{"id":8404,"library":"pdm-build-locked","title":"PDM Build Locked","description":"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.","status":"active","version":"0.3.7","language":"en","source_language":"en","source_url":"https://github.com/pdm-project/pdm-build-locked","tags":["pdm","plugin","packaging","build","dependencies","lockfile","reproducible builds","cli tools"],"install":[{"cmd":"pip install pdm-build-locked","lang":"bash","label":"Install as a regular package"},{"cmd":"pdm self add pdm-build-locked","lang":"bash","label":"Activate as a global PDM plugin"}],"dependencies":[{"reason":"`pdm-build-locked` is a plugin for PDM and requires PDM to function. Compatible with PDM >= 2.11.","package":"pdm","optional":false}],"imports":[{"note":"The functionality is integrated into the `pdm build` command.","symbol":"No direct Python imports for end-users","correct":"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."}],"quickstart":{"code":"# 1. Create a new PDM project and add a dependency\nmkdir my_cli_app\ncd my_cli_app\npdm init --backend pdm-backend --static-version --no-interaction\npdm add rich\n\n# 2. Add pdm-build-locked to your project (if not installed globally)\npdm add --dev pdm-build-locked\n\n# 3. Configure pyproject.toml to use pdm-build-locked\n#    Add the following to your pyproject.toml manually or via script:\n# [tool.pdm-build-locked]\n# backend = 'pdm-backend'\n#\n# 4. Ensure the plugin is active (if not already via `pdm self add`)\npdm install\n\n# 5. Build the project with locked dependencies\npdm build --locked\n\n# 6. Install the resulting wheel with locked dependencies\n#    (Replace 'my_cli_app-0.1.0-py3-none-any.whl' with your actual wheel file name)\npip install dist/my_cli_app-0.1.0-py3-none-any.whl[locked]\n\n# To verify, you can check installed packages or run your CLI app","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions of pdm-build-locked"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ResolutionImpossible: A locked group could not be resolved during installation (e.g., `pip install mypkg[locked]` fails)."},{"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.","cause":"The `pdm.lock` file that was used to build the package does not contain the specified dependency group, or it's outdated/corrupted.","error":"ERROR: Requested groups not in lockfile: ['locked'] or other custom optional groups."},{"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`.","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.","error":"When installing my built package with `[locked]`, it doesn't use the pinned versions from `pdm.lock`."}]}