PDM: A smarter way to manage Python packages

Modern Python developers use virtual environments (venvs), to keep their projects and dependencies separate. Managing project dependencies gets more complex as the number of dependencies grows. Luckily, a variety of third-party tools provide sophisticated package management behaviors that aren’t found in core tools like pip.

This article introduces PDM, the Python Development Master. PDM is a Python package manager that rolls together several package- and virtual-environment-management features, all built atop standards native to the Python ecosystem. It can also be used to build and publish Python projects, run scripts or packages within a project, use plugins that hook into various PDM behaviors, and create projects from predefined templates.

Also see: How to manage Python projects with Poetry.

Setting up PDM

PDM installs in Python 3.7 or higher. It’s best to install PDM into the user directory accessed by your Python installation, rather than in any Python installation itself. The PDM documentation explains how to do this. Alternatively, pip install --user pdm is a reliable, automatic way to get the same result.

Once you’ve installed PDM properly, you should be able to run the pdm command on the command line. If you’re dealing with multiple Python installations on Windows, you can (and should) use py -m pdm to trigger PDM from the proper Python version.

The pdm command is also used to manage PDM itself. For instance, you can type pdm self update to update PDM to the most recent version.

Managing project dependencies

To set up a project to use PDM, go to where you want to create the project directory in the console and type pdm new, where is the name of the project and its directory name. You can also use pdm init in an existing directory to start a new PDM-managed project there.

To add dependencies to the project, use pdm add. You can list more than one dependency, and you should specify them using the standard in PEP 508. In other words, they should look like the dependency entries in a standard requirements.txt file. To remove a dependency, use pdm remove.

Two things worth keeping in mind when adding or removing dependencies:

Each time you add or remove a dependency, PDM recomputes the project’s dependency graph, which may take some time.

When you remove a dependency, any dependencies that depend solely on the one you removed are not automatically removed, but they can be cleaned up semi-automatically. (More on this later.)

To list the dependencies in a project, use pdm list. Or you can use pdm list --graph to show dependencies in a tree, so that you can see at-a-glance which packages depend on which other packages.

To ensure all dependencies are installed as needed, you can use one of two commands:

pdm install, the more commonly used of the two, should be your first choice. It will create the lock file—the description of package versions to use with the project—and then install the dependencies from that.

pdm sync uses a slightly different strategy. If a lock file doesn’t already exist, it will throw an error; otherwise, it will install the dependencies listed in the existing lock file. This is useful if you want to quickly install only from an existing lock file without recomputing dependencies (which takes more time).

Managing optional and development dependencies

By default, any dependencies installed to a PDM-managed project are installed without indicating their function in the project. For instance, if you install the black code formatter using pdm add black, PDM won’t identify it as a dependency needed exclusively for development versus one used for runtime.

If you want to tag dependencies for specific uses, you can use the -dG (dependency group) option, along with a group name, to group them. For instance, we could use pdm add -dG dev black to install black to a subgroup of dependencies labeled dev.

You can also specify that a given dependency should be installed only for production use by using pdm add -d. For instance, if we used the module regex in the production application, but not in development, we would add it with pdm add -d regex.

Updating and cleaning PDM dependencies

PDM-controlled dependencies can be updated all at once by typing pdm update, updated individually by using a package name (pdm update ), or updated as a group by using the group name (pdm update -G ).

By default, packages pinned to a specific version will be kept to that version. You can forcibly update pinned packages to their latest versions by passing the --update-eager flag.

If you want to remove packages that are no longer needed, run pdm sync --clean. Make sure you only do this in the context of a project, and never in your systemwide Python installations.

Running Python programs with PDM

PDM lets you run packages or scripts in your project with the pdm run command—e.g., pdm run black. invokes the black formatter, while pdm run myscript.py runs a given Python file.

PDM can also run single-file scripts. Python’s PEP 723 added a feature called “inline script metadata,” where Python files that start with a specially formatted comment block can describe dependencies and other requirements a la pyproject.toml. When you call pdm run to run a Python file that has this type of data, PDM will create a temporary virtual environment to contain the needed dependencies.

Using __pypackages__ with PDM

PDM was originally created to take advantage of a feature described in PEP 582, which has since been rejected. This idea was to allow a project to contain a directory, __pypackages__, where packages could be bundled as dependencies for a project without using a virtual environment. In other words, the packages could be stored directly in the project’s source tree, but in a way that didn’t interfere with its directory structure. Such packages would not have to be installed into the project’s venv as part of its setup process.

PEP 582 was not approved for Python generally, but PDM-managed projects can use the __pypackages__ directory on a per-project or global basis. A good use case for this would be if you wanted to vendor custom-modified packages into a project. On the whole, though, PDM recommends using venvs, as they’re the more broadly supported solution for isolating project requirements.