Enhanced uv Cheat Sheet

A comprehensive guide to using `uv`, the fast Python package installer and resolver.

Installation

curl -LsSf https://astral.sh/uv/install.sh | sh

Installs the latest version of uv.

Python Installation & Management

uv python install <version> – Install a specific Python version (e.g., 3.11, 3.12.1, pypy-3.10).
uv python list – List available Python versions that can be installed by uv.
uv python pin <version> – Pin a specific installed Python version for the current project (creates .python-version).

uv uses standalone Python builds, managed independently from system Python.

Virtual Environments

uv venv [.venv] [--python <version_or_path>] – Create a virtual environment (defaults to .venv). Optionally specify a Python version (e.g., 3.12) or path.
source .venv/bin/activate – Activate the virtual environment (Linux/macOS).
.venv\Scripts\activate – Activate the virtual environment (Windows).
deactivate – Deactivate the current virtual environment.

If a virtual environment (like .venv) exists and is activated, uv commands will typically use it automatically.

Dependency & Project Management

uv distinguishes between simply installing packages (like pip install) and managing dependencies listed in pyproject.toml.

Adding/Removing from Project:
uv add <package> [--group <name>] – Add a package to pyproject.toml and install it. Use --group for optional dependencies (e.g., dev, test).
uv remove <package> [--group <name>] – Remove a package from pyproject.toml and uninstall it.
Direct Installation/Uninstallation (pip compatibility):
uv pip install <package> [...] – Install packages directly into the environment without modifying pyproject.toml. Accepts most pip install arguments.
uv pip install -r requirements.txt – Install packages from a requirements file.
uv pip install . – Install the current project (from pyproject.toml) into the environment.
uv pip install -e . – Install the current project in editable mode.
uv pip uninstall <package> [...] – Uninstall packages directly from the environment.
uv pip sync [--group <name>] [-r requirements.txt] – Synchronize the environment to match lockfiles (uv.lock, requirements.lock) or requirements files. Removes unlisted packages. Use --group to sync specific optional groups.
uv pip list – List installed packages in the environment.
uv pip freeze – Output installed packages in requirements format (like pip freeze).
uv pip check – Verify installed packages have compatible dependencies.
uv pip show <package> – Show details about an installed package.
uv pip install --upgrade <package> – Upgrade a specific package.
Locking:
uv lock [--exclude-newer <YYYY-MM-DD>] – Generate/update uv.lock based on pyproject.toml. Optionally exclude packages published after a certain date.

Running Commands

uv run <command> [args...] – Run a command within the project's managed environment (activates automatically).
```
uv run python manage.py runserver
```
uv run pytest

uv run ensures the command executes with the correct Python interpreter and dependencies available on PATH.

Disposable Environments / Running Tools

uv tool install <tool> [...] – Install a tool into uv's shared tool cache.
uv tool run <tool> [args...] – Run a tool (like black, ruff, mypy) in an isolated, temporary environment. Installs the tool if not already cached.
```
uv tool run black .
```
```
uv tool run ruff check .
```
uv tool list – List tools installed in the cache.
uv tool uninstall <tool> – Remove a tool from the cache.

This is ideal for running linters, formatters, etc., without polluting your project's dependencies.

Cache Management

uv cache clean – Clear uv's global cache (downloaded packages, builds, etc.).
uv cache dir – Show the location of the cache directory.

Key Differences & Notes

Speed: uv is significantly faster than pip + venv due to its Rust implementation and advanced caching/resolving.
uv add vs uv pip install: Use uv add to modify your project's declared dependencies (in pyproject.toml). Use uv pip install for direct, one-off installations into the environment (like traditional pip usage or installing from requirements files).
uv sync: Ensures the environment strictly matches the lockfile or requirements, removing extraneous packages. Use this for reproducible environments.
Project Awareness: uv often automatically detects the project root (where pyproject.toml or .git resides) and the associated virtual environment (.venv).