Skip to content

Introduction#

PDM is a modern Python package manager with PEP 582 support. It installs and manages packages in a similar way to npm that doesn't need to create a virtualenv at all!

Feature highlights#

  • 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.
  • PEP 621 project metadata.

Installation#

PDM requires Python 3.7+ to be installed. It works on multiple platforms including Windows, Linux and MacOS.

Note

There is no restriction about what Python version that your project is using but installing PDM itself needs Python 3.7+.

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

1
$ brew install pdm

Otherwise, to avoid messing up with the system Python environemnt, the most recommended way to install PDM is via pipx:

1
$ pipx install pdm

Other installation methods#

Install PDM into user site with pip:

1
$ pip install --user pdm

Enable PEP 582 globally#

To make the Python interpreters aware of PEP 582 packages, one need to add the pdm/pep582/sitecustomize.py to the Python library search path.

For Windows users#

One just needs to execute pdm --pep582, then environment variable will be changed automatically. Don't forget to restart the terminal session to take effect.

For Mac and Linux users#

The command to change the environment variables can be produced by pdm --pep582 [<SHELL>]. If <SHELL> isn't given, PDM will pick one based on some guesses.

You may want to write a line in your .bash_profile(or similar profiles) to make it effective when login. For example, in bash you can do this:

1
$ pdm --pep582 >> ~/.bash_profile

Once again, Don't forget to restart the terminal session to take effect.

This setup may become the default in the future.

Use the docker image#

PDM also provides a docker image to ease your deployment flow, to use it, write a Dockerfile with following content:

1
2
3
4
5
6
FROM frostming/pdm

COPY . /app

# -- Replace with the correct path to your app's main executable
CMD ["pdm", "run", "python", "main.py"]

Shell Completion#

PDM supports generating completion scripts for Bash, Zsh, Fish or Powershell. Here are some common locations for each shell:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# Bash
$ pdm completion bash > /etc/bash_completion.d/pdm.bash-completion

# Zsh
# Make sure ~/.zfunc is added to fpath, before compinit.
$ pdm completion zsh > ~/.zfunc/_pdm

# Oh-My-Zsh
$ mkdir $ZSH_CUSTOM/plugins/pdm
$ pdm completion zsh > $ZSH_CUSTOM/plugins/pdm/_pdm
# Then make sure pdm plugin is enabled in ~/.zshrc

# Fish
$ pdm completion fish > ~/.config/fish/completions/pdm.fish

# Powershell
# Create a directory to store completion scripts
PS > mkdir $PROFILE\..\Completions
PS > echo @'
Get-ChildItem "$PROFILE\..\Completions\" | ForEach-Object {
    . $_.FullName
}
'@ | Out-File -Append -Encoding utf8 $PROFILE
# Generate script
PS > Set-ExecutionPolicy Unrestricted -Scope CurrentUser
PS > pdm completion powershell | Out-File -Encoding utf8 $PROFILE\..\Completions\pdm_completion.ps1

Unicode and ANSI supports#

PDM provides a fancy terminal UI with the help of ANSI characters and unicode emojis. It can turn on/off automitically depending on whether it is supported on your terminal. Otherwise if you see any garbled characters, set env var DISABLE_UNICODE_OUTPUT=1 to turn off it.

Use with IDE#

Now there are not built-in support or plugins for PEP 582 in most IDEs, you have to configure your tools manually.

PDM will write and store project-wide configurations in .pdm.toml and you are recommended to add following lines in the .gitignore:

1
2
.pdm.toml
__pypackages__/

PyCharm#

Mark __pypackages__/<major.minor>/lib as Sources Root.

VSCode#

Add following in the settings.json:

1
2
3
4
{
  ...
  "python.autoComplete.extraPaths": ["__pypackages__/<major.minor>/lib"]
}