UV cheatsheet

What is UV?

uv is an extremely fast Python package installer and resolver, written in Rust. Think of it as a next-generation replacement for pip and pip-tools (or poetry, pdm for dependency resolution), designed for speed and reliability.

It aims to be the universal tool for managing your Python projects’ dependencies and virtual environments.

Why UV is So Fast

uv‘s speed comes from several factors:

• Rust-based: Rust is known for its performance and memory safety.
• Parallelism: It can download and install packages concurrently.
• Optimized Resolver: Its dependency resolver is highly efficient.
• Disk Cache: It aggressively caches packages, avoiding redundant downloads.

Key Differences from Pip

Feature	Pip	UV
Speed	Can be slow, especially for large projects	Blazing fast for installation and resolution
Resolver	Satisfies dependencies one-by-one	Resolves entire dependency graph at once (like pip-tools or poetry)
Virtual Environments	Requires python -m venv	Built-in uv venv command for creation and management
Lock Files	No native support (needs pip-tools)	Built-in support (uv pip compile)
Commands	pip install, pip uninstall	uv pip install, uv pip uninstall, uv venv, uv init

Getting Started (80% of Use Cases)

1. Installation

Install uv globally:

pip install uv
# Or, for the absolute latest version:
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Creating a Virtual Environment

With uv, you don’t need python -m venv. uv handles it directly.

• Default Naming: If you’re inside a project directory (e.g., one with a pyproject.toml or requirements.txt), uv will create a .venv directory by default when you run uv venv or uv init.
• Custom Naming: To create a virtual environment with a specific name:
  • uv venv my-project-env
    This creates my-project-env in the current directory.
• Why a Venv for Every Project?
  • Previously, you might have preferred one large virtual environment to avoid long installation times.
  • With uv‘s speed, creating a dedicated virtual environment for each project is now highly recommended. It keeps project dependencies isolated and prevents conflicts, without the performance penalty. Enjoy seeing it be fast!

3. Activating Your Virtual Environment

After creating, activate it:
Linux/macOS:

source .venv/bin/activate
# Or for a custom-named venv:
# source my-project-env/bin/activate

Windows (CMD):

.venv\Scripts\activate.bat

Windows (PowerShell):

.venv\Scripts\Activate.ps1

4. Installing Packages

Once activated, use uv pip install just like you would pip install:

uv pip install requests pandas

5. Installing from requirements.txt

uv pip install -r requirements.txt

6. Synchronizing Dependencies

This is a powerful command, especially when managing dependencies from a requirements.txt or pyproject.toml (with a lock file). It ensures your environment exactly matches the specified dependencies, adding missing packages and removing unneeded ones.

uv pip sync

Understanding uv init

uv init is a command to quickly set up a new or existing Python project for uv.

• If no pyproject.toml exists, it creates one with a basic [project] section.
• It automatically creates a virtual environment named .venv in your project root.
• It’s a convenient one-shot command to get your project ready for uv‘s dependency management.

cd your_project_directory
uv init

pyproject.toml and python-version

uv embraces the modern pyproject.toml standard for project configuration.

• pyproject.toml: This file acts as a central configuration for your Python project, replacing older files like setup.py, setup.cfg, and requirements.txt for certain tools. It can define project metadata, dependencies, build backends, and tool-specific configurations (like for uv).

• python-version: Within pyproject.toml, you can specify the Python version your project requires. uv will respect this when creating virtual environments or resolving dependencies.

Example pyproject.toml snippet:

# pyproject.toml
[project]
name = "my-awesome-app"
version = "0.1.0"
dependencies = [
    "requests~=2.31.0",
    "fastapi~=0.104.0",
]

[tool.uv]
python-version = "3.10" # This tells uv which Python version to use for the venv

Common UV Commands at a Glance

Command	Description
uv venv [name]	Create a new virtual environment (default: .venv, or specified name)
uv pip install PKG	Install packages from PyPI
uv pip install -r FILE	Install packages from a requirements.txt file
uv pip uninstall PKG	Uninstall packages
uv pip freeze	Output installed packages in requirements.txt format
uv pip list	List installed packages
uv pip sync	Synchronize the environment with specified dependencies (e.g., from a lock file)
uv pip compile	Compile abstract dependencies (pyproject.toml, requirements.in) into a lock file (requirements.txt)
uv init	Initialize a project with pyproject.toml and a .venv

Things to Look Out For

• Still Maturing: While very stable for common tasks, uv is under active development. Keep your uv installation updated (pip install --upgrade uv).
• Cache Location: uv uses a global cache. If you encounter issues, clearing the cache might help (uv cache clean).
• Python Versions: Ensure the python-version in your pyproject.toml (if used) matches an available Python interpreter on your system.