Getting Started with uv¶

Why Use uv on the Cluster?¶

The system Python on Discovery is shared and locked down — you can't pip install into it. To install your own packages you need an isolated environment: a private copy of Python plus any libraries your project requires, walled off from the rest of the system.

You also need reproducibility. Research code that "works on my laptop" but breaks on the cluster (or breaks six months later when a dependency updates) is research code you can't trust. A reproducible environment rebuilds exactly the same way every time, on any machine.

uv handles both problems in a single tool. It manages Python versions, creates virtual environments, resolves and installs packages, and locks every version so the result is reproducible. No need to juggle separate module load python, python -m venv, pip install, and pip freeze commands.

How uv Manages Your Project¶

When you start a project with uv, it creates three things. Understanding what each one does will save you confusion later:

pyproject.toml is the file you edit. It lists your dependencies (like numpy >= 1.24) and the Python version your project needs. It's the single source of truth for what your project requires.

uv.lock is generated automatically. It records the exact version of every package that was resolved. That includes not just your direct dependencies, but their dependencies too (so-called transitive dependencies), all the way down. This is what guarantees reproducibility: Anyone who runs uv sync gets precisely the same environment.

.venv/ is the virtual environment directory containing the installed packages. It's disposable. If it gets corrupted or you delete it, uv sync rebuilds it from the lockfile. Don't check it into version control.

Step by Step¶

1. Load uv¶

module load uv

This is required on both login nodes and in batch jobs.

2. Create a New Project¶

uv init myproject  # (1)!
cd myproject

1. This creates pyproject.toml and .python-version. uv automatically downloads and manages the Python version specified in .python-version.

3. Add Packages¶

uv add numpy pandas matplotlib  # (1)!

1. This resolves compatible versions, installs them into .venv/, and writes the lockfile uv.lock that makes your environment reproducible.

4. Run Your Code¶

The simplest way is uv run, which activates the project environment automatically:

uv run python myscript.py

You don't need to remember to activate or deactivate anything. uv run reads pyproject.toml and handles it for you.

If you prefer a traditional workflow (useful in interactive sessions or when other tools expect a standard venv), you can still treat a .venv managed by uv like any other virtual environment:

source .venv/bin/activate
python myscript.py

5. Use a Specific Python Version¶

uv python install 3.11  # (1)!
uv init --python 3.11 myproject

1. uv downloads and manages Python versions for you. You can have multiple versions installed side by side and each project uses whichever version its .python-version file specifies.

6. Use in a Batch Job¶

#!/bin/bash
#SBATCH --job-name=uv_python
#SBATCH --partition=standard
#SBATCH --time=01:00:00
#SBATCH --cpus-per-task=1
#SBATCH --mem=8G
#SBATCH --output=%x_%j.out
#SBATCH --error=%x_%j.err

# Load required modules
module load uv

# Run your work
cd /path/to/myproject
uv run python myscript.py

uv run handles all environment setup. No source .venv/bin/activate needed in the script.

Working with an Existing requirements.txt¶

If you have a project that already uses a requirements.txt file, uv can work with it directly. Create a virtual environment and install from the file:

uv venv  # (1)!
source .venv/bin/activate
uv pip install -r requirements.txt

1. Without arguments, uv venv creates a .venv/ in the current directory using the default Python version.

To keep the environment in sync as the file changes:

uv pip sync requirements.txt  # (1)!

1. uv pip sync ensures the environment matches the file exactly. It installs missing packages and removes packages that are no longer listed.

Shared Environments for Labs¶

If your lab has a shared project directory, you can create a uv project there. Anyone with access to the directory can run uv sync to get an identical environment:

cd /path/to/shared/labproject
uv sync  # (1)!
uv run python analysis.py

1. uv sync reads pyproject.toml and uv.lock, then creates or updates .venv/ so everyone gets exactly the same package versions.

Keeping Storage Tidy¶

uv caches downloaded packages and Python builds so that repeated installs are fast. By default this cache lives in ~/.cache/uv — inside your home directory, which has a storage quota on Discovery.

The cache is purely a speed optimization. It's safe to delete at any time because uv will simply re-download what it needs on the next install. That makes it a good candidate for scratch storage, which is fast and has generous space limits but is not permanent.

export UV_CACHE_DIR=/dartfs-hpc/scratch/$USER/.uv-cache

To reclaim space at any time, prune entries that are no longer needed by any project:

uv cache prune

The .venv/ directory also counts against quota if your project lives in your home directory. For large environments (especially ML packages), consider placing the project itself on scratch or shared storage. Just remember that scratch is not backed up! Always keep pyproject.toml and uv.lock in version control so you can recreate the environment anywhere.

Common Pitfalls¶

Quick Start¶

Here the essence of everything above, distilled into a copy-paste recipe for starting a new project:

# Load uv
module load uv

# Move the cache off your home directory (only needed once — add to ~/.bashrc)
export UV_CACHE_DIR=/dartfs-hpc/scratch/$USER/.uv-cache

# Create a project and add packages
uv init myproject
cd myproject
uv add numpy pandas matplotlib

# Verify it works
uv run python -c "import numpy; print(numpy.__version__)"