Python with uv

Modified

2026-05-14

uv is a fast Python package and project manager written in Rust. It replaces pip, conda, venv, and pipx with a single tool and manages its own Python installations — no dependency on system Python.

Admin: Installation

uv is already installed system-wide. For reference, installation is a one-liner:

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

This installs to ~/.local/bin. Ensure it’s on your PATH.

Managing Python Versions

uv downloads and manages Python installations independently of the system Python.

# Install a specific version
uv python install 3.12
uv python install 3.11

# List installed and available versions
uv python list

Project Workflow (Recommended)

For any work beyond a quick one-off, use uv’s project management. This creates a pyproject.toml and lockfile so your environment is reproducible.

# Start a new project
uv init my-analysis
cd my-analysis

# Add dependencies
uv add pandas scikit-learn matplotlib

# Add dev dependencies
uv add --dev pytest ruff

# Run scripts in the project environment
uv run python train_model.py

# Run installed tools
uv run jupyter lab

# Sync environment after pulling changes
uv sync

The project’s .venv is created automatically. You don’t need to activate it — uv run handles it. If you do want to activate (e.g. for IDE integration):

source .venv/bin/activate

Quick / Ad-hoc Usage

For one-off work where a full project is overkill:

# Create a venv with a specific Python version
uv venv --python 3.12

# Install packages into it
uv pip install numpy pandas

# Or install from a requirements file
uv pip install -r requirements.txt

Standalone Scripts (PEP 723)

Scripts can declare their own dependencies inline. uv run creates an isolated environment automatically — useful for self-contained analysis scripts or utility scripts in this repo (see nvidia/).

Create analyze.py:

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "pandas>=2.0",
#     "matplotlib",
#     "seaborn",
# ]
# ///

import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns

df = pd.read_csv("data.csv")
sns.barplot(data=df, x="category", y="value")
plt.savefig("plot.png")

Run it:

uv run analyze.py

No venv setup, no requirements file — dependencies are resolved and cached on first run.

PyTorch / TensorFlow with CUDA

See GPU setup for full GPU setup details. The key commands:

# PyTorch with CUDA 12.1 (check driver compat in nvidia-cuda-ml.qmd)
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# TensorFlow with bundled CUDA runtime
uv pip install "tensorflow[and-cuda]"

In a project, use uv add with the --index-url override or configure the index in pyproject.toml:

# pyproject.toml
[tool.uv]
index-url = "https://download.pytorch.org/whl/cu121"
extra-index-url = ["https://pypi.org/simple"]

Installing CLI Tools

uv tool installs Python CLI applications into isolated environments, similar to pipx:

uv tool install jupyter
uv tool install ruff
uv tool install black

# List installed tools
uv tool list

Installed tools are available directly on the command line.

Coming from conda

conda	uv equivalent
`conda create -n myenv python=3.11`	`uv venv --python 3.11` or `uv init --python 3.11`
`conda activate myenv`	`source .venv/bin/activate` or just use `uv run`
`conda install numpy pandas`	`uv add numpy pandas` (project) or `uv pip install numpy pandas` (ad-hoc)
`conda env export`	`uv pip freeze` or `uv lock` (project)

The main difference: conda manages non-Python dependencies (C libraries, R, etc.) while uv is Python-only. For GPU libraries, this doesn’t matter — PyTorch and TensorFlow bundle their own CUDA runtime.