Manage Dependencies#
PDM provides a bunch of handful commands to help manage your project and dependencies. The following examples are run on Ubuntu 18.04, a few changes must be done if you are using Windows.
Initialize a project#
1 2 |
|
Answer several questions asked by PDM and a pyproject.toml
will be created for you in the project root:
1 2 3 4 5 6 7 8 9 10 11 |
|
If pyproject.toml
is already present, it will be updated with the metadata. The metadata format follows the
PEP 621 specification
For details of the meaning of each field in pyproject.toml
, please refer to Project File.
Add dependencies#
1 |
|
pdm add
can be followed by one or several dependencies, and the dependency specification is described in
PEP 508.
PDM also allows extra dependency groups by providing -G/--group <name>
option, and those dependencies will go to
[project.optional-dependencies.<name>]
table in the project file, respectively.
You can reference other optional groups in optional-dependencies
, even before the package is uploaded:
1 2 3 4 5 6 7 8 |
|
After that, dependencies and sub-dependencies will be resolved properly and installed for you, you can view pdm.lock
to see the resolved result of all dependencies.
Local dependencies#
Local packages can be added with their paths. The path can be a file or a directory:
1 2 |
|
The paths MUST start with a .
, otherwise it will be recognized as a normal named requirement.
VCS dependencies#
You can also install from a git repository url or other version control systems. The following are supported:
- Git:
git
- Mercurial:
hg
- Subversion:
svn
- Bazaar:
bzr
The URL should be like: {vcs}+{url}@{rev}
Examples:
1 2 3 4 5 6 7 8 9 10 |
|
Add development only dependencies#
New in 1.5.0
PDM also supports defining groups of dependencies that are useful for development,
e.g. some for testing and others for linting. We usually don't want these dependencies appear in the distribution's metadata
so using optional-dependencies
is probably not a good idea. We can define them as development dependencies:
1 |
|
This will result in a pyproject.toml as following:
1 2 |
|
For backward-compatibility, if only -d
or --dev
is specified, dependencies will go to dev
group under [tool.pdm.dev-dependencies]
by default.
Note
The same group name MUST NOT appear in both [tool.pdm.dev-dependencies]
and [project.optional-dependencies]
.
Editable dependencies#
Local directories and VCS dependencies can be installed in editable mode. If you are familiar with pip
, it is just like pip install -e <package>
. Editable packages are allowed only in development dependencies:
Note
Editable installs are only allowed in the dev
dependency group. Other groups, including the default, will fail with a [PdmUsageError]
.
1 2 3 4 5 6 |
|
Save version specifiers#
If the package is given without a version specifier like pdm add requests
. PDM provides three different behaviors of what version
specifier is saved for the dependency, which is given by --save-<strategy>
(Assume 2.21.0
is the latest version that can be found
for the dependency):
minimum
: Save the minimum version specifier:>=2.21.0
(default).compatible
: Save the compatible version specifier:>=2.21.0,<3.0.0
.exact
: Save the exact version specifier:==2.21.0
.wildcard
: Don't constrain version and leave the specifier to be wildcard:*
.
Add prereleases#
One can give --pre/--prerelease
option to pdm add
so that prereleases are allowed to be pinned for the given packages.
Update existing dependencies#
To update all dependencies in the lock file:
1 |
|
To update the specified package(s):
1 |
|
To update multiple groups of dependencies:
1 |
|
To update a given package in the specified group:
1 |
|
If the group is not given, PDM will search for the requirement in the default dependencies set and raises an error if none is found.
To update packages in development dependencies:
1 2 3 4 |
|
About update strategy#
Similarly, PDM also provides 2 different behaviors of updating dependencies and sub-dependencies,
which is given by --update-<strategy>
option:
reuse
: Keep all locked dependencies except for those given in the command line (default).eager
: Try to lock a newer version of the packages in command line and their recursive sub-dependencies and keep other dependencies as they are.all
: Update all dependencies and sub-dependencies.
Update packages to the versions that break the version specifiers#
One can give -u/--unconstrained
to tell PDM to ignore the version specifiers in the pyproject.toml
.
This works similarly to the yarn upgrade -L/--latest
command. Besides, pdm update
also supports the
--pre/--prerelease
option.
Remove existing dependencies#
To remove existing dependencies from project file and the library directory:
1 2 3 4 5 6 |
|
Install the packages pinned in lock file#
There are a few similar commands to do this job with slight differences:
pdm sync
installs packages from the lock file.pdm update
will update the lock file, thensync
.pdm install
will check the project file for changes, update the lock file if needed, thensync
.
sync
also has a few options to manage installed packages:
--clean
: will remove packages no longer in the lockfile--only-keep
: only selected packages (using options like-G
or--prod
) will be kept.
Specify the lockfile to use#
You can specify another lockfile than the default pdm lock
by using the -L/--lockfile <filepath>
option or the PDM_LOCKFILE
environment variable.
Select a subset of dependencies with CLI options#
Say we have a project with following dependencies:
1 2 3 4 5 6 7 8 9 10 |
|
Command | What it does | Comments |
---|---|---|
pdm install |
install prod and dev deps (no optional) | |
pdm install -G extra1 |
install prod deps, dev deps, and "extra1" optional group | |
pdm install -G dev1 |
install prod deps and only "dev1" dev group | |
pdm install -G:all |
install prod deps, dev deps and "extra1", "extra2" optional groups | |
pdm install -G extra1 -G dev1 |
install prod deps, "extra1" optional group and only "dev1" dev group | |
pdm install --prod |
install prod only | |
pdm install --prod -G extra1 |
install prod deps and "extra1" optional | |
pdm install --prod -G dev1 |
Fail, --prod can't be given with dev dependencies |
Leave the --prod option |
All development dependencies are included as long as --prod
is not passed and -G
doesn't specify any dev groups.
Besides, if you don't want the root project to be installed, add --no-self
option, and --no-editable
can be used when you want all packages to be installed in non-editable versions. With --no-editable
turn on, you can safely archive the whole __pypackages__
and copy it to the target environment for deployment.
Show what packages are installed#
Similar to pip list
, you can list all packages installed in the packages directory:
1 |
|
Or show a dependency graph by:
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Set PyPI index URL#
You can specify a PyPI mirror URL by following commands:
1 |
|
Allow prerelease versions to be installed#
Include the following setting in pyproject.toml
to enable:
1 2 |
|
Set acceptable format for locking or installing#
If you want to control the format(binary/sdist) of the packages, you can set the env vars PDM_NO_BINARY
and PDM_ONLY_BINARY
.
Each env var is a comma-separated list of package name. You can set it to :all:
to apply to all packages. For example:
1 2 3 4 5 6 |
|
Solve the locking failure#
If PDM is not able to find a resolution to satisfy the requirements, it will raise an error. For example,
1 2 3 4 5 6 7 |
|
You can either change to a lower version of django
or remove the upper bound of asgiref
. But if it is not eligible for your project,
you can tell PDM to forcedly resolve asgiref
to a specific version by adding the following lines to pyproject.toml
:
New in version 1.12.0
1 2 3 4 |
|
Each entry of that table is a package name with the wanted version. In this example, PDM will resolve the above packages into the given versions no matter whether there is any other resolution available.
Note
By using [tool.pdm.resolution.overrides]
setting, you are at your own risk of any incompatibilities from that resolution. It can only be used if there is no valid resolution for your requirements and you know the specific version works.
Most of the time, you can just add any transient constraints to the dependencies
array.