86

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
a_guest
  • 34,165
  • 12
  • 64
  • 118

5 Answers5

74

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:

Note: To be able to do an editable installation to your user site (pip install -e --user), you need a system installed setuptools v62.0.0 or newer.

LeopardShark
  • 3,820
  • 2
  • 19
  • 33
  • 2
    Thanks for the good overview and the various suggestions. Eventually I managed to do an editable install via `flit`. – a_guest Oct 25 '21 at 19:54
  • 7
    I find it incredibly confusing that "implements PEP 660" seems to mean "frontend which supports PEP 660-compliant backends". Practically, one needs both the frontend and the backend. The only compliant backend I've been able to find so far is Flit. The Poetry implementation has still not been released. From what I can tell, [pip is just a frontend](https://packaging-the-hard-way.readthedocs.io/en/latest/pep517.html?highlight=frontend#let-pip-build-the-distribution-for-you) There seems to be [no implementation yet for setuptools](https://github.com/pypa/setuptools/issues/2816). – Ben Mares Dec 10 '21 at 14:52
  • 3
    PEP 660 is implemented in [poetry 1.0.8](https://github.com/python-poetry/poetry-core/releases/tag/1.0.8) – dyoll Mar 14 '22 at 20:21
  • 6
    Pip supports editable installs from `pyproject.toml` files since [21.3](https://pip.pypa.io/en/stable/news/#v21-3) – dyoll Mar 14 '22 at 20:27
  • 4
    Maybe [_hatch_](https://pypi.org/project/hatch/), [_pdm_](https://pypi.org/project/pdm/), and [_whey_](https://pypi.org/project/whey/) could be on this list. As far as I can tell, they are all PEP 660-compatible. – sinoroc May 26 '22 at 08:51
  • 1
    Setuptools is working on it! Yet to be merged into main, but the functionality is being implemented on [this branch](https://github.com/pypa/setuptools/tree/feature/pep660) – theo-brown Jun 24 '22 at 09:39
  • https://github.com/pypa/setuptools/issues/2816 is now merged. would be good to know how to use setuptooks with editable install hook in pyproject.toml – Ray Bell Aug 13 '22 at 02:53
  • 1
    To avoid the "system installed setuptools" requirement, you can do a non-isolated build as well (e.g., with `--no-build-isolation`) – Eric Oct 06 '22 at 18:51
  • @Eric's answer worked for me after I followed the accepted answer. The command was `pip install -e . --no-build-isolation` where as `pip install -e --user` kept giving me the error **ERROR: --user is not a valid editable requirement. It should either be a path to a local project or a VCS URL (beginning with bzr+http, bzr+https, bzr+ssh, bzr+sftp, bzr+ftp, bzr+lp, bzr+file, git+http, git+https, git+ssh, git+git, git+file, hg+file, hg+http, hg+https, hg+ssh, hg+static-http, svn+ssh, svn+htt p, svn+https, svn+svn, svn+file)** – Sid Aug 01 '23 at 17:49
41

I stumbled here as I searched for the error string "(A "pyproject.toml" file was found, but editable mode currently requires a setuptools-based build.)"

In my case, all I needed to do was update pip:

python3 -m pip install --upgrade pip

Then the install worked fine.

J. Gwinner
  • 931
  • 10
  • 15
22

Note: This workaround is no longer required. Setuptools supports editable installations since v64.0.0 (Aug 2022). Old answer remains below for people stuck on older setuptools versions for whatever reason...

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.

wim
  • 338,267
  • 99
  • 616
  • 750
  • Thanks! It does seem to work, but why? Do you have any explanation at hand? – jonas May 24 '22 at 07:39
  • 1
    See how [pip checks whether the build backend supports editable installation](https://github.com/pypa/pip/blob/22.1.1/src/pip/_internal/req/req_install.py#L483-L502) – wim May 24 '22 at 23:23
2

As of poetry 1.2.0b3, "current project" is automatically installed in editable mode by default when you run poetry install.

$ pip uninstall virtualenv # or via apt if you installed that way
$ sudo apt install python3-dev python3-pip python3-setuptools
$ wget install.python-poetry.org -o get-poetry.py
$ python3 get-poetry.py --preview
$ cd /you/project/folder
$ poetry install
$ pip list
Package            Version  Editable project location
------------------ -------- -------------------------------------------
...
your-project       0.1.0    /you/project/folder
pip                22.2.2
...
Kashyap
  • 15,354
  • 13
  • 64
  • 103
-2

Found a great resource here:

https://setuptools.pypa.io/en/latest/userguide/quickstart.html#development-mode

pip install --editable .
Marc Keeling
  • 47
  • 5