Deprecate pip install --editable calling setup.py develop

[sbidoul]

Last updated on December 20, 2024.

There is now a standardized mechanism for an installer like pip to request an editable install of a project.

pip is transitioning to using this standard only instead of invoking the deprecated setup.py develop command.

What's being deprecated?

TL;DR: the execution of setup.py develop when pip does an editable install. The -e / --editable pip install option is not deprecated.

There is a standardized mechanism (called PEP 660) for an installers to request an editable install of a project. The benefit of this modern mechanism is that it allows projects packaged using other tools (formally called "build backends") such as Hatch and Poetry to support editable installs.

Since pip 21.3, pip has switched to using this mechanism where possible. Now the pip project seeks to deprecate and eventually remove the old and setuptools-specific fallback to running setup.py develop when a pyproject.toml is not present or the PEP 660 mechanism is unsupported for some reason.

If your package is pure Python and follows the src/ layout, the modern mechanism for editable installs will likely "just work" without any major issues. However, pip is issuing a deprecation warning any time the legacy mechanism is used in an effort to warn you that your project may be affected.

Some historical context if you're interested

• Historically, there was no standard way for installers like pip to request an editable install of a project. Thus, the -e / --editable option was implemented as a wrapper over the setup.py develop command. Using this method, only setuptools projects could use editable installs. PEP 660 defines an interface which build backends can implement in order to support editable installs.

• If you are still interested and want more details, they are available on @ichard26's blog post on the changes in pip 24.2. You should read this issue first though!

How will this affect my project?

TL;DR: if your project does not support or function properly using the modern mechanism for editable installs, pip install -e is liable to stop working starting with pip 25.0 (Q1 2025).

If you have received a deprecation warning about a legacy editable install, pip is using the legacy setup.py develop method for performing an editable installation of your project. In practice, this usually means one of two things:

• The pyproject.toml file doesn’t exist at all, thus pip will opt-out of the modern mechanism and use setup.py develop
• The declared setuptools version (in the [build-system].requires field) is too old and doesn’t support PEP 660, i.e. anything older than setuptools 64.0.0

The current plan is that support for legacy editable installs will be entirely removed in pip 25.0 (Q1 2025). If your package doesn't support or function correctly under an editable install using the modern mechanism, pip install -e will break starting with pip 25.0.

Note

If your package works fine with the modern editable mechanism (you can verify this by forcing the modern mechanism by passing --use-pep517), your package will continue to work without any changes, even if it currently uses the legacy mechanism for reasons listed above. pip 25 will always attempt to use the modern mechanism, even if the project doesn't have a pyproject.toml file (pip will assume the project needs setuptools to build).

In other words, once the legacy mechanism is entirely removed, --use-pep517 (solution 2 below) will always be ON for ALL editable installations.

What should I do?

There are a couple of choices to address the deprecation warning, depending on your project's needs:

• Add a pyproject.toml to your project, making sure the [build-system] section requires setuptools >= 64, as well as other libraries required to build your project (the equivalent of setuptools' setup_requires parameter). A basic example is included below:

  [build-system]
  # XXX: If your project needs other packages to build properly, add them to this list.
  requires = ["setuptools >= 64"]
  build-backend = "setuptools.build_meta"

• Alternatively, enable the --use-pep517 pip option, possibly with --no-build-isolation. The --use-pip517 flag will force pip to use the modern mechanism for editable installs. --no-build-isolation may be needed if your project has build-time requirements beyond setuptools and wheel. By passing this flag, you are responsible for making sure your environment already has the required dependencies to build your package. Once the legacy mechanism is removed, --use-pep517 will have no effect and will essentially be enabled by default in this context.

• Lastly, nothing. As noted above, if your project already works fine with the modern editable mechanism, it will continue to work in 2025 even when the legacy mechanism is removed. The deprecation warning will disappear, and pip will transparently transition to always using the modern mechanism. This is the preferred solution if making changes to the project is undesirable or impossible (e.g. legacy or read-only projects, static archives, etc.).

Tip

Setuptools has changed how editable installs work when the modern mechanism is used. If your modern installation does not behave correctly, you may want to try the --config-setting editable_mode=compat pip option. Please consult the setuptools documentation for more information.

Important

Please note that the setup.py file itself is not deprecated. Even in 2025, you'll be able to use it to configure setuptools. What's changing that is that pip is not going to special case for setup.py while performing an editable install. Going forward, pip is going to exclusively use the standardized mechanism for editable installs (PEP 660) which pip and setuptools already support and use.

You can keep your setup.py file if you wish. We strongly recommend—at the bare minimum—declaring your package's build backend in pyproject.toml as described earlier (there are benefits, such as, you can declare your project metadata in pyproject.toml), but it is not mandatory. If no build backend is declared, pip will assume you're using setuptools, and as long as the modern editable install mechanism works fine with your package, pip install -e will continue to work. So, old or legacy projects should have a high likelihood of working :)

[pradyunsg]

This is complicated by the fact that numpy and everything that uses numpy.distutils as a build-dependency cannot be built with setuptools >= 60. setuptools v64.0.0 was the first version to add a PEP 660 implementation.

https://numpy.org/doc/stable/reference/distutils_status_migration.html
https://setuptools.pypa.io/en/latest/history.html#v64-0-0

[pradyunsg]

Adding a cross-reference to the idea of dropping support for this, starting Python 3.12+ (circa #8102 (comment)).

This also makes sense since we'd stop install setuptools by default in ensurepip starting with that Python version, and get-pip.py as well, I imagine.

[edmorley]

Is it worth adding a deprecation message for the setup.py develop fallback in the next Pip release?

[edmorley]

Is here the correct place for the deprecation warning?

pip/src/pip/_internal/req/req_install.py

Lines 829 to 842 in 2a0acb5

	if self.editable and not self.is_wheel:
	install_editable_legacy(
	global_options=global_options if global_options is not None else [],
	prefix=prefix,
	home=home,
	use_user_site=use_user_site,
	name=self.req.name,
	setup_py_path=self.setup_py_path,
	isolated=self.isolated,
	build_env=self.build_env,
	unpacked_source_directory=self.unpacked_source_directory,
	)
	self.install_succeeded = True
	return

[uranusjr]

I think so, either this or inside install_editable_legacy

[sbidoul]

Is it worth adding a deprecation message for the setup.py develop fallback in the next Pip release?

@edmorley I personally think so yes.

A question I have is if the deprecation message should mention that --config-setting editable_mode=compat exists for maximum compatibility.

[edmorley]

I've opened #12830 to add the deprecation warning for the setup.py develop fallback.

[sneakers-the-rat]

Nice work yall ♥

[tomasstolker]

Another naive pip user here... I tried all the different flag combinations that are suggested here, but I can't use the development mode anymore. Is there a clear instruction somewhere how to get it to work? It is a pity this really handy feature has been deprecated...

[pfmoore]

@tomasstolker Editable installs have not been deprecated. Did you read the initial post here? Does your project include a pyproject.toml requiring a sufficiently new version of setuptools? If so, you should have no problem. If not, then that’s all you have to change.

Without knowing what you did and what happened, it’s hard to offer any further information.

[tomasstolker]

Sorry I meant a change in how the development mode is used. I did read the initial post and tried out the suggestions on how to get it to work again. Also including this in my pyproject.toml:

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

I am using setuptools 65.5.0, pip 24.3.1, and Python 3.11. Any idea what the issue could be?

[pfmoore]

Not without knowing what you did, and what pip’s output was, no. Ideally run pip with verbose output switched on, as that gives extra information.

[tomasstolker]

This a cropped version of some of the pip install -e . output:

Installing build dependencies ... done
Checking if build backend supports build_editable ... done
Getting requirements to build editable ... done
Preparing editable metadata (pyproject.toml) ... done
Building editable for calistar (pyproject.toml) ... done
Successfully built calistar
Installing collected packages: calistar
Successfully installed calistar-0.1.0

After this installation, when I make a change to the code, it is not recognized. It is only included in the installation if I do pip install . each time I have changed something.

In the verbose output I do not see anything that may point at a problem but happy to share more details!

[pfmoore]

OK so pip did the editable install. You need to check with setuptools. They use a different editable install approach in newer versions - maybe that’s the issue?

[tomasstolker]

Okay that could be, but it is beyond my understanding of these tools...

I tried a few different versions of setuptools but still no success.

[pfmoore]

Sorry it's frustrating - it's frustrating to us as well that setuptools changed how they implement editable installs at the same time as we switched to the new approach for calling setuptools. It makes it much harder to know what's a problem with pip and what's a problem with setuptools. In this case, it the pip output clearly shows that we correctly installed the package in editable mode, so your best bet is to open an issue in the setuptools project - hopefully they will be able to help you.

[ichard26]

Hi all, if you're still confused about what to do with this deprecation warning, I've updated the issue description to include more information for common questions:

• What if the project is legacy, read-only, or making changes to it is impossible/undesirable? As long as your project already behaves correctly under the modern editable mechanism (you can force it via --use-pep517), pip install -e will continue to work, even if there is no pyproject.toml.
• Is the setup.py file itself deprecated? No.
• This is really complicated, will my simple project will continue to work? Probably. -e is not going anywhere and for many pure Python projects, the modern mechanism will probably "just work" (although there may be issues as setuptools has changed how they implement editable installs under the hood when the modern mechanism is in use).