Post

pip install -e and Editable Installs

Learn how pip and pyproject.toml work together in modern Python packaging. Understand installation flow, build systems, and best practices.

Editable installs (pip install -e) are essential for Python developers working on packages under active development.

But the how of this feature has evolved significantly in recent years — moving from setup.py develop and .egg-link to modern PEP 660-compliant editable wheels.

What is an Editable Install?

When you run pip install -e . You’re telling pip: “Install this package in editable (or development) mode.”

This means:

  • Python will import the code directly from your source directory,
  • Not install it into site-packages,
  • And reflect any source code changes instantly, without reinstalling.

Perfect for package development or contribution workflows.

Legacy vs Modern Editable Installs

Legacy Method: setup.py develop

  • Creates an .egg-link file in site-packages
  • Adds a .pth file (if needed) to include your source directory in sys.path
  • An .egg-link file pointing to your source directory
  • .pth files to add your source to sys.path

Used by setuptools<=64 via:

1
python setup.py develop

Or by pip internally when a fallback is triggered. Edits in source take effect immediately Dependencies were sometimes installed via easy_install, which is now deprecated

Modern (Post-PEP 660): Editable Wheels

Starting with PEP 660, editable installs are now standardized and wheel-based.

Backend Requirements

  • Must implement the following hooks:
    • build_editable
    • prepare_metadata_for_build_editable

pip (Frontend) Behavior

  • Builds a virtual editable wheel
  • Writes files like:
    • __editable__<pkg>.pth – Adds source directory to sys.path
    • __editable__<pkg>_finder.py – Dynamic import hook
    • direct_url.json – Marks source + editable state in .dist-info

Supported in: pip >= 21.3 ,setuptools >= 64 (along with other that supports and implements the build interfaces PEPs 517)

Understanding __editable__* Files

FilePurpose
__editable__<pkg>.pthAdds your source directory to sys.path
__editable__<pkg>_finder.pyDynamically routes imports using sys.meta_path hook
direct_url.json (in .dist-info)Records that the install came from a local source and is editable

These are pip’s new, standardized way of performing editable installs — completely replacing the old .egg-link mechanism. These act as redirectors to your source tree, instead of copying files like a normal wheel.

1
2
3
4
5
6
7
8
9
10
11
12
13
Example: What Files Are Created?
Assume you install a project with pip install -e . using setuptools 80.

You’ll see in your site-packages/:

markdown
Copy
Edit
__editable__my_pkg.pth
__editable__my_pkg_finder.py
my_pkg-0.1.dist-info/
  ├── METADATA
  ├── direct_url.json

Comparing Real Scenarios

Let’s compare what you might see when installing the same codebase across two different VMs:

VMBuild BackendFiles Created in site-packagesEditable Mode
VM1setuptools >= 64__editable__*.pth, *_finder.py, direct_url.json✅ Modern (PEP 660)
VM2flitpkgname.pth, .dist-info/ only🟡 Legacy fallback

Why the Difference?

  • Because Flit doesn’t support PEP 660 (as of today), pip can’t use the modern editable mechanism and falls back to simpler legacy .pth style.

  • Even if both systems use pip 25.0 and Python 3.13.5, the behavior depends entirely on your project’s build backend.


Why You Might See Different Install Artifacts

FileWhen SeenRole
__editable__<pkg>.pthPEP 660 modeAdds source dir to sys.path
__editable__<pkg>_finder.pyPEP 660 modeRoutes imports using sys.meta_path
direct_url.jsonBoth modesRecords source origin and editable flag
pkgname.pthLegacy mode / fallbackAdds source dir to sys.path
.egg-linkVery legacyAdds source dir (used with setup.py develop)

Force Modern Editable (PEP 660)

Make sure your pyproject.toml looks like this:

1
2
3
[build-system]
requires = ["setuptools>=64", "wheel"]  # using new setuptools or any backend that fits the PEPs built standard
build-backend = "setuptools.build_meta"

How to Debug Editable Installs

  • Inspect your site-packages/ directory
    Look for __editable__*.py, .pth, or .egg-link files
    These indicate how pip performed the install

  • Check your pyproject.toml
    Missing or invalid backend? Pip may fall back to legacy mode

  • Check your backend version:

1
pip show setuptools

Check if the build_editable hook is defined

  • Supported backends: setuptools, Poetry >= 1.2, hatchling

  • Not supported: flit, older Poetry versions

This post is licensed under CC BY 4.0 by the author.