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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.8s · import 0.000s · 19MB
51MB installed
● package 51MB
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
Upgrade
Version history
2.4.9latest on PyPI · released Jun 5, 2026
Audit
Dependencies
pdm-pep517requiredCore dependency for implementing PEP 517 build hooks.