uv — Python Package & Project Manager

uv is an extremely fast Python package and project manager written in Rust. It replaces pip, pip-tools, pipx, poetry, pyenv, virtualenv, and more with a single tool. If uv is available, always prefer it over pip and other Python tooling.

How uv handles Python (the short version)

uv manages its own Python installations from prebuilt standalone distributions (from Astral's python-build-standalone project). It will automatically download and install the right Python version when needed — you don't need to worry about pyenv, system Python, which python3, or any of that. When you run uv run or uv sync, uv ensures the correct Python is available, the virtual environment exists, and dependencies are installed. Trust the tool.

Check if uv is available

Before using uv, verify it's installed:

which uv && uv --version

If uv is not installed, you can install it with:

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

Then ensure it's on PATH: source $HOME/.local/bin/env (or restart the shell).

Decision Tree: Which uv workflow do I need?

Pick the right approach based on context:

1. Quick one-off script (no project structure)

You have a single .py file and just need to run it, possibly with some dependencies.

Run with ad-hoc dependencies:

uv run --with requests --with pandas my_script.py

Better: use inline script metadata (PEP 723) so dependencies are self-documenting:

# /// script
# dependencies = [
#   "requests",
#   "pandas>=2.0",
# ]
# ///

import requests
import pandas as pd
# ...

Then just:

uv run my_script.py

uv creates an isolated temporary environment, installs dependencies, runs the script. No venv activation, no pip install, no cleanup.

Add dependencies to an existing script:

uv add --script my_script.py requests pandas

2. Project with pyproject.toml

You're in a directory with (or creating) a structured Python project.

Initialize a new project:

uv init my-project
cd my-project

This creates pyproject.toml, .python-version, main.py, and a .gitignore.

Add dependencies:

uv add requests pandas numpy
uv add --dev pytest ruff  # dev-only dependencies

This updates pyproject.toml, resolves versions, updates uv.lock, and installs into .venv.

Remove dependencies:

uv remove pandas

Run commands in the project environment:

uv run python main.py
uv run pytest
uv run python -c "import requests; print(requests.__version__)"

uv run automatically ensures the environment is synced before execution. You do NOT need to activate the venv.

Sync the environment (install everything from the lockfile):

uv sync

Update the lockfile (after manual edits to pyproject.toml):

uv lock

3. Low-level pip-style commands (legacy / escape hatch)

Sometimes you need direct control — e.g., installing into a specific venv without a pyproject.toml, or working with an existing requirements.txt. uv provides a pip-compatible interface for this.

Create a virtual environment:

uv venv                    # creates .venv with default Python
uv venv --python 3.11      # creates .venv with Python 3.11
uv venv my-env             # creates my-env/ instead of .venv/

Install packages:

uv pip install requests pandas
uv pip install -r requirements.txt
uv pip install -e .                  # editable install of current project

List / inspect:

uv pip list
uv pip show requests
uv pip freeze

Important: uv pip install installs into the active venv (or .venv if found). It will NOT install into the system Python by default. If you need system-level installs (e.g., in a container), pass --system.

4. Running CLI tools (replacing pipx)

Need to run a tool like ruff, black, pytest, or jupyterlab without polluting your project?

uvx ruff check .               # run in ephemeral environment
uvx black my_file.py
uv tool install ruff           # install persistently, adds to PATH

Managing Python Versions

uv python install 3.12          # install a specific version
uv python install 3.10 3.11     # install multiple
uv python list                   # see what's available/installed
uv python pin 3.11              # pin current directory to 3.11

When you request a Python version (via .python-version, requires-python in pyproject.toml, or --python flag), uv will automatically download it if not already present.

Common Pitfalls & Anti-Patterns

❌ Don't: pip install <package>

Do: uv pip install <package> or better, uv add <package> (in a project).

Raw pip install bypasses uv's resolver, may install into the wrong environment, and won't update your lockfile.

❌ Don't: python -m venv .venv && source .venv/bin/activate && pip install ...

Do: uv venv && uv pip install ... or just use uv init + uv add for projects.

uv handles venv creation, Python version selection, and package installation in one coherent flow.

❌ Don't: activate the venv to run things

Do: uv run <command>

uv run handles environment syncing and activation transparently. You rarely need source .venv/bin/activate.

❌ Don't: pip install --break-system-packages

Do: uv pip install --system if you truly need system-level installs (containers, CI).

❌ Don't: worry about which Python is on PATH

Do: Let uv manage it. Use --python 3.11 or .python-version files to request versions. uv resolves the right interpreter automatically.

⚠️ Watch out: uv run in a project directory

If there's a pyproject.toml in the current or parent directory, uv run will try to install the project first. For standalone scripts that don't belong to the project, use:

uv run --no-project script.py

Quick Reference

Working with requirements.txt (Migration Path)

If a project has existing requirements.txt files:

# Create a project from existing requirements
uv init
uv add -r requirements.txt

# Or for low-level usage without a project
uv venv
uv pip install -r requirements.txt

To generate a locked requirements.txt from a project (e.g., for Docker):

uv export --format requirements-txt > requirements.txt