PDM - Python Development Master

2.26.7 · active · verified Thu Apr 09

PDM is a modern Python package and dependency manager that supports the latest PEP standards, including PEP 582 for local package directories. It offers robust dependency resolution, a unified `pyproject.toml` interface, and flexible virtual environment management. Currently at version 2.26.7, PDM maintains an active release cadence with frequent minor updates and bug fixes.

Warnings

breaking PDM v2 introduced significant breaking changes from v1, including a new lock file format (`pdm.lock` instead of `Pipfile.lock`) and updates to CLI commands and configuration. Projects upgrading from PDM 1.x require migration.
Fix: Refer to the official PDM migration guide for detailed steps when upgrading from PDM 1.x. It typically involves recreating the project with `pdm init` and re-adding dependencies.
gotcha PDM primarily uses `pyproject.toml` for all project metadata and dependency management. Mixing PDM with legacy `requirements.txt`, `setup.py`, or `Pipfile` within the same project can lead to conflicts and unexpected behavior.
Fix: Ensure `pyproject.toml` is the single source of truth for your PDM project. Migrate existing dependency declarations into the `[project]` and `[tool.pdm]` sections of `pyproject.toml`.
gotcha PDM's default virtual environment location is typically global (`~/.local/share/pdm/venvs`). Users accustomed to `venv` or `Poetry` creating a `.venv` folder in the project root might be surprised. Project-local venvs can be enabled but require configuration.
Fix: To create a virtual environment inside the project directory (similar to `venv` or `Poetry`), set `python.use_venv = true` in `.pdm.toml` (project-local config) or globally via `pdm config python.use_venv true`.
gotcha The commands `pdm install` and `pdm sync` have distinct behaviors. `pdm install` adds new packages and updates the `pdm.lock` file, while `pdm sync` only installs/updates dependencies specified in the existing `pdm.lock` file without modifying it. Misunderstanding this can lead to outdated lock files or unexpected dependency installations.
Fix: Use `pdm add <package>` or `pdm install` when modifying dependencies to ensure the `pdm.lock` file is updated. Use `pdm sync` when deploying or setting up a project to ensure reproducible installations based on the existing lock file.

Install

pipx install pdm Recommended (global tool)
curl -sSL https://pdm.fming.dev/install.py | python3 - Alternative Installer Script

Imports

Core
```
from pdm.core import Core
```
PDM is primarily a CLI tool. Programmatic imports like this are typically used for building tools on top of PDM, not for general application development.

Quickstart

This quickstart demonstrates initializing a PDM project, adding a dependency, and running a command within the isolated project environment. PDM automatically creates and manages virtual environments.

# 1. Initialize a new PDM project
pdm init

# 2. Add a dependency
pdm add requests

# 3. Run a command within the project's environment
pdm run python -c "import requests; print('Requests is installed!')"

# 4. (Optional) Install development dependencies
pdm add pytest --dev

# 5. (Optional) Activate the virtual environment directly
pdm venv activate
# Then run: python -c "import requests; print('Requests is installed!')"
# deactivate # To exit the virtual environment

view raw JSON →