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
Answers:
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 implements PEP 660 as of version 64.
- Flit implements PEP 660 as of version 3.4.
- Poetry implements PEP 660 as of version 1.08.
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.
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.
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
...
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.
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
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 implements PEP 660 as of version 64.
- Flit implements PEP 660 as of version 3.4.
- Poetry implements PEP 660 as of version 1.08.
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.
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.
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
...
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.