Skip to content

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.

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.

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

Terminal window
# 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:

Terminal window
make build
make restart

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

You can upgrade a package with:

Terminal window
# 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:

Terminal window
# 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:

Terminal window
make build
make restart