Python environments with `uv`¶

Overview¶

uv is a Python package installer and resolver that is a drop-in replacement for pip. This page provides step-by-step instructions for using uv on a Linux system without requiring sudo privileges. For more detailed documentation, see here.

This page also includes a section on running uv with SLURM for job scheduling on clusters, both CPU-only and GPU jobs. The instructions below assume you are installing uv as a standalone tool in your user space.

Installing for your user¶

On Linux or MacOS, install uv in your user environment with the following command:

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

For other installation methods, for example on Windows or when using Homebrew on MacOS, see here.

After installation, restart your shell to update your PATH:

exec $SHELL

You can check that uv is available by running

uv --help

Updating¶

If you already have uv installed and would like to update to a newer version

uv self update

Using virtual environments¶

uv supports efficient project management through virtual environments and dependency locking. Full documentation is here

Creating a new environment¶

Initialize a new isolated Python virtual environment. You can specify any name for your virtual environment directory. By default, it's .venv/.

uv venv
source .venv/bin/activate

To specify a Python version

uv venv --python 3.13
source .venv/bin/activate

To specify a non-default name

uv venv my-venv
source my-venv/bin/activate

Installing dependency packages¶

After running source .venv/bin/activate, install individual packages from PyPi

uv pip install pandas

To install from a requirements.txt file

uv pip install -r requirements.txt

Exporting an environment¶

Freeze your current dependencies into a requirements.txt file

uv pip freeze > requirements.txt

Deactivating an environment¶

deactivate

Installing Python¶

Optionally, you may use uv to install a specific Python version directly into your user space, without creating a virtual environment. This can be useful if you frequently use multiple Python versions.

uv python install 3.13

Verify your installation

uv python find --system

And run Python, either from the shell

uv run --python python3.13 -- python

Or by running a script

uv run --python python3.13 my-code.py

Running jobs with Slurm¶

To run Python scripts using uv on a Slurm cluster, you can start with the following CPU-only or GPU examples of sbatch scripts.

Example CPU job¶

In this example, there are no Python dependency packages. If there were, you can follow steps above to create a virtual environment and then add source my-venv/bin/activate to the sbatch script before the uv run command.

Here's a sample python code, which you can save as cpu-code.py

#!/usr/bin/env python3

"""
Example CPU-bound script.
This script simulates a CPU-intensive task by calculating
large Fibonacci numbers.
"""

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

if __name__ == "__main__":
    result = fibonacci(30)
    print(f"Result: {result}")

Save this submission script as cpu-job.sh

#!/bin/bash -l
#SBATCH --job-name=cpu-job
#SBATCH --cpus-per-task=8
#SBATCH --mem=8G
#SBATCH --time=00:10:00
#SBATCH --output=cpu-%j.log

###source my-venv/bin/activate
###uv run my-code.py
uv run --python python3.13 my-code.py

Submit the job

sbatch cpu-job.sh

To see the output file

cat cpu-*.log

Example GPU job¶

First, set up a pytorch environment on a GPU-compute node.

On the ScienceCluster, you can request an interactive GPU-compute node:

# interactive session to work on a GPU-compute node
srun --pty -n 1 -c 4 --time=00:10:00 --mem=16GB --gpus=1 bash -l

# create a virtual environment
uv venv venv-torch-gpu
source venv-torch-gpu/bin/activate

# install required Python packages
uv pip install torch numpy

After installation, leave the interactive GPU session by first deactivating the environment and then exiting the shell:

Next, save the following Python code to gpu-code.py

#!/usr/bin/env python3

"""
This script checks for GPU availability, then runs a small
tensor operation with PyTorch on the GPU (if available).
"""

import torch

if __name__ == "__main__":
    device = "cuda" if torch.cuda.is_available() else "cpu"
    print(f"Running on device: {device}")

    size = 1000
    a = torch.rand((size, size), device=device)
    b = torch.rand((size, size), device=device)
    c = a @ b  # matrix multiplication

    print("Matrix multiplication successful.")

Specify GPU resources explicitly in your sbatch script

#!/bin/bash -l
#SBATCH --cpus-per-task=2
#SBATCH --mem=8G
#SBATCH --gres=gpu:1
#SBATCH --time=00:10:00
#SBATCH --output=gpu-%j.log

source venv-torch-gpu/bin/activate
uv run gpu-code.py

Submit the GPU job

sbatch gpu-job.sh