0
# PDM (Python Dependency Manager)
1

2
A modern Python package and dependency manager supporting the latest PEP standards. PDM provides fast dependency resolution, flexible project management, and comprehensive Python environment handling with support for PEP 517 (build backend), PEP 621 (project metadata), and lockfiles for reproducible builds.
3

4
## Package Information
5

6
- **Package Name**: pdm
7
- **Language**: Python
8
- **Installation**: `pip install pdm` or via installer script
9
- **Entry Point**: Command-line tool `pdm` and Python API
10

11
## Core Imports
12

13
```python
14
import pdm
15
from pdm.core import Core
16
from pdm.project import Project
17
```
18

19
Common imports for CLI commands:
20
```python
21
from pdm.cli.commands.base import BaseCommand
22
from pdm.cli.actions import do_lock, do_sync
23
```
24

25
## Basic Usage
26

27
### Command Line Interface
28
```bash
29
# Initialize a new project
30
pdm init
31

32
# Add dependencies
33
pdm add requests
34
pdm add pytest --group dev
35

36
# Install dependencies
37
pdm install
38

39
# Update lockfile
40
pdm lock
41

42
# Sync environment with lockfile
43
pdm sync
44

45
# Run commands in project environment
46
pdm run python script.py
47
```
48

49
### Python API Usage
50
```python
51
from pdm.core import Core
52
from pdm.project import Project
53

54
# Create core manager
55
core = Core()
56

57
# Create or load project
58
project = core.create_project(".")
59

60
# Lock dependencies
61
from pdm.cli.actions import do_lock
62
do_lock(project)
63

64
# Sync environment with lockfile
65
from pdm.cli.actions import do_sync
66
do_sync(project)
67
```
68

69
## Architecture
70

71
PDM follows a modular architecture with clear separation of concerns:
72

73
- **Core**: Central coordination and plugin management (`pdm.core.Core`)
74
- **Project**: Project configuration and metadata management (`pdm.project.Project`)
75
- **Environments**: Python environment abstraction and management
76
- **Resolvers**: Dependency resolution using ResolveLib or UV
77
- **Installers**: Package installation and synchronization
78
- **CLI**: Command-line interface with extensible command system
79
- **Formats**: Import/export support for various package manager formats
80

81
This design enables extensibility through plugins while maintaining backwards compatibility and supporting the latest Python packaging standards.
82

83
## Capabilities
84

85
### Core Management
86

87
Central coordination system managing projects, plugins, and global configuration. Provides the main entry point for both CLI and programmatic usage.
88

89
```python { .api }
90
class Core:
91
    def create_project(
92
        self,
93
        root_path: str | Path | None = None,
94
        is_global: bool = False,
95
        global_config: str | None = None,
96
    ) -> Project: ...
97
    def register_command(self, command: type[BaseCommand], name: str | None = None) -> None: ...
98
    def add_config(self, name: str, config_item: ConfigItem) -> None: ...
99
    def load_plugins(self) -> None: ...
100

101
def main(args: list[str] | None = None) -> None: ...
102
```
103

104
[Core Management](./core-management.md)
105

106
### Project Management
107

108
Project configuration, metadata handling, and dependency management. Manages pyproject.toml files, dependency specifications, and project environments.
109

110
```python { .api }
111
class Project:
112
    @property
113
    def lockfile(self) -> Lockfile: ...
114
    @property
115
    def environment(self) -> BaseEnvironment: ...
116
    @property
117
    def python(self) -> PythonInfo: ...
118
    @property
119
    def name(self) -> str: ...
120
    @property
121
    def all_dependencies(self) -> dict[str, Sequence[Requirement]]: ...
122
    @property
123
    def sources(self) -> list[RepositoryConfig]: ...
124
    def add_dependencies(
125
        self,
126
        requirements: Iterable[str | Requirement],
127
        to_group: str = "default",
128
        dev: bool = False,
129
        show_message: bool = True,
130
        write: bool = True,
131
    ) -> list[Requirement]: ...
132

133
class Config:
134
    def __getitem__(self, key: str) -> Any: ...
135
    def __setitem__(self, key: str, value: Any) -> None: ...
136
```
137

138
[Project Management](./project-management.md)
139

140
### Environment Management
141

142
Python environment abstraction supporting virtual environments, system Python, and containerized environments with package management capabilities.
143

144
```python { .api }
145
class BaseEnvironment:
146
    def get_paths(self) -> dict[str, str]: ...
147
    def get_python_executable(self) -> Path: ...
148

149
class PythonEnvironment(BaseEnvironment):
150
    def install(self, requirements: list[str]) -> None: ...
151
    def uninstall(self, packages: list[str]) -> None: ...
152
```
153

154
[Environment Management](./environment-management.md)
155

156
### Dependency Resolution
157

158
Advanced dependency resolution supporting both ResolveLib and UV backends with conflict resolution, constraint handling, and performance optimization.
159

160
```python { .api }
161
class Resolver:
162
    def resolve(self, requirements: list[Requirement]) -> dict[str, Candidate]: ...
163

164
class RLResolver(Resolver): ...
165
class UvResolver(Resolver): ...
166
```
167

168
[Dependency Resolution](./dependency-resolution.md)
169

170
### Installation & Synchronization
171

172
Package installation management with support for wheels, source distributions, editable installs, and environment synchronization.
173

174
```python { .api }
175
def do_lock(
176
    project: Project,
177
    strategy: str = "all",
178
    tracked_names: Iterable[str] | None = None,
179
    requirements: list[Requirement] | None = None,
180
    dry_run: bool = False,
181
    refresh: bool = False,
182
    groups: list[str] | None = None,
183
    strategy_change: list[str] | None = None,
184
    hooks: HookManager | None = None,
185
    env_spec: EnvSpec | None = None,
186
    append: bool = False,
187
) -> dict[str, list[Candidate]]: ...
188

189
def do_sync(
190
    project: Project,
191
    *,
192
    selection: GroupSelection,
193
    dry_run: bool = False,
194
    clean: bool = False,
195
    quiet: bool = False,
196
    requirements: list[Requirement] | None = None,
197
    tracked_names: Collection[str] | None = None,
198
    no_editable: bool | Collection[str] = False,
199
    no_self: bool = False,
200
    reinstall: bool = False,
201
    only_keep: bool = False,
202
    fail_fast: bool = False,
203
    hooks: HookManager | None = None,
204
) -> None: ...
205
```
206

207
[Installation & Synchronization](./installation-sync.md)
208

209
### Lockfile Management
210

211
Comprehensive lockfile management supporting cross-platform compatibility, reproducible builds, and dependency metadata preservation.
212

213
```python { .api }
214
class Lockfile:
215
    def write(self, content: dict) -> None: ...
216
    def read(self) -> dict: ...
217

218
class PDMLock(Lockfile): ...
219

220
def load_lockfile(path: Path) -> Lockfile: ...
221
```
222

223
### CLI Framework
224

225
Extensible command-line interface supporting custom commands, argument parsing, and integration with the plugin system.
226

227
```python { .api }
228
class BaseCommand:
229
    name: str | None = None
230
    description: str | None = None
231
    arguments: Sequence[Option] = (verbose_option, global_option, project_option)
232
    
233
    @classmethod
234
    def register_to(cls, subparsers: _SubParsersAction, name: str | None = None, **kwargs: Any) -> None: ...
235
    def add_arguments(self, parser: ArgumentParser) -> None: ...
236
    def handle(self, project: Project, options: Namespace) -> None: ...
237
```
238

239
[CLI Framework](./cli-framework.md)
240

241
### Virtual Environment Management
242

243
PDM provides comprehensive virtual environment management with support for multiple Python versions and backends.
244

245
```python { .api }
246
# CLI commands available:
247
# pdm venv create [python] [--name] [--with-pip]
248
# pdm venv list
249
# pdm venv remove <key>
250
# pdm venv activate <key>
251
# pdm venv purge
252
# pdm python install <versions>
253
# pdm python list [--all]
254
```
255

256
Main command classes:
257
```python { .api }
258
from pdm.cli.commands.venv import Command as VenvCommand
259
from pdm.cli.commands.python import Command as PythonCommand
260
```
261

262
### Format Converters
263

264
Import and export functionality supporting multiple package manager formats including Poetry, Pipfile, requirements.txt, and setup.py.
265

266
```python { .api }
267
def convert_from(source_format: str, project: Project) -> None: ...
268
def export_to(target_format: str, project: Project) -> str: ...
269
```
270

271
## Types
272

273
### Core Types
274

275
```python { .api }
276
from typing import TypedDict, NamedTuple, Protocol
277
from pathlib import Path
278

279
class RepositoryConfig(TypedDict):
280
    url: str
281
    username: str | None
282
    access_token: str | None
283

284
class SearchResult(NamedTuple):
285
    name: str
286
    version: str
287
    summary: str
288

289
SearchResults = list[SearchResult]
290
RequirementDict = dict[str, str | dict[str, str]]
291

292
class FileHash(TypedDict):
293
    algorithm: str
294
    hash: str
295

296
class HiddenText:
297
    def __init__(self, value: str) -> None: ...
298
    def __str__(self) -> str: ...
299

300
class NotSetType:
301
    def __bool__(self) -> bool: ...
302

303
NotSet = NotSetType()
304
```
305

306
### Protocol Definitions
307

308
```python { .api }
309
class Comparable(Protocol):
310
    def __lt__(self, other) -> bool: ...
311
    def __le__(self, other) -> bool: ...
312
    def __gt__(self, other) -> bool: ...
313
    def __ge__(self, other) -> bool: ...
314

315
class Spinner(Protocol):
316
    def start(self, text: str) -> None: ...
317
    def stop(self) -> None: ...
318
    def update(self, text: str) -> None: ...
319
```
320

321
## Error Handling
322

323
PDM provides a comprehensive exception hierarchy for different error scenarios:
324

325
```python { .api }
326
class PdmException(Exception):
327
    """Base exception for all PDM errors"""
328

329
class ResolutionError(PdmException):
330
    """Dependency resolution failures"""
331

332
class PdmUsageError(PdmException):
333
    """Usage and configuration errors"""
334

335
class RequirementError(PdmUsageError):
336
    """Invalid requirement specifications"""
337

338
class ProjectError(PdmUsageError):
339
    """Project configuration/structure errors"""
340

341
class InstallationError(PdmException):
342
    """Package installation failures"""
343

344
class BuildError(PdmException):
345
    """Package building failures"""
346
```