Skip to content

CLI Reference#

For how dependency commands affect pyproject.toml, the lock file, and installed packages, see Command effects.

pdm#

Options:

  • -h, --help: Show this help message and exit.
  • -V, --version: Show the version and exit
  • -c, --config: Specify another config file path [env var: PDM_CONFIG_FILE]
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --no-cache: Disable the cache for the current command. [env var: PDM_NO_CACHE]
  • -I, --ignore-python: Ignore the Python path saved in .pdm-python. [env var: PDM_IGNORE_SAVED_PYTHON]
  • --pep582 SHELL: Print the command line to be eval'd by the shell for PEP 582
  • -n, --non-interactive: Don't show interactive prompts but use defaults. [env var: PDM_NON_INTERACTIVE]

Commands:

add#

Add requirements, update the lockfile, and install the target group

Update Strategy:

  • --update-reuse: Reuse pinned versions already present in lock file if possible
  • --update-eager: Try to update the packages and their dependencies recursively
  • --update-all: Update all dependencies and sub-dependencies
  • --update-reuse-installed: Reuse installed packages if possible

Save Strategy:

  • --save-compatible: Save compatible version specifiers
  • --save-safe-compatible: Save safe compatible version specifiers
  • --save-wildcard: Save wildcard version specifiers
  • --save-exact: Save exact version specifiers
  • --save-minimum: Save minimum version specifiers

Package Arguments:

  • -e, --editable: Specify editable packages
  • packages: Specify packages

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • -L, --lockfile: Specify another lockfile path. Default: pdm.lock. [env var: PDM_LOCKFILE]
  • --frozen-lockfile, --no-lock: Don't try to create or update the lockfile. [env var: PDM_FROZEN_LOCKFILE]
  • --override: Use the constraint file in pip-requirements format for overriding. [env var: PDM_OVERRIDE] This option can be used multiple times. See https://pip.pypa.io/en/stable/user_guide/#constraints-files
  • --pre, --prerelease: Allow prereleases to be pinned
  • --stable: Only allow stable versions to be pinned (default: True)
  • -u, --unconstrained: Ignore the version constraints in pyproject.toml and overwrite with new ones from the resolution result
  • --dry-run: Show the difference only and don't perform any action
  • --venv NAME: Run the command in the virtual environment with the given key. [env var: PDM_IN_VENV]
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • -d, --dev: Add packages into dev dependencies
  • -G, --group: Specify the target dependency group to add into
  • --no-sync: Only write pyproject.toml and do not sync the working set (default: False)

Install Options:

  • --no-editable: Install non-editable versions for all packages. [env var: PDM_NO_EDITABLE]
  • --no-self: Don't install the project itself. [env var: PDM_NO_SELF]
  • --fail-fast, -x: Abort on first installation error
  • --no-isolation: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.
  • --config-setting, -C: Pass options to the builder. Options with a value must be specified after "=": --config-setting=key(=value) or -Ckey(=value)

Writes the requested requirements to pyproject.toml, resolves them with the previously locked groups, and updates the lockfile. The target dependency group is added to the locked groups; a new lockfile includes the default and target groups. Installs packages from the target group without removing unrelated installed packages. Use --no-sync to leave the environment unchanged.

build#

Build artifacts for distribution

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • --no-isolation: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • --config-setting, -C: Pass options to the builder. Options with a value must be specified after "=": --config-setting=key(=value) or -Ckey(=value)
  • --no-sdist: Don't build source tarballs (default: False)
  • --no-wheel: Don't build wheels (default: False)
  • -d, --dest: Target directory to put artifacts (default: dist)
  • --no-clean: Do not clean the target directory (default: False)

cache#

Control the caches of PDM

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

Commands:

clear#

Clean all the files under cache directory

Positional Arguments:

  • type: Clear the given type of caches

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

remove#

Remove files matching the given pattern

Positional Arguments:

  • pattern: The pattern to remove

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

list#

List the built wheels stored in the cache

Positional Arguments:

  • pattern: The pattern to list (default: *)

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

info#

Show the info and current size of caches

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

completion#

Generate completion scripts for the given shell

Positional Arguments:

  • shell: The shell to generate the scripts for. If not given, PDM will properly guess from SHELL env var.

Options:

  • -h, --help: Show this help message and exit.

config#

Display the current configuration

Positional Arguments:

  • key: Config key
  • value: Config value

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • -l, --local: Set config in the project's local configuration file
  • -d, --delete: Unset a configuration key
  • -e, --edit: Edit the configuration file in the default editor(defined by EDITOR env var)

export#

Export the locked packages set to other formats

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • -L, --lockfile: Specify another lockfile path. Default: pdm.lock. [env var: PDM_LOCKFILE]
  • -f, --format: Export to requirements.txt format or pylock.toml format (default: requirements)
  • --no-hashes, --without-hashes: Don't include artifact hashes (default: False)
  • --no-markers: (DEPRECATED)Don't include platform markers (default: False)
  • --no-extras: Strip extras from the requirements (default: False)
  • -o, --output: Write output to the given file, or print to stdout if not given
  • --pyproject: Read the list of packages from pyproject.toml
  • --expandvars: Expand environment variables in requirements
  • --self: Include the project itself
  • --editable-self: Include the project itself as an editable dependency

Dependencies Selection:

  • -G, --group, --with GROUP: Select group of optional-dependencies separated by comma or dependency-groups (with -d). Can be supplied multiple times, use :all to include all groups under the same species.
  • --without: Exclude groups of optional-dependencies or dependency-groups
  • --no-default: Don't include dependencies from the default group (default: False)
  • -d, --dev: Select dev dependencies
  • --prod, --production: Unselect dev dependencies (default: True)

fix#

Fix the project problems according to the latest version of PDM

Positional Arguments:

  • problem: Fix the specific problem, or all if not given

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • --dry-run: Only show the problems

import#

Import project metadata from other formats

Positional Arguments:

  • filename: The file name

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • -d, --dev: import packages into dev dependencies
  • -G, --group: Specify the target dependency group to import into
  • -f, --format: Specify the file format explicitly

info#

Show the project information

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • --venv NAME: Run the command in the virtual environment with the given key. [env var: PDM_IN_VENV]
  • --python: Show the interpreter path
  • --where: Show the project root path
  • --packages: Show the local packages root
  • --env: Show PEP 508 environment markers
  • --json: Dump the information in JSON

init#

Initialize a pyproject.toml for PDM.

1
2
3
Built-in templates:
- default: `pdm init`, A simple template with a basic structure.
- minimal: `pdm init minimal`, A minimal template with only `pyproject.toml`.

Positional Arguments:

  • template: Specify the project template, which can be a local path or a Git URL
  • generator_args: Arguments passed to the generator

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • --copier: Use Copier to generate project [not installed] (default: builtin)
  • --cookiecutter: Use Cookiecutter to generate project [not installed] (default: builtin)
  • -r, --overwrite: Overwrite existing files

Builtin Generator Options:

  • -n, --non-interactive: Don't ask questions but use default values
  • --python: Specify the Python version/path to use
  • --dist, --lib: Create a package for distribution
  • --backend: Specify the build backend, which implies --dist
  • --license: Specify the license (SPDX name)
  • --name: Specify the project name
  • --project-version: Specify the project's version
  • --no-git: Do not initialize a git repository (default: False)

install#

Check the lockfile, resolve if needed, and install dependencies

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • --override: Use the constraint file in pip-requirements format for overriding. [env var: PDM_OVERRIDE] This option can be used multiple times. See https://pip.pypa.io/en/stable/user_guide/#constraints-files
  • --dry-run: Show the difference only and don't perform any action
  • -L, --lockfile: Specify another lockfile path. Default: pdm.lock. [env var: PDM_LOCKFILE]
  • --frozen-lockfile, --no-lock: Don't try to create or update the lockfile. [env var: PDM_FROZEN_LOCKFILE]
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • --venv NAME: Run the command in the virtual environment with the given key. [env var: PDM_IN_VENV]
  • --check: Check if the lock file is up to date and fail otherwise
  • --plugins: Install the plugins specified in pyproject.toml

Install Options:

  • --no-editable: Install non-editable versions for all packages. [env var: PDM_NO_EDITABLE]
  • --no-self: Don't install the project itself. [env var: PDM_NO_SELF]
  • --fail-fast, -x: Abort on first installation error
  • --no-isolation: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.
  • --config-setting, -C: Pass options to the builder. Options with a value must be specified after "=": --config-setting=key(=value) or -Ckey(=value)

Dependencies Selection:

  • -G, --group, --with GROUP: Select group of optional-dependencies separated by comma or dependency-groups (with -d). Can be supplied multiple times, use :all to include all groups under the same species.
  • --without: Exclude groups of optional-dependencies or dependency-groups
  • --no-default: Don't include dependencies from the default group (default: False)
  • -d, --dev: Select dev dependencies
  • --prod, --production: Unselect dev dependencies (default: True)

Creates a missing lockfile or updates an outdated one, then installs the selected locked packages. Does not change dependency declarations in pyproject.toml or remove unrelated installed packages. Refreshing an existing lockfile preserves its locked groups; run pdm lock with the desired groups before installing a group not yet locked. --check refuses a missing or outdated lockfile but still installs when it is fresh. --frozen-lockfile prevents lockfile writes, not dependency resolution.

list#

List packages installed in the current working set

Positional Arguments:

  • patterns: Filter packages by patterns. e.g. pdm list requests- flask-. In --tree mode, only show the subtree of the matched packages.

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • --venv NAME: Run the command in the virtual environment with the given key. [env var: PDM_IN_VENV]
  • --freeze: Show the installed dependencies in pip's requirements.txt format
  • --tree, --graph: Display a tree of dependencies
  • -r, --reverse: Reverse the dependency tree
  • --resolve: Resolve all requirements to output licenses (instead of just showing those currently installed)
  • --fields: Select information to output as a comma separated string. All fields: groups,homepage,licenses,location,name,version. (default: name,version,location)
  • --sort: Sort the output using a given field name. If nothing is set, no sort is applied. Multiple fields can be combined with ','.
  • --csv: Output dependencies in CSV document format
  • --json: Output dependencies in JSON document format
  • --markdown: Output dependencies and legal notices in markdown document format - best effort basis
  • --include: Dependency groups to include in the output. By default all are included
  • --exclude: Exclude dependency groups from the output

lock#

Resolve dependencies and write the lockfile without installing packages

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • -L, --lockfile: Specify another lockfile path. Default: pdm.lock. [env var: PDM_LOCKFILE]
  • --no-isolation: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.
  • --config-setting, -C: Pass options to the builder. Options with a value must be specified after "=": --config-setting=key(=value) or -Ckey(=value)
  • --override: Use the constraint file in pip-requirements format for overriding. [env var: PDM_OVERRIDE] This option can be used multiple times. See https://pip.pypa.io/en/stable/user_guide/#constraints-files
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • --refresh: Refresh the lock input metadata and file hashes in the lock file
  • --check: Check if the lock file is up to date and quit
  • --update-reuse: Reuse pinned versions already present in lock file if possible (default: all)
  • --update-reuse-installed: Reuse installed packages if possible
  • --exclude-newer: Exclude packages newer than the given UTC date in format YYYY-MM-DD\[THH:MM:SSZ\] or relative time N{d|h|w}
  • --exclude-newer-override PACKAGE=DATE: Override exclude-newer for specific packages; use PACKAGE=false to disable the cutoff

Lock Target:

  • --python: The Python range to lock for. E.g. >=3.9, ==3.12.*
  • --platform: The platform to lock for. E.g. windows, linux, macos, manylinux_2_17_x86_64. See docs for available choices: http://pdm-project.org/en/latest/usage/lock-targets/
  • --implementation: The Python implementation to lock for. E.g. cpython, pypy, pyston
  • --append: Append the result to the current lock file

Lock Strategy:

  • --strategy, -S STRATEGY: Specify lock strategy (cross_platform, static_urls, direct_minimal_versions, inherit_metadata). Add 'no_' prefix to disable. Can be supplied multiple times or split by comma.
  • --no-cross-platform: [DEPRECATED] Only lock packages for the current platform
  • --static-urls: [DEPRECATED] Store static file URLs in the lockfile
  • --no-static-urls: [DEPRECATED] Do not store static file URLs in the lockfile

Dependencies Selection:

  • -G, --group, --with GROUP: Select group of optional-dependencies separated by comma or dependency-groups (with -d). Can be supplied multiple times, use :all to include all groups under the same species.
  • --without: Exclude groups of optional-dependencies or dependency-groups
  • --no-default: Don't include dependencies from the default group (default: False)
  • -d, --dev: Select dev dependencies
  • --prod, --production: Unselect dev dependencies (default: True)

Reads requirements from pyproject.toml for the selected groups and writes the selected lockfile. Does not change pyproject.toml. Does not install or remove packages. With no group-selection options, an existing lockfile keeps its recorded groups; use -G:all to lock all declared groups. Lock strategy flags are also remembered unless changed with --strategy.

new#

Create a new Python project at

Positional Arguments:

  • template: Specify the project template, which can be a local path or a Git URL
  • project_path: The path to create the new project

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • -r, --overwrite: Overwrite existing files

Builtin Generator Options:

  • -n, --non-interactive: Don't ask questions but use default values
  • --python: Specify the Python version/path to use
  • --dist, --lib: Create a package for distribution
  • --backend: Specify the build backend, which implies --dist
  • --license: Specify the license (SPDX name)
  • --name: Specify the project name
  • --project-version: Specify the project's version
  • --no-git: Do not initialize a git repository (default: False)

outdated#

Check for outdated packages and list the latest versions on indexes.

Positional Arguments:

  • patterns: The packages to check

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • --json: Output in JSON format (default: table)
  • --include-sub: Include sub-dependencies

publish#

Build and publish the project to PyPI

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • -r, --repository: The repository name or url to publish the package to [env var: PDM_PUBLISH_REPO]
  • -u, --username: The username to access the repository [env var: PDM_PUBLISH_USERNAME]
  • -P, --password: The password to access the repository [env var: PDM_PUBLISH_PASSWORD]
  • -S, --sign: Upload the package with PGP signature
  • -i, --identity: GPG identity used to sign files.
  • -c, --comment: The comment to include with the distribution file.
  • --no-build: Don't build the package before publishing (default: False)
  • -d, --dest: The directory to upload the package from (default: dist)
  • --skip-existing: Skip uploading files that already exist. This may not work with some repository implementations.
  • --no-verify-ssl, --no-very-ssl: Disable SSL verification
  • --ca-certs: The path to a PEM-encoded Certificate Authority bundle to use for publish server validation [env var: PDM_PUBLISH_CA_CERTS]

python#

Manage installed Python interpreters

Options:

  • -h, --help: Show this help message and exit.

Commands:

list#

List all Python interpreters installed with PDM

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

remove#

Remove a Python interpreter installed with PDM

Positional Arguments:

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

install#

Install a Python interpreter with PDM

Positional Arguments:

  • version: The Python version to install (e.g. [email protected]). If left empty, highest cPython version that matches this platform/arch is installed. If pyproject.toml with requires-python is available, this is considered as well.

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --list, -l: List all available Python versions
  • --min: Use minimum instead of highest version for installation if version is left empty

Link an external Python interpreter to PDM

Positional Arguments:

  • interpreter: The path to the Python interpreter to link

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --name: The name of the link

find#

Search for a Python interpreter

Positional Arguments:

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --managed: Only find interpreters managed by PDM

py#

Manage installed Python interpreters

Options:

  • -h, --help: Show this help message and exit.

Commands:

list#

List all Python interpreters installed with PDM

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

remove#

Remove a Python interpreter installed with PDM

Positional Arguments:

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

install#

Install a Python interpreter with PDM

Positional Arguments:

  • version: The Python version to install (e.g. [email protected]). If left empty, highest cPython version that matches this platform/arch is installed. If pyproject.toml with requires-python is available, this is considered as well.

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --list, -l: List all available Python versions
  • --min: Use minimum instead of highest version for installation if version is left empty

Link an external Python interpreter to PDM

Positional Arguments:

  • interpreter: The path to the Python interpreter to link

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --name: The name of the link

find#

Search for a Python interpreter

Positional Arguments:

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --managed: Only find interpreters managed by PDM

remove#

Remove packages from pyproject.toml

Positional Arguments:

  • packages: Specify the packages to remove

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • --dry-run: Show the difference only and don't perform any action
  • -L, --lockfile: Specify another lockfile path. Default: pdm.lock. [env var: PDM_LOCKFILE]
  • --override: Use the constraint file in pip-requirements format for overriding. [env var: PDM_OVERRIDE] This option can be used multiple times. See https://pip.pypa.io/en/stable/user_guide/#constraints-files
  • --frozen-lockfile, --no-lock: Don't try to create or update the lockfile. [env var: PDM_FROZEN_LOCKFILE]
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • --venv NAME: Run the command in the virtual environment with the given key. [env var: PDM_IN_VENV]
  • -d, --dev: Remove packages from dev dependencies
  • -G, --group: Specify the target dependency group to remove from
  • --no-sync: Only write pyproject.toml and do not uninstall packages (default: False)

Install Options:

  • --no-editable: Install non-editable versions for all packages. [env var: PDM_NO_EDITABLE]
  • --no-self: Don't install the project itself. [env var: PDM_NO_SELF]
  • --fail-fast, -x: Abort on first installation error
  • --no-isolation: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.
  • --config-setting, -C: Pass options to the builder. Options with a value must be specified after "=": --config-setting=key(=value) or -Ckey(=value)

run#

Run commands or scripts with local packages loaded

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • --venv NAME: Run the command in the virtual environment with the given key. [env var: PDM_IN_VENV]
  • -l, --list: Show all available scripts defined in pyproject.toml
  • -j, --json: Output all scripts infos in JSON

Execution Parameters:

  • -s, --site-packages: Load site-packages from the selected interpreter
  • --recreate: Recreate the script environment for self-contained scripts
  • --env KEY=VALUE: Set environment variables for the script. Can be supplied multiple times
  • --env-file FILE: Read environment variables from the given dotenv file
  • --working-dir DIR: Set the working directory for the script
  • script: The command to run
  • args: Arguments that will be passed to the command

Search for PyPI packages

Positional Arguments:

  • query: Query string to search

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

self#

Manage the PDM program itself (previously known as plugin)

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

Commands:

list#

List all packages installed with PDM

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --plugins: List plugins only

add#

Install packages to the PDM's environment

Positional Arguments:

  • packages: Specify one or many package names, each package can have a version specifier

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --pip-args: Arguments that will be passed to pip install

remove#

Remove packages from PDM's environment

Positional Arguments:

  • packages: Specify one or many package names

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --pip-args: Arguments that will be passed to pip uninstall
  • -y, --yes: Answer yes on the question

update#

Update PDM itself

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --head: Update to the latest commit on the main branch
  • --pre: Update to the latest prerelease version
  • --no-frozen-deps: Do not install frozen dependency versions (default: False)
  • --pip-args: Additional arguments that will be passed to pip install

plugin#

Manage the PDM program itself (previously known as plugin)

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

Commands:

list#

List all packages installed with PDM

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --plugins: List plugins only

add#

Install packages to the PDM's environment

Positional Arguments:

  • packages: Specify one or many package names, each package can have a version specifier

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --pip-args: Arguments that will be passed to pip install

remove#

Remove packages from PDM's environment

Positional Arguments:

  • packages: Specify one or many package names

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --pip-args: Arguments that will be passed to pip uninstall
  • -y, --yes: Answer yes on the question

update#

Update PDM itself

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • --head: Update to the latest commit on the main branch
  • --pre: Update to the latest prerelease version
  • --no-frozen-deps: Do not install frozen dependency versions (default: False)
  • --pip-args: Additional arguments that will be passed to pip install

show#

Show the package information

Positional Arguments:

  • package: Specify the package name, or show this package if not given

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • --venv NAME: Run the command in the virtual environment with the given key. [env var: PDM_IN_VENV]
  • --name: Show name
  • --version: Show version
  • --summary: Show summary
  • --license: Show license
  • --platform: Show platform
  • --keywords: Show keywords

sync#

Install selected locked packages without updating the lockfile

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • --dry-run: Show the difference only and don't perform any action
  • -L, --lockfile: Specify another lockfile path. Default: pdm.lock. [env var: PDM_LOCKFILE]
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • --clean: Clean packages not in the lockfile
  • --only-keep, --clean-unselected: Only keep the selected packages
  • --venv NAME: Run the command in the virtual environment with the given key. [env var: PDM_IN_VENV]
  • -r, --reinstall: Force reinstall existing dependencies

Install Options:

  • --no-editable: Install non-editable versions for all packages. [env var: PDM_NO_EDITABLE]
  • --no-self: Don't install the project itself. [env var: PDM_NO_SELF]
  • --fail-fast, -x: Abort on first installation error
  • --no-isolation: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.
  • --config-setting, -C: Pass options to the builder. Options with a value must be specified after "=": --config-setting=key(=value) or -Ckey(=value)

Dependencies Selection:

  • -G, --group, --with GROUP: Select group of optional-dependencies separated by comma or dependency-groups (with -d). Can be supplied multiple times, use :all to include all groups under the same species.
  • --without: Exclude groups of optional-dependencies or dependency-groups
  • --no-default: Don't include dependencies from the default group (default: False)
  • -d, --dev: Select dev dependencies
  • --prod, --production: Unselect dev dependencies (default: True)

Reads group selections from pyproject.toml without changing it. Requires an existing lockfile and installs its pinned versions for the selected groups. Does not resolve new versions or update the lockfile. Keeps unrelated installed packages by default. --clean removes packages absent from the whole lockfile; --clean-unselected also removes packages outside the selected groups.

update#

Update locked dependency versions and install them

Update Strategy:

  • --update-reuse: Reuse pinned versions already present in lock file if possible
  • --update-eager: Try to update the packages and their dependencies recursively
  • --update-all: Update all dependencies and sub-dependencies
  • --update-reuse-installed: Reuse installed packages if possible

Save Strategy:

  • --save-compatible: Save compatible version specifiers
  • --save-safe-compatible: Save safe compatible version specifiers
  • --save-wildcard: Save wildcard version specifiers
  • --save-exact: Save exact version specifiers
  • --save-minimum: Save minimum version specifiers

Positional Arguments:

  • packages: If packages are given, only update them

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • -L, --lockfile: Specify another lockfile path. Default: pdm.lock. [env var: PDM_LOCKFILE]
  • --frozen-lockfile, --no-lock: Don't try to create or update the lockfile. [env var: PDM_FROZEN_LOCKFILE]
  • --override: Use the constraint file in pip-requirements format for overriding. [env var: PDM_OVERRIDE] This option can be used multiple times. See https://pip.pypa.io/en/stable/user_guide/#constraints-files
  • --pre, --prerelease: Allow prereleases to be pinned
  • --stable: Only allow stable versions to be pinned (default: True)
  • -u, --unconstrained: Ignore the version constraints in pyproject.toml and overwrite with new ones from the resolution result
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • --venv NAME: Run the command in the virtual environment with the given key. [env var: PDM_IN_VENV]
  • -t, --top: Only update those listed in pyproject.toml
  • --dry-run, --outdated: Show the difference only without modifying the lockfile content
  • --no-sync: Only update lock file but do not sync packages (default: False)

Install Options:

  • --no-editable: Install non-editable versions for all packages. [env var: PDM_NO_EDITABLE]
  • --no-self: Don't install the project itself. [env var: PDM_NO_SELF]
  • --fail-fast, -x: Abort on first installation error
  • --no-isolation: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.
  • --config-setting, -C: Pass options to the builder. Options with a value must be specified after "=": --config-setting=key(=value) or -Ckey(=value)

Dependencies Selection:

  • -G, --group, --with GROUP: Select group of optional-dependencies separated by comma or dependency-groups (with -d). Can be supplied multiple times, use :all to include all groups under the same species.
  • --without: Exclude groups of optional-dependencies or dependency-groups
  • --no-default: Don't include dependencies from the default group (default: False)
  • -d, --dev: Select dev dependencies
  • --prod, --production: Unselect dev dependencies

Resolves updates for the requested packages or selected groups, writes the lockfile, and installs the selected dependencies. Version constraints in pyproject.toml are kept unless --unconstrained is given. Existing locked groups are preserved, and the update strategy controls which pins are reused. Use --no-sync to leave installed packages unchanged.

use#

Use the given python version or path as base interpreter. If not found, PDM will try to install one.

Positional Arguments:

  • python: Specify the Python version or path

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -g, --global: Use the global project, supply the project root with -p option
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • -k, --skip: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use :all to skip all hooks. Use :pre and :post to skip all pre or post hooks.
  • -f, --first: Select the first matched interpreter - no auto install
  • --auto-install-min: If python argument not given, auto install minimal best match - otherwise has no effect
  • --auto-install-max: If python argument not given, auto install maximum best match - otherwise has no effect
  • -i, --ignore-remembered: Ignore the remembered selection
  • --no-version-file: Do not write .python-version file (default: False)
  • --venv: Use the interpreter in the virtual environment with the given name

venv#

Virtualenv management

Options:

  • -h, --help: Show this help message and exit.
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and __pypackages__ [env var: PDM_PROJECT]
  • --path: Show the path to the given virtualenv
  • --python: Show the python interpreter path for the given virtualenv

Commands:

create#

Create a virtualenv

Positional Arguments:

  • python: Specify which python should be used to create the virtualenv
  • venv_args: Additional arguments that will be passed to the backend

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -w, --with: Specify the backend to create the virtualenv
  • -f, --force: Recreate if the virtualenv already exists
  • -n, --name: Specify the name of the virtualenv
  • --with-pip: Install pip with the virtualenv

list#

List all virtualenvs associated with this project

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

remove#

Remove the virtualenv with the given name

Positional Arguments:

  • env: The key of the virtualenv

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -y, --yes: Answer yes on the following question

activate#

Print the command to activate the virtualenv with the given name

Positional Arguments:

  • env: The key of the virtualenv

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output

purge#

Purge selected/all created Virtualenvs

Options:

  • -h, --help: Show this help message and exit.
  • -v, --verbose: Use -v for detailed output and -vv for more detailed
  • -q, --quiet: Suppress output
  • -f, --force: Force purging without prompting for confirmation
  • -i, --interactive: Interactively purge selected Virtualenvs