pdm-project/pdm

A modern Python package and dependency manager supporting the latest PEP standards

Structural Verdict

How Data Flows Through the System

PDM processes dependency specifications through resolution to installation, maintaining lock files for reproducibility

1. Parse project — Load pyproject.toml and extract dependencies and metadata (config: project.name, project.dependencies)
2. Resolve dependencies — Use resolvelib to find compatible versions satisfying all constraints (config: python-version, index-url)
3. Generate lock — Create pdm.lock with exact versions and hashes for reproducible installs
4. Install packages — Download and install resolved packages into target environment (config: cache-dir, install.parallel)
5. Update working set — Track installed packages and their metadata for future operations

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Feedback Loops

• Dependency Resolution (recursive, balancing) — Trigger: Conflicting version constraints. Action: Backtrack to previous choice and try alternative. Exit: All constraints satisfied or resolution impossible.
• Cache Validation (cache-invalidation, balancing) — Trigger: Metadata fetch for package. Action: Check local cache validity against remote. Exit: Fresh metadata obtained.

Delays & Async Processing

• Package Download (async-processing, ~variable) — Users wait while packages are fetched from PyPI
• Build Isolation (async-processing, ~variable) — Temporary environment setup delays package building
• Cache TTL (cache-ttl, ~configurable) — Metadata may be stale until cache expires

Control Points

• Index URLs (env-var) — Controls: Which package repositories to search. Default: PyPI by default
• Cache Directory (env-var) — Controls: Where to store downloaded packages. Default: ~/.cache/pdm
• Parallel Install (runtime-toggle) — Controls: Number of concurrent package installations. Default: true
• Resolution Strategy (feature-flag) — Controls: How dependency conflicts are resolved. Default: highest version

Technology Stack

Key Components

• main (function) — Main entry point that initializes CLI and dispatches commands src/pdm/core.py
• BaseCommand (class) — Abstract base class for all CLI subcommands with argument parsing src/pdm/cli/commands/base.py
• do_lock (function) — Core dependency resolution and lock file generation logic src/pdm/cli/actions.py
• Project (class) — Central project management class handling pyproject.toml and dependencies src/pdm/project/__init__.py
• Requirement (class) — Represents package requirements with version constraints and markers src/pdm/models/requirements.py
• Candidate (class) — Represents specific package versions during dependency resolution src/pdm/models/candidates.py
• BaseEnvironment (class) — Abstract base for Python environment management (venv, conda, etc) src/pdm/environments/base.py
• EnvBuilder (class) — Base class for building packages (wheels, sdists) in isolated environments src/pdm/builders/base.py
• Config (class) — Configuration management for global and project-specific settings src/pdm/project/config.py
• HookManager (class) — Plugin system for extending PDM functionality with lifecycle hooks src/pdm/cli/hooks.py
• RichLockReporter (class) — Rich terminal UI for displaying dependency resolution progress src/pdm/resolver/reporters.py
• LockedRepository (class) — Repository implementation that reads from lock files src/pdm/models/repositories/lock.py

Configuration

codecov.yml (yaml)

• codecov.notify.after_n_builds (number, unknown) — default: 12
• codecov.notify.wait_for_ci (boolean, unknown) — default: false

install-pdm.py (python-dataclass)

• prerelease (bool, unknown) — default: False
• additional_deps (Sequence[str], unknown) — default: ()
• skip_add_to_path (bool, unknown) — default: False
• frozen_deps (bool, unknown) — default: True

src/pdm/cli/commands/outdated.py (python-dataclass)

• package (str, unknown)
• groups (list[str], unknown)
• installed_version (str, unknown)
• pinned_version (str, unknown)
• latest_version (str, unknown) — default: ""

src/pdm/formats/uv.py (python-dataclass)

• project (Project, unknown)
• requires_python (str, unknown)
• requirements (list[Requirement], unknown)
• locked_repository (LockedRepository, unknown)
• stack (ExitStack, unknown) — default: field(default_factory=ExitStack, init=False)

Related Cli Tool Repositories

Frequently Asked Questions

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.