uvThe only Python packaging system I've ever recommended
Andy Casey
with help from Lehman Garrison
uv?uv maintains a global package cacheNo more downloading and installing the same package versions
uv assigns integer IDs to package versionsconda might parse (m|b)illions of version string comparisons during resolution
conda tried to solve a different problem to pipconda caused community friction with licensing concernsuv has a different approach...Astral could disappear today and Python packaging would still be a solved problem (which I thought would never happen!)
uv?| Task | Traditional Tool | uv | Speedup |
|---|---|---|---|
| Install packages | pip | uv pip install | 10-100x |
| conda | uv pip install | Up to 106 | |
| Create venv | python -m venv | uv venv | 80x |
| Resolve deps | pip-tools | uv lock | 10-100x |
| Run tools | pipx | uvx | Faster |
Install uv with a single command:
# macOS/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 Homebrew
brew install uv
Create a virtual environment:
> uv venv
# uv will detect and use this environment
> uv pip install numpy
> uv run python
uv automatically detects and uses the virtual environment
# Install a package
uv pip install requests
# Install multiple packages
uv pip install requests pandas numpy
# Install from requirements.txt
uv pip install -r requirements.txt
# Install with specific version
uv pip install "django>=4.0,<5.0"
uv can install and manage Python itself!
# List available Python versions
uv python list
# Create a venv with a specific Python version
uv venv -p 3.14
# uv auto-installs missing Python versions as needed
# Initialize a new project
uv init my-project
cd my-project
# Add a dependency (updates pyproject.toml)
uv add requests
# Remove a dependency
uv remove requests
# Sync environment with project dependencies
uv sync
uv creates lock files to avoid version mis-matches
# Generate/update lock file
uv lock
# Install from lock file (exact versions)
uv sync
# This ensures everyone gets the same dependencies!
This doesn't guarantee reproducible installations, but it does minimise chances of version mis-matches.
# Run a Python script with dependencies
uv run script.py
# Run a module
uv run -m pytest
# Run inline script with dependencies
uv run --with requests python -c \
"
import requests as r
print(r.get('https://api.github.com').json())
"
# Execute a package (like pipx)
uvx ruff check .
Use uvx to instantly run any Python tool from PyPI:
# Run a tool you've never installed
❯ uvx pycowsay hello from uv
Installed 1 package in 3ms
-------------
< hello from uv >
-------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
uv creates a temporary venv, installs the package, and runs it!
Use uvx to instantly run any Python tool from PyPI:
# Run a tool you've never installed
uvx ruff check .
# Run a specific version
uvx black@23.0.0 myfile.py
# Run with arguments
uvx httpie https://api.github.com
Useful if you want to try something without contaminating one of your existing environments.
Manage dependencies in standalone scripts:
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "requests",
# "rich",
# ]
# ///
import requests
from rich import print
response = requests.get("https://api.github.com")
print(response.json())
uv run script.py # Auto-installs dependencies!
# List installed packages
uv pip list
# Show package info
uv pip show requests
# Compile requirements (like pip-compile)
uv pip compile pyproject.toml -o requirements.txt
# Upgrade packages
uv pip install --upgrade requests
# See dependency tree
uv tree
uvReal-world workflow examples
# An existing project with a pyproject.toml file
cd my_project/
uv sync
# A new project
uv init my_new_project
cd my_new_project/
uv add numpy matplotlib scipy
$ cd some_folder
$ uv add strict_versions_and_big_dependency_graph
error: No virtual environment found; run `uv venv` to create an environment,
or pass `--system` to install into a non-virtual environment
$ python
zsh: command not found: python
$ which python
python not found
I have no global python installed!
Either I'm in the wrong directory, or I haven't created an environment for this project yet.
~/research/Manage dependencies in standalone scripts:
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "requests",
# "rich",
# ]
# ///
import requests
from rich import print
response = requests.get("https://api.github.com")
print(response.json())
uv run script.py
Load uv using the module system:
module load uv python
As per the docs, this will set
UV_CACHE_DIR=$HOME/.cache/uvbecause your virtual environments should be in $HOME and not ceph,
and uv's file linking strategy only works within a filesystem.
You want:
jax, torch, etc
# 1. Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Create a new project
uv init my-app && cd my-app
# 3. Add dependencies
uv add requests pandas
# 4. Run your code
uv run main.py
# That's it! 🎉