Local project installs#

It is extremely common to have a project, available in a folder/directory on your computer [1] that you wish to install.

With pip, depending on your usecase, there are two ways to do this:

  • A regular install

  • An editable install

Regular installs#

You can install local projects by specifying the project path to pip:

$ python -m pip install path/to/SomeProject

$ python -m pip install path/to/SomeProject

C:> py -m pip install path/to/SomeProject

This will install the project into the Python that pip is associated with, in a manner similar to how it would actually be installed.

This is what should be used in CI system and for deployments, since it most closely mirrors how a package would get installed if you build a distribution and installed from it (because that’s exactly what it does).

Editable installs#

You can install local projects in “editable” mode:

$ python -m pip install -e path/to/SomeProject

$ python -m pip install -e path/to/SomeProject

C:> py -m pip install -e path/to/SomeProject

Editable installs allow you to install your project without copying any files. Instead, the files in the development directory are added to Python’s import path. This approach is well suited for development and is also known as a “development installation”.

With an editable install, you only need to perform a re-installation if you change the project metadata (eg: version, what scripts need to be generated etc). You will still need to run build commands when you need to perform a compilation for non-Python code in the project (eg: C extensions).

Caution

It is possible to see behaviour differences between regular installs vs editable installs. These differences depend on the build-backend, and you should check the build-backend documentation for the details. In case you distribute the project as a “distribution package”, users will see the behaviour of regular installs -- thus, it is important to ensure that regular installs work correctly.

Note

This is functionally the same as setuptools’ develop mode, and that’s precisely the mechanism used for setuptools-based projects.

There are two advantages over using setup.py develop directly:

  • This works with non-setuptools build-backends as well.

  • The “.egg-info” directory is created relative to the project path, when using pip. This is generally a better location than setuptools, which dumps it in the current working directory.

Build artifacts#

Changed in version 21.3: The project being installed is no longer copied to a temporary directory before invoking the build system, by default. A --use-deprecated=out-of-tree-build option is provided as a temporary fallback to aid user migrations.

Changed in version 22.1: The --use-deprecated=out-of-tree-build option has been removed.

When provided with a project that’s in a local directory, pip will invoke the build system “in place”. This behaviour has several consequences:

  • Local project builds will now be significantly faster, for certain kinds of projects and on systems with slow I/O (eg: via network attached storage or overly aggressive antivirus software).

  • Certain build backends (eg: setuptools) will litter the project directory with secondary build artifacts (eg: .egg-info directories).

  • Certain build backends (eg: setuptools) may not be able to perform with parallel builds anymore, since they previously relied on the fact that pip invoked them in a separate directory for each build.