{"id":1304,"library":"pdm-backend","title":"PDM Build Backend","description":"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.","status":"active","version":"2.4.8","language":"en","source_language":"en","source_url":"https://github.com/pdm-project/pdm-backend","tags":["packaging","build-backend","pdm","pep517","pyproject-toml"],"install":[{"cmd":"pip install pdm-backend","lang":"bash","label":"Install pdm-backend (usually as a build dependency)"},{"cmd":"pip install pdm","lang":"bash","label":"Install PDM (to use pdm-backend effectively)"}],"dependencies":[{"reason":"Core dependency for implementing PEP 517 build hooks.","package":"pdm-pep517","optional":false}],"imports":[{"note":"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.","symbol":"build-backend specification","correct":"In pyproject.toml: build-backend = \"pdm.backend\""}],"quickstart":{"code":"# my_project/pyproject.toml\n[project]\nname = \"my-package\"\nversion = \"0.1.0\"\ndynamic = [\"dependencies\", \"optional-dependencies\"]\ndescription = \"A minimal example package\"\nrequires-python = \">=3.9\"\nlicense = { text = \"MIT\" }\nauthors = [\n    { name = \"Your Name\", email = \"your@example.com\" }\n]\n\n[build-system]\nrequires = [\"pdm-backend\"]\nbuild-backend = \"pdm.backend\"\n\n# my_project/src/my_package/__init__.py\n__version__ = \"0.1.0\"\n\n# To build the package (run from my_project directory):\n# 1. Ensure PDM is installed: pip install pdm\n# 2. Run the build command:\n#    pdm build\n# Or using the standard 'build' tool:\n#    pip install build\n#    python -m build","lang":"toml","description":"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."},"warnings":[{"fix":"Ensure `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`).","message":"SCM-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.","severity":"gotcha","affected_versions":"All versions, especially when using dynamic versioning from SCM."},{"fix":"Ensure 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]`.","message":"pdm-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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"It'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.","message":"Prior 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.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"For 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.","message":"While `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-08T00:00:00.000Z","next_check":"2026-07-07T00:00:00.000Z"}