Deprecate legacy `setup.py develop` mechanism for `pip install --editable`

[sbidoul]

Last updated on January 12, 2025.

TL;DR: The -e / --editable pip install option is NOT deprecated. What is changing is the underlying method to achive it. The execution of setup.py develop when pip does an editable install is being repaced by a standardised interface.

UPDATE: The removal has been postponed to pip 25.2 (2025 Q3) as we haven't had the time to ensure all of our ducks are in a row for a smooth transition.

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?

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.1 (Q2 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.1 (Q2 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.1.

[!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.1 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 https://github.com/pypa/pip/issues/8102#issuecomment-1271496237).

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? https://github.com/pypa/pip/blob/2a0acb595c4b6394f1f3a4e7ef034ac2e3e8c17e/src/pip/_internal/req/req_install.py#L829-L842

[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 ♥

[ThiefMaster]

Will this force dynamic import resolution in case of editable packages for everyone? Because this would break quite a few usecases in type checkers and IDEs such as VSCode which do not support (and probably will never support) executing code to map an import name to a filesystem location.

[pfmoore]

Will this force dynamic import resolution in case of editable packages for everyone?

I don't know what "dynamic import resolution" means. If you mean "will it force use of an import hook rather than a .pth file?" then that's not something pip will impose, no. However, setuptools chose to use a different mechanism for PEP 660-style editable installs than the one it used for setup.py develop, and so this change will cause a change in behaviour for setuptools-based projects. If the new method is problematic for you, then I believe there's a config option you can use to ask setuptools to use the old method. Beyond that (if, for example, a config option isn't acceptable for you) this is something you'd need to take up with the setuptools project.

[joshuacwnewton]

Just to clarify one part of the deprecation message:

pip 25.0 will enforce this behaviour change

Does "enforce" mean "throw an error unless pyproject.toml/--use-pep517 are used"? Or does "enforce" mean "--use-pep517 behavior will become the default for pip install -e"?

Asking because I have python -m pip install -U pip + pip install -e . in some old installer scripts, and I want to know if there's a risk that pip==25.0 will break these old install scripts, and if I have to backport --use-pep517. (If there's no error, and the default behavior changes, then I believe we should be fine to leave those commands as-is.)

[sbidoul]

Or does "enforce" mean "--use-pep517 behavior will become the default for pip install -e"?

@joshuacwnewton this ^

[hunterhogan]

Or does "enforce" mean "--use-pep517 behavior will become the default for pip install -e"?

this ^

^ this "improvement" is on-brand for the most powerful language you can still read: replacing --editable with the less-ambiguous --use-pep517.

[BenjaminHamon]

Would it be possible to have a clarification on what developers are expected to do when faced with the deprecation warning? Reading PEP-660 and the setuptools documentation hasn't helped my understanding.

It doesn't appear the --editable option is going away, despite what the deprecation message states, so what is changing exactly? Or rather, are some of its usage expected to break with some pip or setuptools upgrade?

Are we meant to understand we should add --use-pep517 to make sure everything still works, when it seems to pertain only to the build backend, and when it will be the default in pip 25 and thus won't be needed anymore? Or are we to understand we should use pyproject.toml over setup.py for one reason or another?

Adding --use-pep517 fixes the warning but it feels like I'm enabling a future something rather than updating an obsolete something.

Thanks <3

[ThiefMaster]

I think "just switch to pyproject.toml and hatchling instead of setuptools" in the affected project will do the job in almost all cases...

[ichard26]

Would it be possible to have a clarification on what developers are expected to do when faced with the deprecation warning?

Sorry for taking so long, but here you go @BenjaminHamon.

---

Hi, you probably reached this issue because you encountered a deprecation warning about legacy editable installs. Please read below for details and possible solutions.

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.

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 not support or function correctly under an editable install using the modern mechanism, pip install -e will break starting with pip 25.0.

What should I do?

There are several things you can do:

1. 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"

1. Or 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.

[!TIP] If the resulting 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.

[!TIP] Which solution you choose to use depends on the project, but option one is recommended as there are other benefits to adding a pyproject.toml file. For example, you can declare your project metadata in pyproject.toml. If your project already works fine using the modern mechanism, option two is an acceptable way to silence the deprecation warning in the meanwhile.

---

@pypa/pip-committers I'd appreciate if the issue description was edited to display this message instead of what's up right now (here's a link to a Gist with the raw Markdown). Yes, this is way, way longer, but for better or worse, I think providing at least some background knowledge and the reasoning behind this change is required to understand this deprecation as it involves a highly technical and usually hidden part of Python packaging. I would edit the issue myself, but I don't have the permission to do that :)

[uranusjr]

I’ll do the edit.

[timmc-edx]

Does this mean that pip install -e on older packages will start failing for pip 25+? (Where "older" here means "hasn't had any of the above changes/workarounds applied".) I'm thinking of cases where packages can be upgraded, but people nevertheless need to install older versions (for compatibility, bisection-style debugging, etc.)

[ichard26]

@timmc-edx The key phrase is that things will break if your package is already broken when the modern editable install mechanism is used. The breakage possible with pip 25 is that the automatic fallback that keeps those packages working will be removed.

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).

I guess a valid third "solution" is simply to do nothing. If the package functions correctly under the modern editable install mechanism (you can verify that by forcing the modern mechanism via --use-pep517), then great. When the legacy mechanism is entirely removed in pip 25, the warning will go away and the modern mechanism will be used instead, transparently. Is this something we should recommend? No, I don't believe so. Projects should really start using the modern packaging standards, including pyproject.toml, as they do offer a better experience (especially if you want to use alternative tools, like uv)[^1]. The main reason to do nothing would be with legacy, read-only projects or archives as you've mentioned.

In essence, "it depends" is the answer. If you can, the pip team strongly recommends migrating to the supported and standardized solutions, but doing nothing can be a valid path forward. Also, older versions of pip can be used when needed.

[^1]: Of course, the transition is inevitably a bit painful and there are issues with gaps in the standards, but the standards are here to stay.

[potiuk]

Comment from a side. I am really sorry for it to be a long message, I just wanted to provide a bit more context. So for those who would like to get the gist of it here is TL;DR;.

TL;DR; while I would love to see the legacy support removed in 25.0. I think it would be worth to think about one more escalation step that will allow package developers to use "user pressure" to make sure their dependencies are also migrated to modern standards - namely to change current warnings into error and allow the user to "opt-in" to use the old mechanism for some time.

I am not sure - maybe it is already planned - after reading very carefully the entirely thread I think we are going to go straight from "warning" to "remove support" - but I could have missed it or misunderstand it, so wanted to raise it here.

I think this would be the "right escalation path" - for example change to opt-in in 24.3 and complete removal in 25.0 (or maybe 25.1 or 25.2 or even do it with 25.0 (opt-in) followed by 26.0 (removal) scenario.

Similar approaches were taken in the past in pip (--use-legacy-resolver) and it's been a preetty successful (even if at times painful) process.

Why I think it would be good to follow this path?

Because there is only as much package developer can do as to convert their own package to use modern standards (for example we did it in Airflow with https://github.com/apache/airflow/pull/36537 for example. But when you have a lot of dependencies, convincing them and their dependencies and their dependencies to modernize is a long process and unless there is a really strong incentive, you have very limited impact on that.

I think in many cases 'supply chain' issues are "people's/maintainers" bound not "tooling bound" and the more we enable the right people to communicate and teach each other - the better. For example push-down the efforts to modernize things where higher-layer dependencies will fill incentive and need to reach out to the 'lower layer" dependencies in dependency tree, the more effective such transition will be.

The problem with creating thie incentive is that currently the "warnings" are mostly for "end-users". While maintainers can fix their own project setup, they are rarely aware that any of their dependencies (including transitive ones) has such problems. Mainly because in most cases the pre-packaged .whl files are available, there is no need to build the packages when you install even 100s of your dependencies - especially if you are using modern distros. And you will not even be aware how many and which of your dependencies need to be reached out to (and maybe even helped with) to fix it. Because often times users who experience that (for example using some old distros or requiring for some reasons older versions of those packages) just plainly ignore the warnings and you are not even aware of it as package maintainer.

So, what will it change if we turn the warnings into errors and allow the user to "opt-in" to remove them.

IMHO - a lot. What will happen in most cases, the users's installation wil break, they will see the error message that will suggest them to raise an issue to the package that is problematic, or switch to the "opt-in" - but that one could clearly say - "this will stop working on that date or version of pip". In many cases those users will not really reach out to the problematic packages, but they will open issue with the package they tried to install in the first place (say "apache-airflow" - we have 700+ dependencies in total and it's very, very likely some of them will fail to install, people will open an issue for Airflow. And this is precisely what we want to have. We want to have a notification that some of our users have problems with some of our dependencies (and we want to have those engaged users who want to get the problem solved), so that we can do some actions there - as "airflow" maintainers. And we will have quite a few options then:

• We can help the user telling them to use the "opt-in" flag. This is what we will not have if "opt-in" legacy behaviour is not available. With the right warning, this will have clear expiry date and will allow us to follow up with the "dependent" packages.

• We can tell them to use older pip version. This is something we would like to avoid, because this one has no "clear expiry date" (use it for as long as you want ??? or what?).

• We can also reach out (or ask the user to do so) to reach out to the "offending" dependency. Having clear expiry date and having an "end-user" who complains is as strong of a incentive and "pressure" you can put on the dependency

• We can also offer the dependency to help them to migrate and tell them how, open a PR with it, etc. etc. This is especially if we see that they need help. This is something I am currently doing as a new project (together with @sethmlarson and Alpha-Omega) where we will eventually analyse and if needs be reach out to ALL dependencies of Airflow in order to improve their processes and security status. This is rather new and experimental project which we call "Airflow Beach Cleaning" where we attempt to see if improving the whole "supply chain" security of a significant/important part of the ecosystem is possible this way (I am going to talk about it in two days at the Airlfow Summit Keynote in San Francisco - together with Michael Winser from Alpha-Omega - https://airflowsummit.org/sessions/2024/security-united-collaborative-effort-on-securing-airflow-ecosystem-with-alpha-omega-psf-asf/. I think this might be one of the most efficient way where we can "trickle-down" the modernizing efforts - by packages having an incentive and even helping their dependencies, and their dependencies helping their dependencies and so on... I hope in 6-12 months we will have result of the experiment and we will be able to share some learnings and blueprints.

• Finally - the last option we will have - if the "offending" packages will be unresponsive/unwilling to even get help - this will give us (higher-level package maintainers) - time to search for alternatives. By giving the user the option to use the "opt-in" flag and a clear "expiry date" - we will have a pressure on us, to solve the problem and either replace or vendor-in the dependencies that will be problematic for our users.

So, summarising - I think it would be great to consider one step escalation process (error out with opt-in to enable old behaviour back) as this will give a chance for this kind of "trickle-down" effort to be less disruptive.

[edmorley]

@potiuk What you are saying makes sense for wider-reaching changes like the historic switch from the legacy resolver, however, I don't think it's as applicable here. Since:

1. This deprecation is only for packages installed in editable mode (which is typically only the top level package, not the hundreds of transitive dependencies case mentioned above)
2. As far as I understand it, the ~removal will most likely be to instead to fall back to the isolated build environment mode, which will automatically install newer setuptools (via the fallback build backend, used for packages that don't have a build backend declared in pyproject.toml, since they haven't migrated from setup.py yet) which already supports PEP-660, and therefore for most cases I would imagine these legacy packages would continue to just work - even if they haven't been updated to use pyproject.toml.

In general, I would like us to enable build isolation by default soon (whilst still allowing a way to opt out, like uv does) - I think in fact that change doesn't need to wait for this one to be complete. I've just added a comment about that here: https://github.com/pypa/pip/issues/9175#issuecomment-2336684758

[ichard26]

I can't edit the post, but just as a friendly reminder to all, 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 (i.e. pip won't be calling the CLI interface provided by setup.py such as setup.py develop). Going forward, pip is going to exclusively use the standardized mechanism for editable installs (PEP 660) which pip and setuptools already support and use.

What's tricky here is that pip defaults to using the legacy setup.py develop mechanism when the pyproject.toml is not present. 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.

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 in the issue description, 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, but please, add a pyproject.toml if you can because it makes all of our lives easier :)

[potiuk]

@potiuk What you are saying makes sense for wider-reaching changes like the historic switch from the legacy resolver, however, I don't think it's as applicable here. Since:

What you wrote makes perfect sense. Thanks for explaining in detail. Yeah - what you describe makes perfect sense and my concerns are addressed. Going with straight removal should be fine.

[ichard26]

Original comment: https://github.com/pypa/pip/issues/11457#issuecomment-2339037577

I can't edit the issue description as always, but as a regular reminder to all, 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 (i.e. pip won't be calling the CLI interface provided by setup.py such as setup.py develop).

However, at the bare minimum, please add a pyproject.toml with the build backend declared as it is the glue that enables various packaging tools, from old and new, to work together. Whether you migrate entirely off setup.py is a separate decision. If you are able, of course, you can certainly get rid of setup.py in many situations and benefit from other improvements in packaging, but that isn't required to address this specific deprecation.

[jmccreight]

Thanks @ichard26 for the additional clarification.

As far as I can tell, there is currently no way to test the behavior of pip 25.0+ while also keeping a setup.py: if you have setup.py you will necessarily get a deprecation warning. Can someone confirm that?

It would be nice option of pip 25.0+ behavior for editable installs so we can both be more confident and quash the depreciation warning.

[notatallshaw]

if you have setup.py you will necessarily get a deprecation warning. Can someone confirm that?

That doesn't sound right? I'm not an expert here, but I have projects with a pyproject.toml with the build backend pointed to setuptools, and a setup.py, and I don't get a deprecation warning

[jmccreight]

Thanks for confirming! I had SETUPTOOLS_ENABLE_FEATURES="legacy-editable" set in my environment, which I'd totally forgotten about. When I remove that, I dont get the deprecation warning with setup.py in place. Maybe this will save someone the same confusion.

[brando90]

Sorry to jump in, but this looks complicated. For naive users that don't really care about how it's done, does it mean that the command I've run for years:

pip install -e .

won't work anymore?

[ichard26]

No.

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

[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...