Skip to content

uv

What is uv?

uv is a fast, all-in-one Python package and project manager (built by Astral, the makers of Ruff). It manages Python versions, virtual environments, and dependencies per-project via pyproject.toml/uv.lock, without needing activate.

Login Node Only

uv is currently installed only on the login node (/usr/local/bin/uv), not on compute nodes.

This means you cannot call uv directly inside a SLURM job script — it will fail with uv: command not found. Build your environment on the login node first, then have your job script call the environment's Python binary directly (see Running via SLURM below).

Checking uv is available

Check Installation

which uv
uv --version

Creating a Project

Each project gets its own folder with its own environment and lockfile.

Initialize a new project

mkdir my_project
cd my_project
uv init .

This creates:

  • pyproject.toml — project metadata and dependency list
  • uv.lock — exact resolved versions and hashes, for reproducibility
  • .python-version — pins which Python version this project uses
  • main.py — a starter script
  • a .git repository (uv initializes git by default unless one already exists)

Installing Python Versions

uv can download and manage its own Python versions independently of whatever Python is installed system-wide — no module load or conda needed.

Install a specific Python version

uv python install 3.12
uv python pin 3.12

uv python pin writes the version into .python-version, so any uv run or uv add in that project uses it automatically.

Verifying which Python is actually used

Compare the system default against the project's: 

python3 --version                # system default, e.g. 3.9.25
uv run python -c "import sys; print(sys.executable, sys.version)"
The second command will point into .venv/bin/python and report the version you pinned (e.g. 3.12.13), confirming it is not using the system Python at all.

Installing Libraries

Add a dependency

uv add numpy

This resolves the package, downloads it into the shared cache (~/.cache/uv) if not already cached, hardlinks it into .venv, and records it in both pyproject.toml and uv.lock.

GPU packages (e.g. PyTorch)

uv add torch
On Linux, uv resolves the CUDA-enabled build of PyTorch automatically — no separate index URL or manual CUDA wheel selection needed. Note this pulls in the full CUDA toolkit dependencies and is a large download (multiple GB).

Cache location

uv cache dir      # ~/.cache/uv
du -sh ~/.cache/uv
The cache is per-user. Avoid running uv cache clean/uv cache prune casually — it won't break existing environments (files are hardlinked, so already-installed projects keep working), but it forces the next fresh install of any package to re-download from scratch.

Running a Script

main.py

Simple script

import numpy as np

def main():
    arr = np.arange(10)
    print("Hello from uv!")
    print(arr, arr.sum())

if __name__ == "__main__":
    main()

Run it

uv run main.py
uv run checks that .venv exists and matches uv.lock (creating/updating it if not), then executes the script with that environment's Python — all in one command.

Running via SLURM

Since uv itself is not available on compute nodes, build the environment on the login node first with uv add, then have your job script skip uv run and call the environment's Python binary directly — it needs nothing but files already sitting on shared home storage.

gpu_test.py

GPU script

import torch

def main():
    print("Torch version:", torch.__version__)
    print("CUDA available:", torch.cuda.is_available())
    if torch.cuda.is_available():
        print("Device:", torch.cuda.get_device_name(0))
        a = torch.rand(3, 3, device="cuda")
        b = torch.rand(3, 3, device="cuda")
        print(a @ b)

if __name__ == "__main__":
    main()

run.sh

SLURM job script

#!/bin/bash
#SBATCH --job-name=uv-torch-test
#SBATCH --partition=gpu_short
#SBATCH --gres=gpu:1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=2
#SBATCH --time=00:10:00
#SBATCH --output=slurm-%j.out

cd "$SLURM_SUBMIT_DIR" || exit 1

.venv/bin/python gpu_test.py

Submit

sbatch run.sh

Expected Output

Torch version: 2.13.0+cu130
CUDA available: True
Device: NVIDIA H200
tensor([[0.9204, 0.3678, 0.3440],
        [1.0989, 0.2772, 0.6835],
        [0.7401, 0.2615, 0.6867]], device='cuda:0')

Full path to Python

You must call .venv/bin/python (or an absolute path to it), not just python — the job's shell has no knowledge of the project's virtual environment otherwise.

More Information

Documentation

Official uv documentation:

https://docs.astral.sh/uv/