A newbie's guide to pdm, Your Lifeline Out of Python Dependency Hell

December 9, 2024 | python

I recently started a personal project working with the newly open-sourced Foursquare Places dataset. I was using srai, a Python library for spatial analysis, to process the geospatial data when I ran into some module errors. The issues stemmed from a dependency conflict with h3ropy, which underwent some recent updates causing several breaking changes within the srai library. When I looked into fixing this issue and opened a PR, I noticed that srai used something called pdm for its dependency management. This was new to me - I’ve always used pip and requirements.txt files to manage Python project dependencies. While my traditional approach has worked, I’ve had my fair share of dependency hell experiences, so I was more than willing to give pdm a try. Since the contribution guide for srai requires using pdm to set up the development environment, I decided to learn more about it. I found that PDM promises better and faster dependency resolution, particularly for complex Python projects. I wanted to share my notes on getting started with PDM, in case others are looking to give it a try.

Why `pdm`?

PDM stands out for several reasons, the most important of which is its fast and reliable dependency resolution.

Getting Started

Installing pdm is straightforward:

# Choose one:
pip install pdm
pipx install pdm  # Recommended for global installation

Similarly, creating a new project is equally simple. After creating a new project directory, you can run the following command to initialize the project:

pdm init  # Interactive project setup
pdm init --python 3.9  # Specify Python version directly

The init command walks you through creating a pyproject.toml file - your new single source of truth for project configuration. This follows the PEP 518 and PEP 621 specifications, bringing modern package management practices to Python.

Managing Python Versions

One of PDM’s strengths is its flexible Python version management. To check the current python interpreter version, you can run the following command:

# Check current Python info
pdm info

To switch the python interpreter version, you can run the following command:

pdm use python3.9  # Use a specific python version
pdm use /path/to/interpreter  # Use a specific interpreter
pdm use -f /path/to/virtualenv  # Use a virtual environment

Dependency Management Made Simple

To add dependencies to your project, you can run the pdm add command, in several different ways:

# Add core dependencies
pdm add numpy pandas

# Add development (dev environment) dependencies
pdm add -dG dev black pytest

# Add from git repositories
pdm add git+https://github.com/user/repo.git

This creates a clean separation in your pyproject.toml:

[tool.pdm.dev-dependencies]
dev = ["black", "pytest"]

Updating Dependencies

Similarly, pdm provides several ways to update dependencies, depending on the user’s own needs:

pdm update  # Update all dependencies
pdm update black  # Update specific package
pdm update -G dev  # Update the dependencies in the dev group
pdm update -G dev black  # Update a specific package in the dev group