pip "Project ... does not support editable installs" (PEP 660)

By Daniel Zoghalchali·Latchkey

pip install -e . needs the project’s build backend to implement the PEP 660 build_editable hook. An old backend (or one that never added editable support) cannot produce an editable wheel, so pip refuses.

What this error means

pip install -e . fails with ERROR: Project file:///path does not support editable installs or a Backend does not support build_editable message. A regular pip install . of the same project works.

ERROR: Project file:///home/runner/work/app does not support editable installs.
Hint: the build backend does not implement the optional 'build_editable' hook.

Diagnose it: which Python, and which index?

A pip failure in CI is usually about the interpreter or the index rather than the package. Runners have several Pythons installed, and the one on PATH is not necessarily the one your virtualenv or your workflow selected.

which -a python python3 pip pip3
python -c "import sys; print(sys.executable, sys.version)"
pip config list
pip debug --verbose 2>/dev/null | grep -i "compatible tags" | head -5

Common causes

Build backend predates PEP 660

Editable installs were standardized in PEP 660. A backend pinned to an old version - or one that never implemented build_editable - cannot build an editable wheel.

Old setuptools without editable_wheel

setuptools gained PEP 660 support in 64.0. On an image with older setuptools, pip install -e . falls back and fails instead of using the modern editable path.

How to fix it

Upgrade the build backend

For setuptools projects, a current setuptools implements PEP 660. Upgrade the build frontend and backend first.

python -m pip install --upgrade pip "setuptools>=64" wheel
pip install -e .

Declare a PEP 660-capable backend

Make sure [build-system] names a backend version that supports editable builds.

[build-system]
requires = ["setuptools>=64", "wheel"]
build-backend = "setuptools.build_meta"

Fall back to a non-editable install

If you cannot upgrade the backend, a plain install still works for CI that only needs the package importable (you lose live source editing).

pip install .

How to prevent it

• Pin setuptools>=64 (or a PEP 660-capable backend) in [build-system] requires.
• Upgrade pip/setuptools/wheel as the first CI step.
• Use pip install . in CI when editable mode is not needed.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation