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.

Specification#

The direct_url.json file MUST be created in the *.dist-info 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.

Note

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 vcs_info) in direct_url.json.

Note

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

Example pip commands and their effect on direct_url.json#

Commands that generate a direct_url.json:

  • 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, url will be the local directory where the git repository has been cloned to, and dir_info will be present with "editable": true and no vcs_info will be set)

  • pip install -e ./app

Commands that do not generate a direct_url.json

  • pip install app

  • pip install app --no-index --find-links https://example.com/

History#

  • March 2020: This specification was approved through PEP 610.