Update 04/08/2014: It seems like this post has been helpful for a lot of people, which really makes me happy! I just wanted to let new readers coming by know that the configuration I present in this post is out-of-date. However, I have my Emacs configuration on GitHub, and do try to keep it up-to-date. If you have any difficulties getting the configuration in the GitHub to work, please do submit a bug request and I will try to help you fix the problem.
As I mentioned in last week’s post, I am a heavy Emacs user and find it invaluable as an environment for my research. In particular, I use Emacs most for data analysis and modeling in Python, including an interface to IPython, which allows me to quickly switch between writing and running snippets of code. This proves to be a great replacement MATLAB, at least in my opinion.
I frequently get requests for my .emacs configuration file or questions about how I have such an environment set up. As such, in this post I’m going to document how to set up your Emacs configuration to support rapid Python development, including the plugins I have installed and the keyboard shortcuts I use most often.
Note that I am running GNU Emacs 23.3.1 (x86_64-pc-linux-gnu, GTK Version 2.24.5). I have never tried running it under OSX or Windows, so I can’t guarantee that these instructions will transfer, but you are welcome to try. If you run into any inconsistencies, feel free to send them to me and I will update this post accordingly!
Also, if you are new to Emacs, please read my beginner’s guide first, as I will be assuming familiarity with basic Emacs functionality and terminology. I will also assume you can at least read and understand LISP to some extent (but you don’t necessarily have to be able to write it).
In this tutorial, we’re going to be installing several Emacs plugins
and modifying the Emacs initialization file, which is typically found
~/.emacs. Here are my .emacs and configuration files that it
includes (note these are NOT the same as the actual plugins: I just
like to divide my configuration so into bite-sized chunks so it’s
easier to manage):
You can find a zip of all these
.el files (excluding the .emacs)
here. EDIT: The most recent version of my emacs configuration
(which might not necessarily be consistent with this post) can be
If you choose to install these configuration files, place the .emacs
in the root of your home directory (
~/.emacs) and put the other
A note about installing plugins: I’ve found that installing plugins
from the Ubuntu repositories to be a bad idea because different
versions don’t always play nicely with one another. It’s better to
install the most recent version from source, and that’s what I’ve done
for this tutorial. If you download and install the plugin versions (as
I’ve indicated via the directories that I install them into), this
should all work. Note that you may have to actually compile some of
the plugins as well (if there’s a Makefile, run
make; sudo make
install and if there’s a setup.py file, run
sudo python setup.py
install. If there’s both, run the Makefile first and then run the
Here is the list of plugins we’ll be going through/installing:
- Interactively Do Things (included by default)
- Auto-complete (version 1.3.1)
- Fill column indicator (version 1.83)
- IPython (version 0.14)
- Python mode (version 6.0.11)
- Pymacs (version 0.25)
- Ropemacs (version 0.7)
- Highlight current line (version 0.57)
- Color theme (version 6.6.0)
There are several plugins that I use which aren’t related to Python
coding, but are nonetheless very valuable:
“Interactively Do Things”), general auto-completion, and the fill
Interactively Do Things
“Interactively Do Things” (a.k.a. ido) is a plugin that should
be included in Emacs by default; however, it is not typically enabled
by default. You can enable it by running
M-x ido-mode in Emacs, or
by adding the following lines to your .emacs customization file:
Ido is handy because it makes switching between buffers, opening/closing files, etc., extremely easy to do. Here’s a few screenshots of what it looks like to switch buffers; notice that it lists in the minibuffer all the different buffers you could switch to:
The *scratch* buffer is bolded, which means it’s the default. Let’s say I want to switch to *Messages*, though. As I start typing the name, the list of buffers in the minibuffer is updated to show only those that match what you’re typing (filtering) by:
I could, at this point, simply press enter and it would switch to the *Messages* buffer. You get similar functionality when searching for files, killing buffers, etc. Saves a lot of time, not having to remember buffer names exactly and not having to fully type them out!
There’s a lot more to ido that I’m not going to go into; I encourage you to read through the documentation and find out more about it.
Auto complete is another handy plugin which keeps track of recent things you’ve typed and will offer to auto complete them for you. Let’s say I’m editing a python file:
And now I want to print out one of the arrays I just created. As I start to type, a list pops up with suggestions:
I can use the arrow keys to highlight the selection I want and press enter to choose it.
The variable name is completed and I don’t have to type the rest, similar to the auto-completion behavior you’d see in Eclipse or another popular IDE. This is useful even if you don’t have competing variable names — if you have particularly long names, auto-complete will remember them, too, and you will only need to type the first few characters.
To enable auto complete, download it, install the files into
~/.emacs.d/auto-complete-1.3.1/, and add the following lines to your
1 2 3 4 5 6
It is good coding etiquette to keep lines short (e.g., no longer than 72 characters — this is because some people use 80 character terminals, and constantly scrolling to the left/right is very annoying!). It’s furthermore just nice coding style to have lines a consistent length.
To let myself know when I’m running over line length, I have the
fill column indicator plugin installed. This draws a line on the
right side of the screen, indicating the “fill column” (which is just
another way of saying “the ideal maximum line length”). If my text
runs past this line, I know I need to do some formatting to make it
span multiple lines (if I’m just writing text, I will use
To enable this plugin, download it and install the file in the
~/.emacs.d/fill-column-indicator-1.83/ directory, then add the
following to your .emacs:
1 2 3 4 5
Ok, moving on to the actual Python configuration now! First off, you’ll (of course) need to have Python installed. I’m currently running 2.7. You’ll also want to install IPython and I recommend you avoid the version in the Ubuntu repositories because it’s out of date. You can download a newer version here; I am currently running a development version of 0.14.
Second, you’ll need to actually download the
plugin and install the files into
~/.emacs.d/python-mode-6.0.11/. Add the following to your .emacs:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
Now open up a Python file and hit
C-c !. Another window will be
created, and in it should be an IPython interpreter:
(I’m not entirely sure what’s up with the multiple
In prompts at the
beginning, but it doesn’t seem to matter so I haven’t bothered to
investigate it as of yet.)
Not only can you run IPython inside of Emacs, but you can actually send code from the file you’re editing to the interpreter. To evaluate a snippet of code, first select a region:
C-c | to send it to IPython:
Now that the code’s been executed, you can refer to it in the IPython environment:
You can also send an entire buffer at once with
python-mode also offers integration with IPython for tab
completion. So, if you can’t quite remember the name of a function,
just type what you can think of into the interpreter and press
TAB. For example, if I type
np.array and then TAB, a new buffer is
created and shows the possible completions:
I actually dislike this behavior, however: my coding style is to have
two windows open at once and to rapidly switch between them with
o. To have Emacs open a second window (or use an existing second
window) and to maintain focus in the IPython interpreter, I’ve
commented out the following lines in the
1 2 3 4 5 6 7 8 9 10 11 12
This leads to behavior that instead looks like this:
Pymacs and ropemacs
Another handy set of plugins are Pymacs and ropemacs. To be honest, I don’t use them as much as I should — I’m hoping this post will re-familiarize me with the basic commands and I’ll start using them more!
Anyway, you probably don’t really need to worry about what Pymacs is: it’s an interface between Python and Emacs LISP, but we won’t be directly using that. What it’s necessary for is rope, which is a non-Emacs-specific Python refactoring library. Ropemacs is just the Emacs plugin for rope.
To install, first install rope itself:
sudo aptitude install python-rope
1 2 3 4 5 6 7 8 9 10 11 12
There’s a lot that you can do with ropemacs — if you’re interested in finding out more, read the README that’s included in the source — but here’s a taste to get started. The first time you run a ropemacs command in an instance of Emacs, you will be prompted to specify your rope project folder. If you only have one folder for your project, just select that; if you have a whole module, choose the root module directory.
Ok, first, better autocompletion: where auto-complete will only keep
track of what you have recently typed, ropemacs can actually look up
method and variable names from a module. Use
M-/ to bring up a list
of completions in the minibuffer (note again the helpfulness of
(Note that it’s not perfect; it seems to have trouble, for example,
finding the correct completions of
np.random.n. IPython doesn’t have
this trouble, probably because ropemacs doesn’t actually import the
module and so does not correctly obtain all the attributes.)
You can also look up documentation of an attribute if the point is
over it with
And you can rename attributes/refactor code in not just a file, but
your entire project. For example, to rename
r r and when the point is over the attribute you want to rename. Then
type in the new name:
Hit enter, and you will be presented with a list of options (you can read about what they all do in the documentation). We just want “perform” here, so press enter again.
Voila, all instances of
data are now renamed to
This is more powerful than just a simple find-and-replace: for
example, if you have a variable named
data and another variable
data_array, you can’t just find-and-replace
something else, because it will likely affect
data_array as well!
For the final part of this post, I’m just going to give you my elisp code for more aesthetic modifications. A fair amount of it is just the color scheme, but there are a few other useful options that I usually want to have set (like disabling the menu bar, scroll bar, and tool bar). I’ve tried to document it well, but am happy to clarify anything if it’s not obvious! Here’s a screenshot of how my typical Python Emacs environment looks:
You’ll notice that the current line (where the point is) is
highlighted; to acheive this affect you’ll need to install the
highlight current line plugin to the
~/.emacs.d/highlight-current-line-0.57/ directory and use the
configuration below in the “cursor” section.
For the base color them, you’ll need the color theme
plugin. Install it to
~/.emacs.d/color-theme-6.6.0/ and, again, use
the configuration below in the “color theme” section.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158