Text of peps.python.org › pep-0660 as Styx crawled it on Oct 13, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 660 – Editable installs for pyproject.toml based builds (wheel based) | peps.python.org

PEP 660 – Editable installs for pyproject.toml based builds (wheel based) PEP 660 – Editable installs for pyproject.toml based builds (wheel based) Author : Daniel Holth <dholth at gmail.com>, Stéphane Bidoul <stephane.bidoul at gmail.com> Sponsor : Paul Moore <p.f.moore at gmail.com> Discussions-To : Discourse thread Status : Final Type : Standards Track Topic : Packaging Created : 30-Mar-2021 Post-History : Resolution : Discourse thread Table of Contents Abstract Motivation Rationale Terminology and goals The Mechanism build_editable get_requires_for_build_editable prepare_metadata_for_build_editable What to put in the wheel Frontend requirements Limitations Prototypes Rejected ideas editable local version identifier Virtual wheel Unpacked wheel Copyright Abstract This document describes a PEP 517 style method for the installation of packages in editable mode.

Motivation Python programmers want to be able to develop packages without having to install (i.e. copy) them into site-packages , for example, by working in a checkout of the source repository. While this can be done by adding the relevant source directories to PYTHONPATH , setuptools provides the setup.py develop mechanism that makes the process easier, and also installs dependencies and entry points such as console scripts. pip exposes this mechanism via its pip install --editable option.

The installation of projects in such a way that the python code being imported remains in the source directory is known as the editable installation mode. Now that PEP 517 provides a mechanism to create alternatives to setuptools, and decouple installation front ends from build backends, we need a new mechanism to install packages in editable mode. Rationale PEP 517 deferred “Editable installs”, meaning non- setup.py distributions lacked that feature.

The only way to retain editable installs for these distributions was to provide a compatible setup.py develop implementation. By defining an editable hook other build frontends gain parity with setup.py . Terminology and goals The editable installation mode implies that the source code of the project being installed is available in a local directory. Once the project is installed in editable mode, users expect that changes to the project python code in the local source tree become effective without the need of a new installation step.

Some kind of changes, such as the addition or modification of entry points, or the addition of new dependencies, require a new installation step to become effective. These changes are typically made in build backend configuration files (such as pyproject.toml ), so it is consistent with the general user expectation that python source code is imported from the source tree. The modification of non-python source code such a C extension modules obviously require a compilation and/or installation step to become effective.

The exact steps to perform will remain specific to the build backend used. When a project is installed in editable mode, users expect the installation to behave identically as a regular installation. In particular the code must be importable by other code, and metadata must be available to standard mechanisms such as importlib.metadata . Depending on the way build backends implement this specification, some minor differences may be visible such as the presence of additional files that are in the source tree and would not be part of a regular install.

Build backends are encouraged to document such potential differences. The Mechanism This PEP adds three optional hooks to the PEP 517 backend interface. These hooks are used to build a wheel that, when installed, allows that distribution to be imported from its source folder. build_editable def build_editable ( wheel_directory , config_settings = None , metadata_directory = None ): ... Must build a .whl file, and place it in the specified wheel_directory .

It must return the basename (not the full path) of the .whl file it creates, as a unicode string. May do an in-place build of the distribution as a side effect so that any extension modules or other built artifacts are ready to be used. The .whl file must comply with the Wheel binary file format specification (PEP 427). In particular it must contain a compliant .dist-info directory. Metadata must be identical as the one that would have been produced by build_wheel or prepare_metadata_for_build_wheel , except for Requires-Dist which may differ slightly as explained below.

Build-backends must produce wheels that have the same dependencies ( Requires-Dist metadata) as wheels produced by the build_wheel hook, with the exception that they can add dependencies necessary for their editable mechanism to function at runtime (such as editables ). The filename for the “editable” wheel needs to be PEP 427 compliant too. It does not need to use the same tags as build_wheel but it must be tagged as compatible with the system.

If the build frontend has previously called prepare_metadata_for_build_editable and depends on the wheel resulting from this call to have metadata matching this earlier call, then it should provide the path to the created .dist-info directory as the metadata_directory argument. If this argument is provided, then build_editable MUST produce a wheel with identical metadata. The directory passed in by the build frontend MUST be identical to the directory created by prepare_metadata_for_build_editable , including any unrecognized files it created.

An “editable” wheel uses the wheel format not for distribution but as ephemeral communication between the build system and the front end. This avoids having the build backend install anything directly. This wheel must not be exposed to end users, nor cached, nor distributed. get_requires_for_build_editable def get_requires_for_build_editable ( config_settings = None ): ... This hook MUST return an additional list of strings containing PEP 508 dependency specifications, above and beyond those specified in the pyproject.toml file, to be installed when calling the build_editable hooks.

If not defined, the default implementation is equivalent to return [] . prepare_metadata_for_build_editable def prepare_metadata_for_build_editable ( metadata_directory , config_settings = None ): ... Must create a .dist-info directory containing wheel metadata inside the specified metadata_directory (i.e., creates a directory like {metadata_directory}/{package}-{version}.dist-info/ ). This directory MUST be a valid .dist-info directory as defined in the wheel specification, except that it need not contain RECORD or signatures.

The hook MAY also create other files inside this directory, and a build frontend MUST preserve, but otherwise ignore, such files; the intention here is that in cases where the metadata depends on build-time decisions, the build backend may need to record these decisions in some convenient format for re-use by the actual wheel-building step. This must return the basename (not the full path) of the .dist-info directory it creates, as a unicode string.

If a build frontend needs this information and the method is not defined, it should call build_editable and look at the resulting metadata directly. What to put in the wheel Build backends must populate the generated wheel with files that when installed will result in an editable install. Build backends may use different techniques to achieve the goals of an editable install. This section provides examples and is not normative.

Build backends may choose to place a .pth file at the root of the .whl file, containing the root directory of the source tree. This approach is simple but not very precise, although it may be considered good enough (especially when using the src layout) and is similar to what setup.py develop currently does. The editables library shows how to build proxy modules that provide a high quality editable installation. It accepts a list of modules to include, and hide.

When imported, thes

The rest of this page is on the live site.