PDM - Python Development Master

A modern Python package manager with PEP 582 support.

What is PDM?

PDM is meant to be a next generation Python package management tool.
It was originally built for personal use. If you feel you are going well
with Pipenv or Poetry and don't want to introduce another package manager,
just stick to it. But if you are missing something that is not present in those tools,
you can probably find some goodness in pdm.

PEP 582 proposes a project structure as below:


There is a __pypackages__ directory in the project root to hold all dependent libraries, just like what npm does.
Read more about the specification here.

Highlights of features

  • PEP 582 local package installer and runner, no virtualenv involved at all.
  • Simple and relatively fast dependency resolver, mainly for large binary distributions.
  • A PEP 517 build backend.
  • A full-featured plug-in system.
  • PEP 621 project metadata format.

Why not virtualenv?

The majority of Python packaging tools also act as virtualenv managers to gain the ability
to isolate project environments. But things get tricky when it comes to nested venvs: One
installs the virtualenv manager using a venv encapsulated Python, and create more venvs using the tool
which is based on an encapsulated Python. One day a minor release of Python is released and one has to check
all those venvs and upgrade them if required.

PEP 582, on the other hand, introduces a way to decouple the Python interpreter from project
environments. It is a relative new proposal and there are not many tools supporting it (one that does
is [pyflow]), but it is written with Rust and thus can't get much help from the big Python community.
For the same reason it can't act as a PEP 517 backend.


PDM requires python version 3.7 or higher.

If you are on MacOS and using homebrew, install it by:

$ brew install pdm

Otherwise, it is recommended to install pdm in an isolated environment with pipx:

$ pipx install pdm

Or you can install it under a user site:

$ pip install --user pdm


Initialize a new PDM project

$ pdm init

Answer the questions following the guide, and a PDM project with a pyproject.toml file will be ready to use.

Install dependencies into the __pypackages__ directory

$ pdm add requests flask

You can add multiple dependencies in the same command. After a while, check the pdm.lock file to see what is locked for each package.

Run your script with PEP 582 support

Suppose you have a script app.py placed next to the __pypackages__ directory with the following content(taken from Flask's website):

from flask import Flask
app = Flask(__name__)

def hello_world():
    return 'Hello World!'

if __name__ == '__main__':

If you are a Bash user, set the environment variable by eval $(pdm --pep582). Now you can run the app directly with your familiar Python interpreter:

$ python /home/frostming/workspace/flask_app/app.py
 * Serving Flask app "app" (lazy loading)
 * Running on (Press CTRL+C to quit)

Ta-da! You are running an app with its dependencies installed in an isolated place, while no virtualenv is involved.

For Windows users, please refer to the doc about how to make it work.

If you are curious about how this works, check this doc section for some explanation.

Docker image

$ docker pull frostming/pdm