lock-version

• Type: string; value of"1.0"
• Required?: yes
• Inspiration:Metadata-Version
• Record the file format version that the file adheres to.
• This PEP specifies the initial version – and only valid value until futureupdates to the standard change it – as"1.0".
• If a tool supports the major version but not the minor version, a toolSHOULD warn when an unknown key is seen.
• If a tool doesn’t support a major version, it MUST raise an error.

environments

• Type: Array of strings
• Required?: no
• Inspiration:uv
• A list ofEnvironment Markers forwhich the lock file is considered compatible with.
• Tools SHOULD write exclusive/non-overlapping environment markers to ease inunderstanding.

requires-python

• Type: string
• Required?: no
• Inspiration:PDM,Poetry,uv
• Specifies theRequires-Python for the minimumPython version compatible for any environment supported by the lock file(i.e. the minimum viable Python version for the lock file).

extras

• Type: Array of strings
• Required?: no; defaults to[]
• Inspiration:Provides-Extra (multiple use)
• The list ofextras supportedby this lock file.
• Lockers MAY choose to not support writing lock files that support extras anddependency groups (i.e. tools may only support exporting a single-use lockfile).
• Tools supporting extras MUST also support dependency groups.
• Tools should explicitly set this key to an empty array to signal that theinputs used to generate the lock file had no extras (e.g. apyproject.tomlfile had no[project.optional-dependencies] table), signalling that thelock file is, in effect, multi-use even if it only looks to be single-use.

dependency-groups

• Type: Array of strings
• Required?: no; defaults to[]
• Inspiration:Arbitrary tool configuration: the [tool] table
• The list ofDependency Groups publicly supported by this lockfile (i.e. dependency groups users are expected to be able to specify via atool’s UI).
• Lockers MAY choose to not support writing lock files that support extras anddependency groups (i.e. tools may only support exporting a single-use lockfile).
• Tools supporting dependency groups MUST also support extras.
• Tools SHOULD explicitly set this key to an empty array to signal that theinputs used to generate the lock file had no dependency groups (e.g. apyproject.tomlfile had no[dependency-groups] table), signalling that the lock fileis, in effect, multi-use even if it only looks to be single-use.

default-groups

• Type: Array of strings
• Required?: no; defaults to[]
• Inspiration:Poetry,PDM
• The name of synthetic dependency groups to represent what should be installedby default (e.g. whatproject.dependencies implicitly represents).
• Meant to be used in situations wherepackages.marker necessitates such agroup to exist.
• The groups listed by this key SHOULD NOT be listed independency-groups asthe groups are not meant to be directly exposed to users by name but insteadvia an installer’s UI.

created-by

• Type: string
• Required?: yes
• Inspiration: Tools with their name in their lock file name
• Records the name of the tool used to create the lock file.
• Tools MAY use the[tool] table to record enough details that it can beinferred what inputs were used to create the lock file.
• Tools SHOULD record the normalized name of the tool if it is available as aPython package to facilitate finding the tool.

[[packages]]

• Type: array of tables
• Required?: yes
• Inspiration:PDM,Poetry,uv
• An array containing all packages thatmay be installed.
• Packages MAY be listed multiple times with varying data, but all packages tobe installed MUST narrow down to a single entry at install time.

[tool]

• Type: table
• Required?: no
• Inspiration:Arbitrary tool configuration: the [tool] table
• Seepackages.tool.

Using*.pylock.toml as the file name

It was proposed to put thepylock constant part of the file name after theidentifier for the purpose of the lock file. It was decided not to do this sothat lock files would sort together when looking at directory contents insteadof purely based on their purpose which could spread them out in a directory.

Using*.pylock as the file name

Not using.toml as the file extension and instead making it.pylockitself was proposed. This was decided against so that code editors would knowhow to provide syntax highlighting to a lock file without having specialknowledge about the file extension.

Not having a naming convention for the file

Having no requirements or guidance for a lock file’s name was considered, butultimately rejected. By having a standardized naming convention it makes it easyto identify a lock file for both a human and a code editor. This helpsfacilitate discovery when e.g. a tool wants to know all of the lock files thatare available.

Use JSON over TOML

Since having a format that is machine-writable was a goal of this PEP, it wassuggested to use JSON. But it was deemed less human-readable than TOML whilenot improving on the machine-writable aspect enough to warrant the change.

Use YAML over TOML

Some argued that YAML met the machine-writable/human-readable requirement in abetter way than TOML. But as that’s subjective andpyproject.toml alreadyexisted as the human-writable file used by Python packaging standards it wasdeemed more important to keep using TOML.

A single hash algorithm for the whole file

Earlier versions of this PEP proposed having a single hash algorithm bespecified per file instead of any number of algorithms per file. The thinkingwas that by specifying a single algorithm it would help with auditing the filewhen a specific hash algorithm was mandated for use.

In the end there was some objection to this idea. Typically, it centered aroundthe cost of rehashing large wheel files (e.g. PyTorch). There was also concernabout making hashing decisions upfront on the installer’s behalf which they maydisagree with. In the end it was deemed better to have flexibility and letpeople audit the lock file as they see fit.

Hashing the contents of the lock file itself

Hashing the contents of the bytes of the file and storing hash value within thefile itself was proposed at some point. This was removed to make it easierwhen merging changes to the lock file as each merge would have to recalculatethe hash value to avoid a merge conflict.

Hashing the semantic contents of the file was also proposed, but it would leadto the same merge conflict issue.

Regardless of which contents were hashed, either approach could have the hashvalue stored outside of the file if such a hash was desired.

Recording the creation date of the lock file

To know how potentially stale the lock file was, an earlier proposal suggestedrecording the creation date of the lock file. But for the same merge conflictreasons as storing the hash of the file contents, this idea was dropped.

Recording the package indexes used in searching

Recording what package indexes were used to create the lock file was considered.In the end, though, it was rejected as it was deemed unnecessary bookkeeping.

Locking build requirements for sdists

An earlier version of this PEP tried to lock the build requirements for sdistsunder apackages.build-requires key. Unfortunately, it confused enough peopleabout how it was expected to operate and there were enough edge case issues todecide it wasn’t worth trying to do in this PEP upfront. Instead, a future PEPcould propose a solution.

A dedicateddirect key

Earlier versions had a dedicatedpackages.direct key to flag when somethingshould be considered as originating from adirect URL reference. But there are explicitlyonly three cases where a direct URL reference can occur (VCS, directory, andarchive). Since all three cases are explicit in[[packages]], the setting ofthe key was technically superfluous.

The single drawback of not having this key is for wheels and sdists that nowfall underpackages.archive. With the separate key (or having it specifiedas a part ofpackages.sdist orpackages.wheels), it would allow foridentifying in the lock file itself that an archive file is an sdist or wheel.As it currently stands, an installer must infer that detail itself.

Drop recording the package version

The package version is optional since it can only be reliably recorded when ansdist or wheel file is used. And since both sources record the version in filenames it is technically redundant.

But in discussions it was decided the version number is useful for auditingenough to still state it separately.

Drop the requirement to specify the location of an sdist and/or wheels

At least one person has commented how their work has unstable URLs for allsdists and wheels. As such, they have to search for all files at installregardless of where the file was found previously. Dropping the requirement toprovide the URL or path to a file would have helped solve the issue of recordingknown-bad information.

The decision to allow tools to look for a file in other ways beyond the URLprovided alleviated the need to make the URL optional.

Drop requiring file size and hashes

At least one person has said that their work modifies all wheels and sdists withinternal files. That means any recorded hashes and file sizes will be wrong. Bymaking the file size and hashes optional – very likely through some opt-outmechanism – then they could continue to produce lock files that meet this PEP’srequirements.

The decision was made that this weakens security too much. It also preventsinstalling files from alternative locations.

Drop recording the sdist file name

While incompatible with dropping the URL/path requirement, the packageversion, and hashes, recording the sdist file name is technically not necessaryat all (right now recording the file name is optional). The file name onlyencodes the project name and version, so no new info is conveyed about the file(when the package version is provided). And if the location is recorded thengetting the file is handled regardless of the file name.

But recording the file name can be helpful when looking for an appropriate filewhen the recorded file location is no longer available (while sdist file namesare now standardized thanks toPEP 625, that has only been true since 2020and thus there are many older sdists with names that may not be guessable).

The decision was made to require the sdist file name out of simplicity.

Makepackages.wheels a table

One could see writing out wheel file details as a table keyed on the file name.For example:

[[packages]]name="attrs"version="23.2.0"requires-python=">=3.7"index="https://pypi.org/simple/"[packages.wheels]"attrs-23.2.0-py3-none-any.whl"={upload-time=2023-12-31T06:30:30.772444Z,url="https://files.pythonhosted.org/packages/e0/44/827b2a91a5816512fcaf3cc4ebc465ccd5d598c45cefa6703fcf4a79018f/attrs-23.2.0-py3-none-any.whl",size=60752,hashes={sha256="99b87a485a5820b23b879f04c2305b44b951b502fd64be915879d77a7e8fc6f1"}[[packages]]name="numpy"version="2.0.1"requires-python=">=3.9"index="https://pypi.org/simple/"[packages.wheels]"numpy-2.0.1-cp312-cp312-macosx_10_9_x86_64.whl"={upload-time=2024-07-21T13:37:15.810939Z,url="https://files.pythonhosted.org/packages/64/1c/401489a7e92c30db413362756c313b9353fb47565015986c55582593e2ae/numpy-2.0.1-cp312-cp312-macosx_10_9_x86_64.whl",size=20965374,hashes={sha256="6bf4e6f4a2a2e26655717a1983ef6324f2664d7011f6ef7482e8c0b3d51e82ac"}"numpy-2.0.1-cp312-cp312-macosx_11_0_arm64.whl"={upload-time=2024-07-21T13:37:36.460324Z,url="https://files.pythonhosted.org/packages/08/61/460fb524bb2d1a8bd4bbcb33d9b0971f9837fdedcfda8478d4c8f5cfd7ee/numpy-2.0.1-cp312-cp312-macosx_11_0_arm64.whl",size=13102536,hashes={sha256="7d6fddc5fe258d3328cd8e3d7d3e02234c5d70e01ebe377a6ab92adb14039cb4"}"numpy-2.0.1-cp312-cp312-macosx_14_0_arm64.whl"={upload-time=2024-07-21T13:37:46.601144Z,url="https://files.pythonhosted.org/packages/c2/da/3d8debb409bc97045b559f408d2b8cefa6a077a73df14dbf4d8780d976b1/numpy-2.0.1-cp312-cp312-macosx_14_0_arm64.whl",size=5037809,hashes={sha256="5daab361be6ddeb299a918a7c0864fa8618af66019138263247af405018b04e1"}"numpy-2.0.1-cp312-cp312-macosx_14_0_x86_64.whl"={upload-time=2024-07-21T13:37:58.784393Z,url="https://files.pythonhosted.org/packages/6d/59/85160bf5f4af6264a7c5149ab07be9c8db2b0eb064794f8a7bf6d/numpy-2.0.1-cp312-cp312-macosx_14_0_x86_64.whl",size=6631813,hashes={sha256="ea2326a4dca88e4a274ba3a4405eb6c6467d3ffbd8c7d38632502eaae3820587"}"numpy-2.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl"={upload-time=2024-07-21T13:38:19.714559Z,url="https://files.pythonhosted.org/packages/5e/e3/944b77e2742fece7da8dfba6f7ef7dccdd163d1a613f7027f4d5b/numpy-2.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",size=13623742,hashes={sha256="529af13c5f4b7a932fb0e1911d3a75da204eff023ee5e0e79c1751564221a5c8"}"numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl"={upload-time=2024-07-21T13:38:48.972569Z,url="https://files.pythonhosted.org/packages/2c/f3/61eee37decb58e7cb29940f19a1464b8608f2cab8a8616aba75fd/numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",size=19242336,hashes={sha256="6790654cb13eab303d8402354fabd47472b24635700f631f041bd0b65e37298a"}"numpy-2.0.1-cp312-cp312-musllinux_1_1_x86_64.whl"={upload-time=2024-07-21T13:39:19.213811Z,url="https://files.pythonhosted.org/packages/77/b5/c74cc436114c1de5912cdb475145245f6e645a6a1a29b5d08c774/numpy-2.0.1-cp312-cp312-musllinux_1_1_x86_64.whl",size=19637264,hashes={sha256="cbab9fc9c391700e3e1287666dfd82d8666d10e69a6c4a09ab97574c0b7ee0a7"}"numpy-2.0.1-cp312-cp312-musllinux_1_2_aarch64.whl"={upload-time=2024-07-21T13:39:41.812321Z,url="https://files.pythonhosted.org/packages/da/89/c8856e12e0b3f6af371ccb90d604600923b08050c58f0cd26eac9/numpy-2.0.1-cp312-cp312-musllinux_1_2_aarch64.whl",size=14108911,hashes={sha256="99d0d92a5e3613c33a5f01db206a33f8fdf3d71f2912b0de1739894668b7a93b"}"numpy-2.0.1-cp312-cp312-win32.whl"={upload-time=2024-07-21T13:39:52.932102Z,url="https://files.pythonhosted.org/packages/15/96/310c6f6d146518479b0a6ee6eb92a537954ec3b1acfa2894d1347/numpy-2.0.1-cp312-cp312-win32.whl",size=6171379,hashes={sha256="173a00b9995f73b79eb0191129f2455f1e34c203f559dd118636858cc452a1bf"}"numpy-2.0.1-cp312-cp312-win_amd64.whl"={upload-time=2024-07-21T13:40:17.532627Z,url="https://files.pythonhosted.org/packages/b5/59/f6ad378ad85ed9c2785f271b39c3e5b6412c66e810d2c60934c9f/numpy-2.0.1-cp312-cp312-win_amd64.whl",size=16255757,hashes={sha256="bb2124fdc6e62baae159ebcfa368708867eb56806804d005860b6007388df171"}

In general, though, people did not prefer this over the approach this PEP hastaken.

Drop the[tool] table

The[tool] table is included as it has been found to be very useful forpyproject.toml files. Providing similar flexibility to this PEP is done inhopes that similar benefits will materialize.

But some people have been concerned that such a table will be too enticing totools and will lead to files that are tool-specific and unusable by othertools. This could cause issues for tools trying to do installation, auditing,etc. as they would not know what details in the[tool] table are somehowcritical.

As a compromise, this PEP specifies that the details recorded in[tool] mustbe disposable and not affect installation of packages.

List the requirement inputs for the file

Right now the file does not record the requirements that acted as inputs to thefile. This is for simplicity reasons and to not explicitly constrain the filein some unforeseen way (e.g., updating the file after initial creation for anew platform that has different requirements, all without having to resolvehow to write a comprehensive set of requirements).

But it may help in auditing and any recreation of the file if the originalrequirements were somehow recorded. This could be a single string or an arrayof strings if multiple requirements were used with the file.

In the end it was deemed too complicated to try and capture the inputsthat a tool used to construct the lock file in a generic fashion.

Recording dependents

Recording the dependents of a package is not necessary to install it. As such,it has been left out of the PEP as it can be included via[tool].

But knowing how critical a package is to other packages may be beneficial. Thisinformation is included bypip-tools , so there’s prior art in including it.A flexible approach could be used to record the dependents, e.g. as muchdetail as to differentiate from any other entry for the same package in the file(inspired byuv).

In the end, though, it was decided that recording the dependencies is a betterthing to record.