How to install a package using pip in editable mode with pyproject.toml?

Question

When a project is specified only via pyproject.toml (i.e. no setup.{py,cfg} files), how can it be installed in editable mode via pip (i.e. python -m pip install -e .)?

I tried both setuptools and poetry for the build system, but neither worked:

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

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

I get the same error for both build systems:

ERROR: Project file:///tmp/demo has a 'pyproject.toml' and its build backend is missing the 'build_editable' hook. Since it does not have a 'setup.py' nor a 'setup.cfg', it cannot be installed in editable mode. Consider using a build backend that supports PEP 660.

I'm using this inside a conda environment, the following is my version of setuptools and pip:

$ conda list | grep setuptools
setuptools                58.3.0                   pypi_0    pypi
$ python -m pip --version
pip 21.3.1

Answer 1

PEP 660 – Editable installs for pyproject.toml based builds defines how to build projects that only use pyproject.toml. Build tools must implement PEP 660 for editable installs to work. You need a front-end (such as pip ? 21.3) and a backend. The statuses of some popular backends are:

• Setuptools does not yet implement PEP 660.
• Flit implements PEP 660 as of version 3.4.
• Poetry implements PEP 660 as of version 1.08.

Answer 2

As a temporary workaround until setuptools implements PEP 660 (#2816) you can create an empty setup file just for the purpose of the editable installation.

touch setup.cfg
pip install -e .
rm setup.cfg

Note: this is not actually invoking any build_editable hook (which doesn't even exist in setuptools' backend currently), instead it triggers a code path within pip which creates a temporary setup.py and then executes setup.py develop. So it's a "legacy" editable installation, done by putting down a link to the source code in a path configuration file like .venv/lib/python3.XY/site-packages/easy-install.pth. Poetry and flit do similar, except they're creating separate path files like mypkg.pth in the site dir, rather than using lines in easy-install.pth.

Because setup.py develop is a path file hack, the usual caveats of such development installs apply, e.g. it exposes any .py files which happen to be present in the source directory even if they are not actually packaged into a real distribution when creating a release.