Introduction

Both pip install --editable . and python setup.py develop aim to make a package importable while you edit its source code. The important difference is that pip install --editable . is the modern packaging workflow, while setup.py develop is a legacy setuptools command that bypasses a lot of the behavior developers now expect from pip.

What Editable Installation Means

An editable install makes Python import your package from the source tree instead of from a copied wheel or site-packages directory. When you modify the package code, the next import sees the updated files without reinstalling.

That is useful for local package development, command-line tools under active development, and test environments where you want code changes to appear immediately.

Why pip install -e . Is Usually Better

pip install --editable . uses the packaging toolchain that modern Python projects are built around. It understands dependency resolution, uninstall tracking, virtual environments, and newer build metadata such as pyproject.toml. If the backend supports PEP 660, pip can perform a standards-based editable install instead of relying only on older setuptools behaviors.

Typical usage looks like this:

python -m pip install -e .
python -m pip install -e '.[dev]'

The second command is common when your project defines optional development dependencies such as linters, test runners, or documentation tools.

In contrast, python setup.py develop calls setuptools directly:

python setup.py develop

That still works for many older repositories, but it is tied to setup.py-centric packaging and does not give you the same modern pip workflow.

Practical Differences

The most useful way to compare them is by behavior.

pip install -e .:

• integrates with pip uninstall
• installs dependencies using pip's resolver
• works naturally inside standard virtual environment workflows
• supports modern packaging metadata and build backends more cleanly

python setup.py develop:

• depends directly on setuptools internals
• is mainly for legacy projects built around setup.py
• can behave differently across setuptools versions
• is not the recommended path for new projects

For most active projects, the question is not which one is more powerful. It is whether you want to stay inside the modern packaging toolchain. Usually, you do.

A Minimal Modern Example

Suppose your project has this structure:

1demo_pkg/
2  pyproject.toml
3  src/demo_pkg/__init__.py
4  src/demo_pkg/cli.py

With a pyproject.toml that declares setuptools as the build backend, you can install it in editable mode like this:

1[build-system]
2requires = ["setuptools>=64", "wheel"]
3build-backend = "setuptools.build_meta"
4
5[project]
6name = "demo-pkg"
7version = "0.1.0"
8dependencies = []

Then run:

python -m pip install -e .
python -c "import demo_pkg; print(demo_pkg.__file__)"

The printed path should point back to your source tree, which confirms the editable install is active.

When You Still See setup.py develop

You still encounter python setup.py develop in older tutorials, long-lived internal projects, or repositories that have not been migrated to pyproject.toml. If you are maintaining one of those projects and everything is built around setuptools commands already, it may continue to work for now.

But even in those cases, using python -m pip install -e . is often the safer default because it makes the installation path consistent with how dependencies and environments are handled elsewhere in the Python ecosystem.

Common Pitfalls

One common mistake is assuming the two commands are perfectly interchangeable. They can produce similar results in simple setuptools projects, but they are not the same toolchain and do not always handle metadata, dependencies, or uninstall behavior the same way.

Another issue is running editable installs outside a virtual environment and then wondering why the package seems to leak into unrelated projects. Use a dedicated environment unless you have a strong reason not to.

It is also easy to forget that editable mode reflects source changes, not metadata changes. If you change entry points, dependencies, or project metadata, you may still need to rerun the install command.

Summary

• Both commands aim to make a package editable during development.
• 'python -m pip install -e . is the modern, preferred workflow.'
• 'python setup.py develop is a legacy setuptools-specific command.'
• Pip integrates better with dependency resolution, uninstall, and modern packaging standards.
• For new projects, prefer editable installs through pip and pyproject.toml.