Concepts

The RPC Process

Elpy works by starting a Python process in the background and communicating with it through a basic Remote Procedure Call (RPC) interface. Ideally, you should never see this process and not worry about it, but when things don’t work as expected, it’s good to know what’s going on in the background.

Every project and virtual env combination gets their own RPC process. You can see them both in the process list (M-x list-process) as well as in the buffer list (C-x C-b) as buffers named *elpy-rpc[...]*.

RPC processes are used to provide code completion, documentation and other features. To do so, they use python packages (jedi, yapf, rope, …) that are installed in a dedicated virtualenv (.emacs.d/elpy/rpc-venv by default). Those packages can be updated through the configuration panel (accessible with M-x elpy-config).

By default, Elpy will also find the library root of the current file and pass that to the RPC functions. The library root is the directory from which the current file can be imported.

There are a few options and commands related to the RPC process.

M-x elpy-rpc-restart

Close all running RPC processes. Elpy will re-start them on demand with current settings.

elpy-rpc-python-command (Customize Option)

The Python interpreter Elpy should use to run the RPC process. This defaults to "python", which should be correct for most cases.

Please do note that this is not an interactive interpreter, so do not set this to "ipython", "jupyter" or similar.

As the RPC should be independent of any virtual environment, Elpy will try to use the system interpreter if it exists. If you wish to use a specific python interpreter (from a virtual environment for example), set this to the full interpreter path.

elpy-rpc-virtualenv-path (Customize Option)

Path to the virtualenv used by the RPC.

Can be ‘default (create a dedicated virtualenv .emacs.d/elpy/rpc-venv), ‘system (use the system environment), ‘current (use the currently active environment), a virtualenv path or a function returning a virtualenv path.

If the default virtual environment does not exist, it will be created using elpy-rpc-python-command and populated with the needed packages from elpy-rpc–get-package-list.

elpy-rpc-large-buffer-size (Customize Option)

The size in character starting from which Elpy will transfer buffer contents via temporary files instead of via the normal RPC mechanism.

When Elpy communicates with the RPC process, it often needs to tell Python about the contents of the current buffer. As the RPC protocol encodes all data in JSON, this can be a bit slow for large buffers. To speed things up, Elpy can transfer file contents in temporary files, which is a lot faster for large files, but slightly slower for small ones.

elpy-rpc-pythonpath (Customize Option)

A directory to add to the PYTHONPATH for the RPC process. This should point to the directory where the elpy module is installed. Usually, there is no need to change this.

Backends

For introspection and analysis of Python sources, Elpy mainly relies on Jedi, a python package for static code analysis.

Due to the dynamic nature of python and its minimalist structure syntax, python code can be difficult to understand in certain situations. Jedi documentation provides some tips to make jedi job easier.

Virtual Envs

Elpy has full support for Python’s virtual envs. Every RPC process is associated with a specific virtual env and completions are done based on that environment.

Outside of RPC processes, though, it is not easy to have more than one virtual env active at the same time. Elpy allows you to set a single global virtual env and change it whenever you like, though.

M-x pyvenv-workon
M-x pyvenv-activate
M-x pyvenv-deactivate

These commands are the main interaction point with virtual envs, mirroring the normal activate and deactivate commands of virtual envs and the workon command of virtualenvwrapper.sh.

The pyvenv-workon command will allow auto-completion of existing virtual envs and also supports virtualenvwrapper’s setup hooks to set environment variables.

Elpy won’t pollute your Emacs command namespaces, but it might be an idea to create an alias for the workon command:

(defalias 'workon 'pyvenv-workon)

Modules

As the last concept, Elpy has a number of optional features you can enable or disable as per your preferences.

elpy-modules (Customize Option)

The list of modules to activate by default. See the section on Writing Modules for details on how to write your own modules.