uv.md

Working with Python Packages (uv)

Recent versions of Pegasus use uv to manage Python packages. It provides all the functionality of pip-tools while being much faster and offering more flexibility and features.

Requirements Files

uv uses two files to manage requirements. The first is a pyproject.toml file, which contains the base list of packages. The pyproject.toml file also supports dependency groups, which are used for development and production requirements. pyproject.toml replaces the previous requirements.in, dev-requirements.in, and prod-requirements.in files.

The second file is the uv.lock file. This file contains the pinned versions of dependencies that are used by the project's environment. This file is automatically generated from the pyproject.toml file and should not be edited by hand. uv.lock replaces the previous requirements.txt, dev-requirements.txt, and prod-requirements.txt files.

Adding or removing a package

To add or remove packages you can run the following commandss:

# native version
uv add <package_name>
uv remove <package_name>

# docker version
make uv add <package_name>
make uv remove <package_name>

If you're using natively this is all you have to do! The command will update your pyproject.toml file, your uv.lock file, and sync your virtual environment.

On Docker, you will have to also rebuild the container. You can do that with:

make build
make restart

The make requiements command can also be used to sync your uv.lock file and rebuild / restart your containers.

Upgrading a package

You can upgrade a package with:

# native version - update the lockfile
uv lock --upgrade-package <package_name>
# native version - update the lockfile and sync the virtual environment
uv sync --upgrade-package <package_name>

# docker version
make uv "lock --upgrade-package wagtail"

You can upgrade all packages with:

# native version - update the lockfile
uv lock --upgrade
# native version - update the lockfile and sync the virtual environment
uv sync --upgrade

# docker version
make uv "lock --upgrade"

Like with adding packages, if you're using Docker, you'll have to rebuild and restart Docker containers for the updated environment to work:

make build
make restart