How to use editable installs for Python packages

When you install Python packages into a given instance of Python, the default behavior is for the package’s files to be copied into the target installation. But sometimes you don’t want to copy the files—sometimes, you want to link to them, so any installed version of the package can be updated by simply editing the linked source.

This behavior is called an editable install, and it’s a powerful way to make use of a package at the same time you’re editing it. Any changes to the source for the package are instantly reflected everywhere it is installed.

Using editable installs to keep projects in sync

Here’s a common scenario: Let’s say you have a Python project named pythingy somewhere on your system—say, /usr/projects/pythingy or D:/dev/pythingy. You use pythingy as a utility in various other Python projects, but you’re also constantly working on and making changes to pything. It’s a pain to install and update copies of pythingy into multiple virtual environments every time you make a change.

What you really want is to have every virtual environment where you use pythingy just reference the original source directory for pythingy. When you make a change to the original source code, every linked copy is also updated, because they’re just pointers to the original.

Editable installs let you do exactly this.

To install a Python package in editable mode, all you need to do is use the -e flag, and pass the path to the package’s directory:

pip install -e /usr/projects/pythingy

The installation process should be no different. What will change is how the project is referenced when you use pip list on any environment where the project has been installed:

(.venv) PS D:\Dev\pythingy> pip list
Package  Version Editable project location
-------- ------- ---------------------------------
pip      25.1.1
pythingy 0.1     D:\dev\pythingy

The Editable project location path will indicate where the original source is for the installed project. (Unless you have editable-installed packages, you won’t see this column when you run pip list.)

The best part is, you do not need to run pip install --update on the package when you make changes—though there are a couple of exceptions we’ll discuss shortly.

Editable-installing a package into its virtual environment

Another useful practice when working on a project is to make an editable install of the project into its own virtual environment. To do this, just use pip install -e . from the root of the project’s directory.

Adding the project as an editable install to its own environment environment confers a few useful advantages:

• It replicates the behavior an end user has with the project. If we have pythingy installed into its own environment as an editable install, we can test aspects of the project that only show up when it’s been installed—such as entry point scripts (e.g., a pythingy shell command to invoke the package).
• You don’t have to use relative imports in the project itself. If pythingy is present in the namespace for the virtual environment where you’re working on it, you can use pythingy as a top-level namespace to import from. Aside from being unambiguous about where the import’s coming from, it avoids all the difficult-to-debug side-effects that crop up with relative imports. And again, it replicates the behavior the user will have when they install the project into a virtual environment.

Limitations of editable installs

Editable installs do have a few limitations worth keeping in mind.

It’s not recommended to use a remote endpoint (e.g., a remote git repository) for the source of your editable install. In other words, don’t do something like pip install -e git+https://github.com/foo/bar. If you want to use a remote git repo as a source, clone it locally, run pip install -e /path/to/clone, and keep the cloned copy in sync with its remote source.

Additionally, changing the source of an editable install does not automatically re-trigger any build actions for the source. This generally manifests with two key features: entry point scripts, which allow you to launch a Python package with a command from the shell; and Python extension modules, which are compiled (typically from C source). If your edits of the package source change either of these things, you need to re-run the installation process and re-trigger the build step before they’ll be updated: pip install -e -U /path/to/source.