Configuring GNU emacs with elpy on MacOS

2018-09-29 Kenneth H. East [view page source]

Note on installing and configuring elpy in GNU Emacs 26.1 with Python 3.7 on MacOS Sierra (10.12).

Introduction

Elpy is an extension for the GNU Emacs text editor to work with Python projects. Elpy can be easy to install but, at times, problems can be encountered.

Configure MELPA

We will obtain elpy from the MELPA elisp archive. If your .emacs is already configured to use MELPA, skip this step.

Add the following to your .emacs:

(require 'package)
(add-to-list 'package-archives
             '("melpa-stable" . "https://stable.melpa.org/packages/"))

Restart emacs or reload .emacs.

Install `elpy`

Run M-x package-install RET elpy RET to dowload elpy from MELPA.

When the command completes, add the following to your .emacs:

(package-initialize)
(elpy-enable)

Restart emacs or reload .emacs.

Apply Patches to `elpy`

When this was written, MELPA provided me with elpy 1.17.0. In this version, elpy-config has a bug when used with Python 3.7 (it seems to work properly with earlier Python versions).

The current elpy version on github is 1.24.0. The bug is fixed in this version.

Rather than attempt to install the newer version from github, I chose to patch my local elpy.el with the fix from github -- it is only two lines of code.

After patching ~/.emacs.d/elpa/elpy-1.17.0, I recompiled the file via M-x byte-compile-file RET elpy.el RET.

Without this fix, elpy-config would fail after installing some of the Python packages.

Specifying the virtualenv

Prior to configuring elpy, you must ensure that your venv is set correctly.

elpy uses pyvenv to select virtualenvs. This means that virtualenvwrapper can't be used with elpy. Be sure to disable and virtualenvwrapper initialization, if present, in your .emacs.

For this example, I am using a venv named py37.

Using 'workon'

Set the venv via M-x pyvenv-workon RET py37 RET. Obviously, this relies upon your $WORKON_HOME being set properly by virtualenvwrapper.sh.

Using 'activate'

Alternatively, you can activate a specific venv. My $WORKON_HOME is set to ~/.virtualenvs. I could have activated py37 by: M-x pyvenv-activate RET ~/.virtualenvs/py37.

Automatic Selection

This is a side note / tip, not necessary to configure elpy...

The .dir_locals.el file can be used to automatically set the venv within Emacs for a python project. Typically, the file is placed in the root of a Python project and applies itself to all subdirectories.

For example, the following .dir_locals.el, when placed in the root of a Python project, sets the venv to py37 in the root and all subdirectories:

;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")

((python-mode . ((pyvenv-workon . "py37"))))

Configure `elpy`

N.B.: Ensure your venv is correct. You can check it via: M-: pyvenv-virtual-env-name RET. In my case, it returns "py37".

elpy provides the elpy-config command to simplify configuration. Run it via: M-x elpy-config RET. It may run a few seconds before opening a new buffer.

Install Missing Python Packages

Any Python packages that are required by elpy, but that are not present in the venv, will be displayed near the top of the buffer, just below

The current configuration will be displayed in the top of the buffer. If any of the required Python packages are not present in the venv, they will be shown as missing in the configuration.

When packages are missing, the buffer will display content that, when clicked, will install the packages into the current venv. To install a package, click on '[run]' in the buffer.

Of course, all of these packages could have been installed in the venv using 'pip', without using Emacs or elpy-config.

Configuring `elpy`.

elpy has a large number of options that can be configured. The remainder of the buffer provides the ability to tweak these options.

KHE