uv is an extremely fast Python package and project manager, written in Rust. It serves as a unified replacement for pip, pip-tools, poetry, pyenv, virtualenv, and more.
Install uv:
# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Using pip (not recommended for main usage, but possible)
pip install uv
Upgrade uv:
uv self update
Shell Autocompletion:
# Example for bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
uv allows you to manage Python projects with pyproject.toml and a cross-platform uv.lock.
Initialize a Project:
# Create a new project
uv init my-project
# Initialize in current directory
uv init
Manage Dependencies:
# Add a dependency
uv add requests
# Add a specific version
uv add 'requests==2.31.0'
# Add a development dependency
uv add --dev pytest
# Remove a dependency
uv remove requests
Sync Environment:
# Sync virtual environment with lockfile (creates .venv if needed)
uv sync
# specific extras
uv sync --all-extras
Run Commands in Project Scope:
# Runs command in the project's environment (auto-syncs if needed)
uv run python main.py
uv run pytest
uv can run standalone scripts and manage their dependencies automatically without manual virtual environments.
Run a Script:
# Run a script (auto-creates ephemeral environment)
uv run script.py
Run with Dependencies (Ad-hoc):
# Requires 'rich' and 'requests' available for this run
uv run --with rich --with requests script.py
Inline Script Metadata: Standardized way to declare dependencies inside the script (PEP 723).
# /// script
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
import requests
from rich.pretty import pprint
# ...
Run it simply with:
uv run script.py
Execute and install Python command-line tools (similar to pipx).
Run a Tool Ephemerally (uvx):
# Run 'ruff' without installing it globally
uvx ruff check .
# Run a secure shell with 'httpie'
uvx httpie https://google.com
Install Tools Globally:
# Install 'ruff' tool
uv tool install ruff
# List installed tools
uv tool list
# Upgrade installed tools
uv tool upgrade --all
uv can manage Python installations itself, replacing pyenv.
Install Python:
# Install latest Python
uv python install
# Install specific versions
uv python install 3.12 3.11
List Available Versions:
uv python list
Pin Python Version for Project:
# Creates/Updates .python-version file
uv python pin 3.11
uv provides a drop-in replacement for pip commands, useful for legacy workflows or CI.
# Install packages into current environment
uv pip install requests
# specific requirements file
uv pip install -r requirements.txt
# Compile requirements (pip-compile replacement)
uv pip compile requirements.in -o requirements.txt
# Sync environment (pip-sync replacement)
uv pip sync requirements.txt
Common Environment Variables:
UV_CACHE_DIR: Directory for uv cache.UV_PROJECT_ENVIRONMENT: Path to the virtual environment (default: .venv).UV_PYTHON_DOWNLOADS: Control python downloads (auto [default], manual, never).UV_NATIVE_TLS: Set true to use system certificate store (important for corporate certs).HTTP_PROXY / HTTPS_PROXY: Standard proxy settings.UV_INDEX_URL / UV_EXTRA_INDEX_URL: Default and extra package indexes.pyproject.toml Configuration: Example for a data analysis project (not installed as a package).
[project]
name = "analysis-project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
"pandas",
"numpy",
"jupyterlab",
"polars",
# GitHub dependency (name only here, details in tool.uv.sources)
"internal-tools",
]
[tool.uv]
package = false # Important: Prevents building this project itself as a package
[tool.uv.sources]
# robust reproducibility: pin git tag/commit for github deps
internal-tools = { git = "https://github.com/my-org/internal-tools", tag = "v1.0.2" }
torch = { index = "pytorch" }
# Custom Index (e.g. for CUDA specific pytorch)
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
PEP 723 allows defining dependencies directly within a script file. This replaces the need for uv run --no-project --with ... in many persistent cases.
Example script.py:
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
import requests
from rich.pretty import pprint
print("Running with self-contained dependencies!")
Run it:
uv run script.py
uv will automatically detect the metadata block, create an ephemeral environment, install requests and rich, and execute the script.
--no-project: Run a command ignoring the current project context.--with: Add ephemeral dependencies to a run command.--refresh: Force refresh of cached data.uv cache clean to clear.