Python package management has historically required juggling several tools — pip for packages, virtualenv for environments, pyenv for Python versions, and poetry or pip-tools for dependency locking. uv replaces all of them with a single, blazing-fast binary written in Rust.

What is uv?

uv is an open-source Python package and project manager developed by Astral (the team behind the ruff linter). It is a drop-in replacement for pip, pip-tools, pipx, poetry, pyenv, virtualenv, and more — and it is typically 10–100× faster than the tools it replaces.

Key features:

• Installs and manages Python versions automatically
• Creates and manages virtual environments
• Resolves and locks dependencies via uv.lock
• Runs scripts and CLI tools in isolated environments
• Compatible with pyproject.toml and requirements.txt

Installation

Option 1: Standalone installer (recommended)

Open your terminal and run:

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

This downloads and installs the uv binary without requiring Python or Rust to be present beforehand. The installer will also update your shell profile (~/.zshrc or ~/.bash_profile) to add uv to your PATH.

Restart your terminal (or run source ~/.zshrc), then verify the installation:

uv --version

Option 2: Homebrew

If you already use Homebrew, you can install uv with:

brew install uv

Updating uv

uv self update

Managing Python Versions

One of uv’s most useful features is that it can download and manage Python interpreters for you — no need to install Python separately beforehand.

Install one or more Python versions:

uv python install 3.12 3.13

List available and installed versions:

uv python list

Pin a specific Python version for a project directory:

uv python pin 3.12

This writes a .python-version file that uv will respect automatically in that directory.

Starting a New Project

uv uses a project-centric workflow similar to npm or cargo.

Create a new project:

uv init myproject
cd myproject

This generates a pyproject.toml and a basic project structure.

Add a dependency:

uv add requests

This installs the package, adds it to pyproject.toml, and creates or updates a uv.lock lockfile.

Remove a dependency:

uv remove requests

Sync the environment with the lockfile:

uv sync

This ensures your virtual environment exactly matches what is declared in uv.lock — useful when pulling someone else’s project.

Virtual Environments

uv creates and manages a .venv directory automatically when you run uv sync or uv run. You can also create one explicitly:

uv venv

Or with a specific Python version:

uv venv --python 3.12

To activate the environment manually (e.g. for editor integration):

source .venv/bin/activate

In day-to-day use, you rarely need to activate the environment directly — uv run handles it for you.

Running Code

Run a script inside the project environment:

uv run python script.py

Open an interactive Python session:

uv run python

uv will automatically use the correct Python version and environment for your project.

Running One-off Tools with uvx

uvx (an alias for uv tool run) lets you run a CLI tool published as a Python package without installing it globally or polluting your project environment:

uvx ruff check .
uvx black --check .

Each invocation spins up a temporary isolated environment, runs the tool, and cleans up. You can also install tools globally for persistent use:

uv tool install ruff
ruff --version

pip-Compatible Interface

If you want the speed of uv without changing your existing workflow, uv provides a pip-compatible interface:

uv pip install flask
uv pip install -r requirements.txt
uv pip freeze
uv pip compile requirements.in --output-file requirements.txt

These commands behave like their pip/pip-tools equivalents but are significantly faster.

Common Workflow Cheatsheet

Further Reading

• uv documentation
• uv on GitHub
• uv command reference