Skip to content

Using uv for Python Environment Management on HiPerGator

uv is a modern package management tool that provides a faster, more user-friendly alternative to conda and pip for managing Python project environments. While uv works out of the box, please configure your cache location to avoid storage issues on HiPerGator.

Note that uv is only for Python. pixi is a similar tool which supports multiple languages.

Advantages:

  • Project-local environments: All environment files are stored in your project directory (.venv/), not in your home directory. (uv does use a global cache, which you should configure.)

  • Easy Notebook Integration: Use uv add package in notebook cells to safely install packages directly into your environment

  • Reproducible environments: Uses uv.toml for declarative environment specification

  • Native Python venv support: Leverages Python's built-in venv module for environment management

  • Faster installations: uv uses a more efficient solver and caching system

Usage

uv is available in the conda module. To use uv, first load the conda module. 

ml conda

Cache Configuration

HiPerGator home directories have limited storage (40GB), so configure uv to use your /blue storage for caching.

Why does uv need a cache? While uv keeps environment-specific files in your project directory (.venv/), it uses a global cache for downloaded packages, metadata, and solve results. This cache can be shared across projects, making subsequent installations much faster and reducing storage usage overall.

We recommend using a symlink to your allocation directory since this will also take care of other applications that use the ~/.cache directory.

Move your cache to your allocation and create a symlink:

# Assume your group storage is /blue/dr-florida and your username is allie.gator

# Move your existing cache if it's there
mv ~/.cache/ /blue/dr-florida/allie.gator/.cache

# Create a symlink
ln -s /blue/dr-florida/allie.gator/.cache ~/.cache

Info

The uv cache directory can alternatively be set via the UV_CACHE_DIR environment variable, but we recommend symlinking the default location instead.

Basic Usage

Initialize a Project

Create a new project directory and initialize uv:

mkdir my-project
cd my-project
uv init

This creates a pyproject.toml file and .venv/ directory for your project.

Add Dependencies

Add packages to your project:

# Add regular dependencies
uv add numpy pandas matplotlib

# Add development dependencies
uv add --dev pytest black flake8

# Add packages with version constraints
uv add "requests>=2.25.0" "fastapi<1.0.0"

Install Dependencies

Install all dependencies from pyproject.toml:

uv sync

Reproduce Environments

To recreate an environment in a new location, copy the pyproject.toml file and run:

uv sync

Run Commands

Execute commands in your uv environment:

# Run Python scripts
uv run python my_script.py

# Run arbitrary commands
uv run jupyter notebook
uv run pytest

Notebook Integration

Quick Setup

  1. Install ipykernel: 

    uv add --dev ipykernel

  2. Create kernel (for JupyterLab): 

    uv run ipython kernel install --user --name "my-project" --display-name "my-kernel-name"

  3. Use in notebooks:

  4. VS Code: Select the kernel from .venv/bin/python
  5. JupyterLab: Select your project kernel

Adding Packages in Notebooks

Install packages directly from notebook cells:

# This updates pyproject.toml and installs the package
!uv add seaborn

PyTorch

If you wish to install PyTorch with CUDA support for NVIDIA GPUs you will need to specify a package index for uv add. The default package index, PyPI, does not include CUDA enabled PyTorch builds. Specify an alternative package index with the --index option:

uv add torch torchvision --index https://download.pytorch.org/whl/cu129

See the PyTorch guide for more details.

Using uv in HPG Scripts

Command Line Usage

You can use uv commands directly in your terminal or scripts. For example, to run a Python script within your uv environment:

uv run my_script.py

Job Scripts

Use uv in SLURM job scripts:

#!/bin/bash
#SBATCH --job-name=uv-job
#SBATCH --output=job-%j.log
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --mem=16gb
#SBATCH --time=24:00:00

module load conda
cd /path/to/your/project
uv run python train_model.py

Getting Help