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¶

Option 1: requirements.txt¶

Freeze your current dependencies into a requirements.txt file

uv pip freeze > requirements.txt

Option 2: requirements.lock¶

Another possibility is to use the native uv syntax to create a cross-platform lock file

uv pip compile pyproject.toml -o requirements.lock

Then later, reinstall from the lock file with

uv pip sync requirements.lock

Option 3: pyproject.toml¶

Alternatively, if you're using uv's project management (which requires a pyproject.toml file), you can use:

uv lock

to generate a uv.lock file, and then

uv sync

to recreate the environment.

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 --python python3.13 cpu-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 by running deactivate and then exit.

After exiting the interactive session, save the following Python code to a file called 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 --job-name=gpu-job
#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