PDM Build Locked

0.3.7 · active · verified Thu Apr 16

pdm-build-locked is a PDM plugin that adds locked packages as additional optional dependency groups to the distribution metadata. This enables reproducible installs of Python CLI tools by allowing users to install exact dependency versions from a PDM lockfile, preventing breakage on dependency updates. It is compatible with PDM versions >=2.11 and is currently at version 0.3.7.

Common errors

```
ResolutionImpossible: A locked group could not be resolved during installation (e.g., `pip install mypkg[locked]` fails).
```
cause This often occurs when `tool.pdm.resolution.overrides` in your `pyproject.toml` sets a version range for a dependency that conflicts with the range specified in `project.dependencies` for the same package.

fix Review your `pyproject.toml` and reconcile any conflicting version constraints between `project.dependencies` and `tool.pdm.resolution.overrides`. The override should refine, not contradict, the base dependency.
```
ERROR: Requested groups not in lockfile: ['locked'] or other custom optional groups.
```
cause The `pdm.lock` file that was used to build the package does not contain the specified dependency group, or it's outdated/corrupted.

fix Remove the existing `pdm.lock` file and regenerate it using `pdm lock -G :all` (or specifying relevant groups) to ensure all intended dependency groups are included and properly locked. Then, rebuild your distribution.
```
When installing my built package with `[locked]`, it doesn't use the pinned versions from `pdm.lock`.
```
cause The `pdm-build-locked` plugin was likely not active or correctly configured during the `pdm build` process, or the `pyproject.toml` wasn't properly set up to use it.

fix Ensure `pdm-build-locked` is installed and active (`pdm self add pdm-build-locked` or `pdm add --dev pdm-build-locked` and `pdm install`). Verify that your `pyproject.toml` includes the `[tool.pdm-build-locked]` section. After confirming the setup, rebuild your package using `pdm build --locked`.

Warnings

breaking Setting `tool.pdm.resolution.overrides` to a version range incompatible with `project.dependencies` for a dependency can lead to `ResolutionImpossible` errors when users try to install the package with the `[locked]` extra.
Fix: Ensure that any `tool.pdm.resolution.overrides` definitions are compatible with the `project.dependencies` specified in `pyproject.toml`. The overridden range should always be a subset of the project's dependency range.
gotcha Using `[locked]` dependency groups is primarily intended for CLI tools or CLI tools that are also libraries (where `[locked]` is used only when installing the executable). Applying `[locked]` dependencies for a 'library only' package is highly discouraged as it can easily lead to dependency conflicts for consuming projects.
Fix: Only use `pdm-build-locked` for CLI tools or combined CLI tool/library packages where the `[locked]` extra is exclusively for executable installs. Avoid using it for libraries that are expected to be included as dependencies in other projects' `pyproject.toml` files.
gotcha The `pdm.lock` file must be configured with the `inherit_metadata` strategy (for PDM >= 2.11) and include locks for all desired optional-dependencies groups. If groups are missing, they won't be available in the built distribution.
Fix: Before building, ensure your `pdm.lock` file is up-to-date and generated with all necessary groups, for example, by running `pdm lock -G :all`. Verify the `[metadata]` section of `pdm.lock` includes the expected groups.

Install

pip install pdm-build-locked Install as a regular package
pdm self add pdm-build-locked Activate as a global PDM plugin

Imports

No direct Python imports for end-users

This library is a PDM plugin and is primarily used via PDM CLI commands and `pyproject.toml` configuration. It does not expose Python symbols for direct import into application code.

The functionality is integrated into the `pdm build` command.

Quickstart

This quickstart demonstrates how to set up a project using `pdm-build-locked`. It involves creating a PDM project, adding `pdm-build-locked` as a development dependency, configuring `pyproject.toml` to enable the plugin, building the distribution with the `--locked` flag, and then installing the resulting wheel with the `[locked]` extra, which pulls in the exact dependency versions specified in your `pdm.lock` file. Remember to replace 'my_cli_app-0.1.0-py3-none-any.whl' with the actual filename generated in your `dist/` directory.

# 1. Create a new PDM project and add a dependency
mkdir my_cli_app
cd my_cli_app
pdm init --backend pdm-backend --static-version --no-interaction
pdm add rich

# 2. Add pdm-build-locked to your project (if not installed globally)
pdm add --dev pdm-build-locked

# 3. Configure pyproject.toml to use pdm-build-locked
#    Add the following to your pyproject.toml manually or via script:
# [tool.pdm-build-locked]
# backend = 'pdm-backend'
#
# 4. Ensure the plugin is active (if not already via `pdm self add`)
pdm install

# 5. Build the project with locked dependencies
pdm build --locked

# 6. Install the resulting wheel with locked dependencies
#    (Replace 'my_cli_app-0.1.0-py3-none-any.whl' with your actual wheel file name)
pip install dist/my_cli_app-0.1.0-py3-none-any.whl[locked]

# To verify, you can check installed packages or run your CLI app

view raw JSON →