Recording the Direct URL Origin of installed distributions¶
This document specifies a
direct_url.json file in the
*.dist-info directory of an installed distribution, to record the
Direct URL Origin of the distribution. The general structure and usage of
*.dist-info directories is described in Recording installed projects.
direct_url.json file MUST be created in the
directory by installers when installing a distribution from a requirement
specifying a direct URL reference (including a VCS URL).
This file MUST NOT be created when installing a distribution from an other type of requirement (i.e. name plus version specifier).
This JSON file MUST be a UTF-8 encoded, RFC 8259 compliant, serialization of the Direct URL Data Structure.
When the requested URL has the file:// scheme and points to a local directory that happens to contain a
VCS checkout, installers MUST NOT attempt to infer any VCS information and
therefore MUST NOT output any VCS related information (such as
As a general rule, installers should as much as possible preserve the
information that was provided in the requested URL when generating
direct_url.json. For example user:password environment variables
should be preserved and
requested_revision should reflect the revision that was
provided in the requested URL as faithfully as possible. This information is
however enriched with more precise data, such as
Example pip commands and their effect on direct_url.json¶
Commands that generate a
pip install https://example.com/app-1.0.tgz
pip install https://example.com/app-1.0.whl
pip install "app @ git+https://example.com/repo/app.git#subdirectory=setup"
pip install ./app
pip install file:///home/user/app
pip install --editable "app @ git+https://example.com/repo/app.git#subdirectory=setup"(in which case,
urlwill be the local directory where the git repository has been cloned to, and
dir_infowill be present with
"editable": trueand no
vcs_infowill be set)
pip install -e ./app
Commands that do not generate a
pip install app
pip install app --no-index --find-links https://example.com/
March 2020: the
direct_url.jsonmetadata file was originally specified in PEP 610 and is formally documented here.