uv: The Blazing-Fast Python Packager #

uv is an extremely fast Python package installer and resolver, written in Rust. It’s designed to be a drop-in replacement for pip, pip-tools, virtualenv, and more, offering significant performance improvements.

🚀 Core Concepts #

Unified Tool: Aims to replace a fragmented toolchain with a single, cohesive binary.
Speed: 10-100x faster than pip and pip-tools due to its Rust architecture and intelligent caching.
Two Modes:
1. Project Mode: Manages dependencies through pyproject.toml (like Poetry or PDM) using commands like uv add, uv remove, and uv lock.
2. pip-like Mode: Acts as a direct, faster replacement for pip commands (uv pip install, uv pip sync, etc.).
Global Cache: Shares dependencies across projects to save disk space.

📦 Installation #

Install uv with the official script:

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

For Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

🌿 Virtual Environments #

uv automatically detects and uses a .venv in the current or parent directories.

Create a venv:

# Creates a .venv in the current directory
uv venv

# Specify a name and Python version
uv venv -p 3.11 my-env

Activate venv (Standard procedure):
- macOS/Linux: source .venv/bin/activate
- Windows: .venv\Scripts\activate
Deactivate venv:
```
deactivate
```

🏗️ Project Management (pyproject.toml) #

Use this mode for structured, reproducible projects.

Initialize a new project:
```
uv init
```
This creates a pyproject.toml file.

Add a dependency:

# Add to main dependencies
uv add requests

# Add to a dependency group (e.g., dev)
uv add -G dev pytest

Remove a dependency:

uv remove requests
uv remove -G dev pytest

Lock dependencies: Generates a uv.lock file from pyproject.toml for reproducible installs.
```
uv lock
```
Sync environment: Installs all packages from uv.lock into the virtual environment. This is the primary way to install project dependencies.
```
uv sync

# Sync specific dependency groups
uv sync --with dev
```

Update a package:

# Update a single package in pyproject.toml and the lockfile
uv add --upgrade requests

# Update all packages in the lockfile
uv lock --upgrade

⚡ pip-Compatible Commands #

For quick, one-off tasks or working with requirements.txt files.

Install packages:

# Install one or more packages
uv pip install requests flask

# Install from a requirements file
uv pip install -r requirements.txt

# Install the current project in editable mode
uv pip install -e .

Uninstall packages:
```
uv pip uninstall requests flask
```
List installed packages:
```
uv pip list
```
Freeze dependencies: Outputs installed packages in requirements.txt format.
```
uv pip freeze > requirements.txt
```

Compile requirements: A powerful replacement for pip-tools, this generates a locked requirements.txt from an input file.

# Create a requirements.in with your top-level dependencies
echo "flask" > requirements.in

# Compile it to a locked requirements.txt
uv pip compile requirements.in -o requirements.txt

🏃‍♀️ Running Scripts & Tools #

Run a command in the venv: Executes a command within the project’s managed environment without needing to activate it first.
```
uv run pytest
uv run python my_script.py
```

Run a tool from a temporary environment (like pipx):

uv tool run black --check .
uv tool run ruff format

Install a tool globally (in uv’s isolated environment):

uv tool install ruff
uv tool list
uv tool uninstall ruff

🐍 Python Version Management #

uv can install and manage Python versions for you.

Install a Python version:

uv python install 3.12
uv python install pypy@3.10

List available Pythons:
```
uv python list
```
Pin a project’s Python version: Creates a .python-version file.
```
uv python pin 3.12
```

🧹 Cache Management #

Show cache directory:
```
uv cache dir
```
Clean the cache: Removes all cached data, forcing re-downloads on the next run.
```
uv cache clean
```