UV is an extremely fast Python package installer and resolver, written in Rust. It's a drop-in replacement for pip, pip-tools, and virtualenv, offering 10-100x faster performance.
# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# With pip
pip install uv
# With pipx
pipx install uv
# With Homebrew
brew install uvuv init myproject # Create new project
uv init --lib mylib # Create library project
uv init --app myapp # Create application project
uv init . # Initialize in current directoryuv add requests # Add dependency
uv add pytest --dev # Add dev dependency
uv add "django>=4.0" # Add with version constraint
uv remove requests # Remove dependency
uv sync # Install all dependencies
uv lock # Update lockfileuv run python script.py # Run Python script
uv run pytest # Run pytest
uv run -- python -c "print('hello')" # Run arbitrary commanduv venv # Create .venv in current directory
uv venv myenv # Create named environment
uv venv --python 3.11 # Specify Python version
uv venv --python python3.12 # Use specific Python executable
uv venv --seed # Include pip and setuptools# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate
# Or use uv run (no activation needed)
uv run python script.pyuv pip install requests # Install package
uv pip install requests==2.31.0 # Specific version
uv pip install "requests>=2.30,<3.0" # Version range
uv pip install -e . # Editable install
uv pip install -r requirements.txt # From requirements fileuv pip install package --index-url URL # Custom index
uv pip install package --extra-index-url URL # Additional index
uv pip install --no-deps package # Skip dependencies
uv pip install --force-reinstall package # Force reinstall
uv pip install git+https://github.com/user/repo.git # From gituv pip uninstall requests # Uninstall package
uv pip uninstall -r requirements.txt # Uninstall from fileuv pip list # List installed packages
uv pip list --format json # JSON format
uv pip show requests # Show package details
uv pip freeze # Output installed packages
uv pip freeze > requirements.txt # Save to fileuv pip compile requirements.in # Compile dependencies
uv pip compile requirements.in -o requirements.txt
uv pip compile pyproject.toml # From pyproject.toml
uv pip compile --upgrade # Upgrade all packages
uv pip compile --upgrade-package requests # Upgrade specific packageuv pip sync requirements.txt # Sync to exact state
uv pip sync requirements.txt --strict # Remove unlisted packagesuv python install 3.11 # Install Python 3.11
uv python install 3.12.0 # Specific version
uv python list # List available versions
uv python list --only-installed # Show installed versionsuv venv --python 3.11 # Create venv with specific version
uv run --python 3.12 script.py # Run with specific versionuv run script.py # Run Python script
uv run --with requests script.py # Run with extra packages
uv run --with 'requests>=2.30' script.py # With version constraintuv tool install ruff # Install tool globally
uv tool install black --force # Force reinstall tool
uv tool list # List installed tools
uv tool uninstall ruff # Uninstall tool
uv tool run ruff check . # Run tool without installing
uvx ruff check . # Shorthand for tool run[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"requests>=2.30.0",
"pydantic>=2.0.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.0.0",
"ruff>=0.1.0",
]
[tool.uv]
dev-dependencies = [
"pytest>=7.0.0",
]
[tool.uv.sources]
mypackage = { git = "https://github.com/user/repo.git" }# Environment variables
export UV_INDEX_URL="https://pypi.org/simple"
export UV_EXTRA_INDEX_URL="https://extra.pypi.org/simple"
export UV_CACHE_DIR="~/.cache/uv"
export UV_NO_CACHE=1 # Disable cache
export UV_PYTHON="3.11" # Default Python version[tool.uv]
index-url = "https://pypi.org/simple"
extra-index-url = ["https://extra.pypi.org/simple"]
no-cache = false
native-tls = true
[tool.uv.pip]
index-url = "https://pypi.org/simple"uv cache clean # Clean all cache
uv cache clean requests # Clean specific package
uv cache dir # Show cache directory
uv cache prune # Remove old cache entriesuv pip freeze > requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip compile pyproject.toml -o requirements.txt# requirements.in
requests
django>=4.0
# requirements-dev.in
-c requirements.txt
pytest
black
# Compile both
uv pip compile requirements.in -o requirements.txt
uv pip compile requirements-dev.in -o requirements-dev.txtuv pip install package --no-build-isolation # Skip build isolation
uv pip install package --no-binary :all: # No binary packages
uv pip install package --only-binary :all: # Only binary packages
uv pip install package -j 4 # Parallel downloads (4 threads)
uv pip install package --link-mode=copy # Copy instead of symlink| Command | pip | uv |
|---|---|---|
| Install package | pip install pkg |
uv pip install pkg |
| Create venv | python -m venv .venv |
uv venv |
| Compile deps | pip-compile |
uv pip compile |
| Sync deps | pip-sync |
uv pip sync |
| Run script | python script.py |
uv run script.py |
uv init myproject
cd myproject
uv add requests pytest
uv run python -c "import requests; print(requests.__version__)"# If you have requirements.txt
uv pip install -r requirements.txt
# If you have setup.py or pyproject.toml
uv pip install -e .
# Generate lock file
uv pip compile pyproject.toml -o requirements.txt# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies
uv sync --locked
# Run tests
uv run pytestuv pip install package -v # Verbose output
uv pip install package -vv # Extra verbose
uv pip install package --no-cache # Bypass cache
uv version # Check UV version
uv self update # Update UV itself[project]
name = "my-project"
version = "0.1.0"
description = "My project"
dependencies = [
"requests>=2.31.0",
"pandas>=2.0.0",
]
requires-python = ">=3.11"
[project.optional-dependencies]
dev = [
"ruff>=0.1.0",
"pytest>=7.0.0",
]
docs = [
"sphinx>=6.0.0",
]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.uv]
default-groups = ["dev", "docs"]
no-build = false
native-tls = false
[tool.uv.pip]
extra-index-url = ["https://pypi.org/simple"]
find-links = ["https://download.pytorch.org/whl/cu118"]
no-index = false
- Use
uv runinstead of activating: Automatically uses project environment - Lock your dependencies: Use
uv lockto ensure reproducible builds - Leverage caching: UV's cache makes reinstalls extremely fast
- Use pyproject.toml: Modern standard for Python projects
- Pin versions in production: Use
uv pip compilefor reproducibility - Keep UV updated:
uv self updatefor latest features and fixes
- Documentation: https://docs.astral.sh/uv/
- GitHub: https://github.com/astral-sh/uv
- Discord: https://discord.gg/astral-sh