PDM Build Backend

Warnings

• gotcha 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.
  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`).
• gotcha 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.
  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]`.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• pip install pdm-backend Install pdm-backend (usually as a build dependency)
• pip install pdm Install PDM (to use pdm-backend effectively)

Imports

• 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.

Quickstart

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