uv

The uv tool is a Python package and project manager written in Rust. Even though the first version was only released in February of 2024, its feature set is growing rapidly, just like its popularity inside the community. In case you can only bring a single tool to a remote island, pick uv.

The features illustrate how uv is designed to be a single command that can replace various other tools, including pip, pipx, pipenv, poetry, pyenv, venv and more. A lot of effort has been put in optimizing for speed, starting from how it downloads package metadata and resolves dependencies, to how it caches the packages in a central location and then reflinks them into the individual venvs.

Usage

Installation

There are various ways to install uv. If you already have Python installed, feel free to use pip[x]. Without any Python installed you can bootstrap your host by simply downloading the binary from the upstream releases, as uv can then even install Python for you.

Projects

The concept of Python project basically refers to whenever you write your own code and need to manage its dependencies. In order to use uv, start by creating a minimal pyproject.toml.

[project]
name = "samplename"
version = "0.1.0"
description = "Add your description here"

Then add dependencies as needed,

$ uv add pandas

where each package will be automatically added to the pyproject.toml, installed inside a new venv and tracked with all its dependencies inside the cross-platform uv.lock.

You can also flag dependencies with --dev as only required for development, but not for production. Command-line tools, like linter, can directly be run from inside the venv using uv run.

$ uv add --dev ruff
$ uv run ruff check

Tip

Always add pyproject.toml and uv.lock to your version-control system. Not only does it help your collaborators to use the same package versions, but it also tracks all package updates in the git history.

Your collaborators can then clone the repo and call uv sync to install all package versions exactly as defined in your lock file.

$ uv sync --frozen --extra=dev

The pip interface helps to run pip-like commands inside the venv.

$ uv pip list             # list installed packages
$ uv pip freeze           # list installed packages in requirements format
$ uv pip tree             # show dependency graph of installed packages
$ uv pip check            # check for package conflicts of missing deps

Tools

Conceptually a Python tool is any package that provides a command-line interface. The motivation to manage such tools differently was already provided when discussing pipx and the usage is also similar.

$ uv tool install ruff    # install given command-line tool inside dedicated venv
$ uv tool run ruff check  # run given command-line tool
$ uv tool install --with ansible-lint ansible   # install tool and extra dep inside same venv
$ uv tool list            # show list of installed tools
$ uv tool upgrade ruff    # upgrade tool to latest version
$ uv tool update-shell    # add ~/.local/bin to $PATH to make all tools directly callable

Cache

Given that uv aggressively caches already downloaded packages, you may occasionally want to inspect and drop the cache.

$ uv cache dir            # show path to cache directory
$ uv cache prune          # delete unused cache files
$ uv cache clean <pkg>    # delete given package from cache
$ uv cache clean          # delete all packages from cache