Install & Compatibility
Where this runs
tested against v0.3.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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
Debug
Known issues
breakingSetting `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.fixEnsure 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.
affects: All versions of pdm-build-locked
gotchaUsing `[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.fixOnly 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.
affects: All versions
gotchaThe `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.fixBefore 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.
affects: All versions
Upgrade
Version history
0.3.7latest on PyPI · released Nov 30, 2025
Audit
Dependencies
pdmrequired`pdm-build-locked` is a plugin for PDM and requires PDM to function. Compatible with PDM >= 2.11.