Using Emacs Desktop Mode with Virtualenvwrapper

Emacs desktop-mode lets you save the state of emacs (open buffers, kill rings, buffer positions, etc.) between sessions. It can also be used as a project file similar to other IDEs. This virtualenvwrapper plugin adds a trigger to save the current desktop file and load a new one when activating a new virtualenv using workon.


Install this plugin with pip:

$ pip install virtualenvwrapper-emacs-desktop

Or by unpacking the source distribution and running setup.py directly:

$ tar zxvf virtualenvwrapper-emacs-desktop-X.Y.tar.gz
$ cd virtualenvwrapper-emacs-desktop-X.Y
$ python setup.py install

You may need administrator privileges to install to a global location.

Configuring Desktop Mode in Emacs

Setup of desktop-mode is straightforward:

  1. Run customize-group on the "desktop" group.
  2. Turn desktop-save-mode on to enable the minor mode.
  3. Optionally change the base name for desktop files in desktop-base-file-name. For example, using "emacs.desktop" means the file will not be hidden.
  4. Set a default search path for the desktop file in desktop-path. Use your home directory, or the directory where you keep your emacs configuration files (~/emacs.d or ~/emacs). This value is the default. Your real desktop files will be saved into the virtualenv directories.
  5. Set desktop-save to Always save. There are other values that work, but some require interaction with the editor during the context move to confirm file saves.

There are a few other options that may be useful to tweak, depending on the other features of emacs you use. For example, desktop-clear-preserve-buffers lets you control which buffers are saved when the desktop is cleared on a reload. It may be useful to save the *Messages*, *Org Agenda*, and *scratch* buffers, since those are related to emacs operation and not limited to any one project.


If the emacsclient binary visible on your $PATH does not match the version of emacs you are using, set VIRTUALENVWRAPPER_EMACSCLIENT to the full path of the version to use instead.

export VIRTUALENVWRAPPER_EMACSCLIENT=/Applications/Emacs.app/Contents/MacOS/bin/emacsclient

Enabling the Plugin

Switching desktop sessions every time workon is used would make it impossible to have two shells open and working on separate projects at the same time. Therefore, the plugin must be explicitly enabled in the shell where it should control the emacs session.

Two shell functions (emacs_desktop_controller_on and emacs_desktop_controller_off) are provided to switch the plugin on and off. They do this by changing the variable DESKTOP_CONTROLLER, which the plugin examines before taking any action. If the variable is not set, or is defined but empty, the plugin makes no changes. If the variable is set to any value, the session is changed.

Most modern terminal programs make it easy to create custom configurations with specific settings. Use your terminal's customization feature to create a "desktop controller" configuration with DESKTOP_CONTROLLER set, then control virtualenvwrapper-emacs-desktop from a terminal using that configuration.


The default OS X terminal emulator Terminal.app lets you set up profiles with custom configurations, including running a command when the new window is opened. Create a new profile, then under the Shell tab, set:

Run command:emacs_desktop_controller_on
Run inside shell:


The third-party OS X terminal emulator iTerm lets you set up "bookmarks" with custom configurations, including the "Working Dir". One way to use this to control the plugin is to set up a special bookmark with a working directory set to $WORKON_HOME, then add a check to ~/.bashrc to check for that condition.

Command:bash -l
Working Dir:/Users/username/.virtualenvs

~/.bashrc settings:

if [ "$(pwd)" = "$WORKON_HOME" ]

emacs shell

shell-mode in emacs sets EMACS and INSIDE_EMACS, so you can test for those environment variables.

Gnome Terminal





If you have suggested configuration mechanisms for other terminal emulators or other platforms, please post them in the comments and I will add them to this README file.