uv
uv is a high-performance Python package and project manager that provides a unified interface for installing Python versions, managing dependencies, creating virtual environments, running scripts, building packages, and publishing to package indexes.
Note
This is a reference guide for uv. For a tutorial on how to use uv, see Create your first Python project.
Why uv?
Traditional Python development involves juggling multiple tools (e.g. pip, pip-tools, pipx, poetry, pyenv, virtualenv), each with different interfaces and behaviors. uv unifies these workflows while delivering 10-100x performance improvements over existing solutions.
- Speed: 10-100x faster than traditional Python tools
- Simplicity: One tool for all Python packaging needs
- Standards: Full compatibility with modern Python packaging standards
- Reliability: Reproducible builds with universal lockfiles
Installation
Quick Install
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
See the official installation guide for more methods.
Command Categories
Project Management
Projects use pyproject.toml for configuration and uv.lock
for dependency locking.
# Initialize new project
uv init my-project
# Add dependencies
uv add requests
uv add --dev pytest # development dependency
# Install project and dependencies
uv sync
# Run commands in project environment
uv run python main.py
uv run pytest
# Build distributions
uv build
# Publish to PyPI
uv publish
Script Execution
Run standalone Python scripts with automatic dependency management.
# Run script with inline dependencies
uv run script.py
# Run with additional dependencies
uv run --with requests script.py
# Add dependencies to script metadata
uv add --script script.py requests
Inline Script Dependencies
uv allows you to specify dependencies for a script in the script itself, using the dependencies
key.
Run uv add --script script.py requests rich
to add the requests
and rich
dependencies to your script.
# /// script
# dependencies = ["requests", "rich"]
# requires-python = ">=3.8"
# ///
import requests
from rich import print
Note
Inline script dependencies are a PEP 723 compliant way to specify dependencies for a script.
Tool Management
Install and run Python-based CLI tools in isolated environments.
# Run tool temporarily
uvx ruff .
# Install tool globally
uv tool install ruff
# Upgrade tools
uv tool upgrade ruff
uv tool upgrade --all
pip-Compatible Interface
uv provides a drop-in replacement for pip/pip-tools workflows with enhanced performance.
# Create virtual environment
uv venv
# Install packages
uv pip install requests
uv pip install -r requirements.txt
uv pip install -e . # editable install
# Generate lockfiles
uv pip compile requirements.in
uv pip compile --universal requirements.in # cross-platform
# Sync environment with lockfile
uv pip sync requirements.txt
Learn More
- Create your first Python project
- Setting up testing with pytest and uv
- Run your first Python script with uv
- uv documentation
- Installation guide
- Package management
- Project management
- Python version management
- Tool management
Also Mentioned In
- uvhow: Get uv upgrade instructions for your uv install
- uv 0.8 Release: Automatic Python Installation to PATH
- Hynek Schlawack's uv Workflow Guide
- The uv build backend is now stable
- Managing Python Versions In Your uv Projects
- Pyrefly: Meta's New Type Checker for Python
- Why uv makes Make less essential for Python projects
- The Python Tooling Revolution
- Simple, Modern Python
- Conda
- Create your first Python project
- How do pyenv and uv compare for Python interpreter management?
- How to add dynamic versioning to uv projects
- How to add Python to your system path with uv
- How to configure Claude Code to use uv
- How to configure Cursor rules to use uv
- How to Fix ModuleNotFoundError: No module named 'numpy' During pip Install
- How to fix Python version incompatibility errors in uv
- How to install uv
- How to migrate from Poetry to uv
- How to migrate from requirements.txt to pyproject.toml with uv
- How to Run a Jupyter Notebook with uv
- How to run the IPython shell in your uv project
- How to try the ty type checker
- How to upgrade uv
- How to Use `--exclude-newer` for Reproducible Python Environments
- How to use a uv lockfile for reproducible Python environments
- How to use pip in a uv virtual environment
- How to Use Poe the Poet as a Task Runner with uv
- How to write self-contained Python scripts using PEP 723 inline metadata
- pip
- Publishing Your First Python Package to PyPI
- pyproject.toml
- Run your first Python script
- Setting up testing with pytest and uv
- ty
- What is a .python-version file?
- What is a lockfile?
- What is a Python package?
- What is PEP 751?
- Why are there so many Python packaging tools?
- Why does uv Use Hatch as a backend?
- Why Should I Choose pyproject.toml over requirements.txt for managing dependencies?
- Why should I use a virtual environment?