pdm-backend is the PEP 517 compliant build backend utilized by PDM, a modern Python package manager. It supports the latest packaging standards for building source distributions (sdist) and wheels, including dynamic versioning from SCM, flexible metadata definition in pyproject.toml, and handling of various project layouts. The current version is 2.4.8, with a regular release cadence to incorporate new features and bug fixes.
Install & Compatibility
Where this runs
tested against v2.4.9 · 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
py 3.10
8/12 runs
8/12 runs
py 3.11
8/12 runs
8/12 runs
py 3.12
8/12 runs
8/12 runs
py 3.13
8/12 runs
8/12 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
build-backend specification
✓ In pyproject.toml: build-backend = "pdm.backend"
pdm-backend is a PEP 517 build backend and is not meant for direct import in user code. Its functionality is exposed through a pyproject.toml entry point, where build tools like PDM or 'build' interact with it.
This quickstart demonstrates how to configure `pdm-backend` in a `pyproject.toml` file for a simple Python package. It defines basic project metadata and specifies `pdm-backend` as the build backend. After setting up the `pyproject.toml` and a minimal package structure, you can build your project's wheel and sdist using the `pdm build` command or the standard `python -m build` tool.
# my_project/pyproject.toml
[project]
name = "my-package"
version = "0.1.0"
dynamic = ["dependencies", "optional-dependencies"]
description = "A minimal example package"
requires-python = ">=3.9"
license = { text = "MIT" }
authors = [
{ name = "Your Name", email = "your@example.com" }
]
[build-system]
requires = ["pdm-backend"]
build-backend = "pdm.backend"
# my_project/src/my_package/__init__.py
__version__ = "0.1.0"
# To build the package (run from my_project directory):
# 1. Ensure PDM is installed: pip install pdm
# 2. Run the build command:
# pdm build
# Or using the standard 'build' tool:
# pip install build
# python -m build
Debug
Known issues
gotchaSCM-based versioning requires a clean Git working tree and correct Git configuration. Errors can occur if Git is not found, if the repository is in a detached HEAD state without proper tags, or if `core.abbrev` is configured to a non-standard value.fixEnsure `git` is installed and accessible. For dynamic SCM versioning, verify your `pyproject.toml` configuration in `[tool.pdm.version]` and ensure your Git repository is properly tagged and in a consistent state. Recent versions of pdm-backend include fixes for specific Git parsing issues (e.g., `core.abbrev`).
affects: All versions, especially when using dynamic versioning from SCM.
gotchapdm-backend strictly adheres to PEP 621 for static metadata in `pyproject.toml`. Dynamic fields must be explicitly declared in `project.dynamic` and their values provided by build hooks or specific tool configurations.fixEnsure that any metadata fields (like `dependencies`, `version`, `authors`) that are not statically defined are listed in the `[project].dynamic` array. For dynamic versioning, configure it under `[tool.pdm.version]`.
affects: All versions
breakingPrior to 2.0, `pdm-backend` might have behaved differently with older PDM versions or `pyproject.toml` schemas. Users transitioning from older PDM setups might encounter packaging issues.fixIt's highly recommended to use PDM versions compatible with `pdm-backend >= 2.0.0` and ensure your `pyproject.toml` adheres to the latest PEP 621 standards. Review PDM's official migration guides if upgrading from PDM 1.x.
affects: <2.0.0
gotchaWhile `pdm-backend` can be used with `python -m build`, its full power and seamless integration are achieved when used within the `pdm` CLI (e.g., `pdm build`). Using `pdm` ensures the correct environment and `pyproject.toml` interpretation.fixFor the best experience and to leverage all `pdm-backend` features, use the `pdm` CLI tool. Install `pdm` via `pip install pdm` and then run `pdm build` in your project directory.
affects: All versions
gotchaThe test script or environment attempted to interpret configuration file syntax (e.g., `requires-python = ">=3.9"` from a `pyproject.toml` equivalent) directly as Python code, leading to a `SyntaxError: cannot assign to operator`. This indicates a flaw in the test setup's parsing mechanism, not an issue with `pdm-backend` itself.fixEnsure the testing environment or script uses a proper parser (e.g., `toml` library) for configuration files like `pyproject.toml` instead of attempting to execute them as Python code.
affects: All versions
Audit
Dependencies
pdm-pep517requiredCore dependency for implementing PEP 517 build hooks.