Skip to content

CLI Reference#

pdm#

Optional Arguments:

  • -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: -v for detailed output and -vv for more detailed
  • -I, --ignore-python: Ignore the Python path saved in the .pdm.toml config
  • --pep582 SHELL: Print the command line to be eval'd by the shell

Commands:

add#

Add package(s) to pyproject.toml and install them

Package Arguments:

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

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • -L, --lockfile: Specify another lockfile path. Default: pdm.lock. [env var: PDM_LOCKFILE]
  • --save-compatible: Save compatible version specifiers
  • --save-wildcard: Save wildcard version specifiers
  • --save-exact: Save exact version specifiers
  • --save-minimum: Save minimum version specifiers
  • --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-depenencies
  • --pre, --prerelease: Allow prereleases to be pinned
  • -u, --unconstrained: Ignore the version constraint of packages
  • --dry-run: Show the difference only and don't perform any action
  • -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: True)

Install Options:

  • --no-editable: Install non-editable versions for all packages
  • --no-self: Don't install the project itself
  • --no-isolation: Do not isolate the build in a clean environment

build#

Build artifacts for distribution

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and pypackages
  • --no-isolation: Do not isolate the build in a clean environment
  • -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.
  • --no-sdist: Don't build source tarballs(default: True)
  • --no-wheel: Don't build wheels(default: True)
  • -d, --dest: Target directory to put artifacts(default: dist)
  • --no-clean: Do not clean the target directory(default: True)
  • --config-setting, -C: Pass options to the backend. options with a value must be specified after "=": "--config-setting=--opt(=value)" or "-C--opt(=value)"

cache#

Control the caches of PDM

Sub Commands:

clear#

Clean all the files under cache directory

Positional Arguments:

  • type: Clear the given type of caches

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed

remove#

Remove files matching the given pattern

Positional Arguments:

  • pattern: The pattern to remove

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed

list#

List the built wheels stored in the cache

Positional Arguments:

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

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed

info#

Show the info and current size of caches

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed

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.

Optional Arguments:

  • -h, --help: show this help message and exit

config#

Display the current configuration

Positional Arguments:

  • key: Config key
  • value: Config value

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • -l, --local: Set config in the project's local configuration file
  • -d, --delete: Unset a configuration key

export#

Export the locked packages set to other formats

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • -L, --lockfile: Specify another lockfile path. Default: pdm.lock. [env var: PDM_LOCKFILE]
  • -f, --format: Specify the export file format(default: requirements)
  • --without-hashes: Don't include artifact hashes(default: True)
  • -o, --output: Write output to the given file, or print to stdout if not given
  • --pyproject: Read the list of packages from pyproject.toml

Dependencies Selection:

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

import#

Import project metadata from other formats

Positional Arguments:

  • filename: The file name

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • -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

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • --python: Show the interpreter path
  • --where: Show the project root path
  • --packages: Show the packages root
  • --env: Show PEP 508 environment markers

init#

Initialize a pyproject.toml for PDM

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • -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.
  • -n, --non-interactive: Don't ask questions but use default values

install#

Install dependencies from lock file

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • --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.
  • --no-lock: Don't do lock if the lock file is not found or outdated(default: True)
  • --check: Check if the lock file is up to date and fail otherwise

Install Options:

  • --no-editable: Install non-editable versions for all packages
  • --no-self: Don't install the project itself
  • --no-isolation: Do not isolate the build in a clean environment

Dependencies Selection:

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

list#

List packages installed in the current working set

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • --graph: Display a graph of dependencies
  • --freeze: Show the installed dependencies in pip's requirements.txt format
  • --json: Show the installed dependencies in JSON document format
  • -r, --reverse: Reverse the dependency graph

lock#

Resolve and lock dependencies

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • -L, --lockfile: Specify another lockfile path. Default: pdm.lock. [env var: PDM_LOCKFILE]
  • --no-isolation: Do not isolate the build in a clean environment
  • -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: Don't update pinned versions, only refresh the lock file

plugin#

Manage the PDM plugins

Sub Commands:

list#

List all plugins installed with PDM

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed

add#

Install new plugins with PDM

Positional Arguments:

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

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • --pip-args: Arguments that will be passed to pip install

remove#

Remove plugins from PDM's environment

Positional Arguments:

  • packages: Specify one or many plugin names

Optional Arguments:

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

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed

publish#

Build and publish the project to PyPI

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -p, --project: Specify another path as the project root, which changes the base of pyproject.toml and pypackages
  • -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: True)

remove#

Remove packages from pyproject.toml

Positional Arguments:

  • packages: Specify the packages to remove

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • --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.
  • -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: True)

Install Options:

  • --no-editable: Install non-editable versions for all packages
  • --no-self: Don't install the project itself
  • --no-isolation: Do not isolate the build in a clean environment

run#

Run commands or scripts with local packages loaded

Positional Arguments:

  • command: The command to run
  • args: Arguments that will be passed to the command

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • -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.
  • -l, --list: Show all available scripts defined in pyproject.toml
  • -s, --site-packages: Load site-packages from the selected interpreter

search#

Search for PyPI packages

Positional Arguments:

  • query: Query string to search

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed

show#

Show the package information

Positional Arguments:

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

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • --name: Show name
  • --version: Show version
  • --summary: Show summary
  • --license: Show license
  • --platform: Show platform
  • --keywords: Show keywords

sync#

Synchronize the current working set with lock file

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • --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]
  • -r, --reinstall: Force reinstall existing dependencies
  • -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: only keep the selected packages

Install Options:

  • --no-editable: Install non-editable versions for all packages
  • --no-self: Don't install the project itself
  • --no-isolation: Do not isolate the build in a clean environment

Dependencies Selection:

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

update#

Update package(s) in pyproject.toml

Positional Arguments:

  • packages: If packages are given, only update them

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • -L, --lockfile: Specify another lockfile path. Default: pdm.lock. [env var: PDM_LOCKFILE]
  • --save-compatible: Save compatible version specifiers
  • --save-wildcard: Save wildcard version specifiers
  • --save-exact: Save exact version specifiers
  • --save-minimum: Save minimum version specifiers
  • --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-depenencies
  • --pre, --prerelease: Allow prereleases to be pinned
  • -u, --unconstrained: Ignore the version constraint of packages
  • -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.
  • -t, --top: Only update those list 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: True)

Install Options:

  • --no-editable: Install non-editable versions for all packages
  • --no-self: Don't install the project itself
  • --no-isolation: Do not isolate the build in a clean environment

Dependencies Selection:

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

use#

Use the given python version or path as base interpreter

Positional Arguments:

  • python: Specify the Python version or path

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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
  • -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
  • -i, --ignore-remembered: Ignore the remembered selection

venv#

Virtualenv management

Positional Arguments:

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

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -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

list#

List all virtualenvs associated with this project

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed

remove#

Remove the virtualenv with the given name

Positional Arguments:

  • env: The key of the virtualenv

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed
  • -y, --yes: Answer yes on the following question

activate#

Activate the virtualenv with the given name

Positional Arguments:

  • env: The key of the virtualenv

Optional Arguments:

  • -h, --help: show this help message and exit
  • -v, --verbose: -v for detailed output and -vv for more detailed

purge#

Purge selected/all created Virtualenvs

Optional Arguments:

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

Optional Arguments:

  • -h, --help: show this help message and exit