uv on RCAC Clusters: Why We Built uv-manager¶
module load uv now works on Anvil, Gautschi, Gilbreth, Negishi and Scholar. After loading it, you
run uv and uvx exactly as Astral's documentation describes. This
post explains why RCAC provides uv through a small wrapper called uv-manager, what that wrapper
does, and what to keep in mind when you use it on a cluster.
Why a module for uv?¶
Last year Anaconda, Inc. changed the terms under which its distribution and its defaults channel
may be used, and RCAC made the conda module (Miniforge, with the open conda-forge channel) the
recommended way to build Python environments. Our earlier post,
Conda vs Anaconda, covers that change.
Many Python users need nothing from conda-forge, though. Their dependencies are packages on PyPI, and uv installs those quickly, resolves them into a lock file, and manages Python versions as well. Plenty of you already run uv's standalone installer on our clusters, and on a cluster that installer causes four problems:
- Home quota. The installer puts uv in
~/.local/bin, its cache in~/.cache/uv, and its tool environments and Python interpreters under~/.local/share/uv. A working setup easily reaches tens of gigabytes, far more than a home directory holds. - CPU architecture. A binary downloaded on a login node is built for that node's architecture.
Where the compute nodes a job lands on differ (now or in a future partition), the same files fail
with an
Exec format errordeep inside the job. - Shared state. The obvious fix, one site-wide uv install, means one user's
uv tool installoruv python installchanges what every other user gets. Each user needs their own. - Purges. Moving uv's files to scratch solves the quota, but scratch is purged file by file.
When some files of a tool environment or of a uv-managed Python are purged and others survive,
uv does not notice. It runs them anyway, and you get an
ImportErrorthat says nothing about the purge.
What uv-manager is¶
uv-manager is a single, open-source shell script
installed under the names uv, uvx and uv-manager. When you run uv, it:
- finds your state root,
$UVM_ROOT(the module sets it to$SCRATCH/.uv); - on the first call on a given CPU architecture, downloads the real uv into
$UVM_ROOT/<architecture>, which is yours alone; - points uv's cache, tool and Python directories at that same per-architecture tree, on the node that is actually running the command;
- runs the real uv with your arguments.
Apart from a small record of each tool you install, nothing it stores goes in your home directory,
a login node and a compute node of different architectures never share binaries, and no two users
share anything. uv-manager status shows every path it is using, and uv-manager install fetches
a newer uv when you want one.
Using it¶
Each cluster's user guide has a page with the details: projects and virtual environments, choosing
a Python version, batch jobs, and when to use conda instead.
The software catalog entry lists the versions on each cluster.
What to keep in mind¶
- Repair runs in your batch jobs. The module sets
UVM_REPAIR=1. In a Slurm job, the firstuvoruvxcall checks for purged files and repairs them before your command runs, once per job. In a multi-node job one task repairs while the others wait. ExportUVM_REPAIR=0to turn it off. Outside a job,uv-manager doctorreports what it finds. - Pick a Python when the newest is too new. The module has uv use only the Python interpreters
it installs itself (an old operating-system Python can quietly pull in ancient package
releases), and by default that is the newest release. When a package has no build for it yet,
pin one:
uv python pin 3.12, or--python 3.12on a single command. To use thecondamodule's Python, pass--python "$(command -v python3)". - Anvil purges scratch after 30 days. To keep your uv state longer, set
UVM_ROOT=$PROJECT/$USER/.uvbefore loading the module (a directory of your own, never the shared top of$PROJECT). - Keep long-lived environments off scratch. A project's
.venvbelongs in your home directory if it is small, or in your group's Data Depot space if it is large. - Watch your file count. Scratch limits the number of files as well as space, and a busy uv
cache holds many.
myquotashows where you stand, anduv cache pruneclears what you no longer use. - conda is still the right tool for some work. Compiled stacks from conda-forge, R, GDAL,
conda-env-modmodules and Jupyter kernels stay with thecondamodule. Both modules load side by side.
If uv-manager itself misbehaves, please open an issue on GitHub; for anything about your jobs, the RCAC support team can help.
Update: uv-manager 0.8.0 (November 3, 2026)¶
The uv module now loads
uv-manager 0.8.0 by default on
Anvil, Gautschi, Gilbreth, Negishi and Scholar, and uv/0.7.0 is still available.
With UVM_REPAIR set, as the module does, repair in a batch job now covers two more cases: a tool
installed with uv tool install and run by its own name (srun ruff check .), and the environments
uv run script.py and uvx run from uv's cache. To restore installed tools, uv-manager keeps a
record of each one, a few KB apiece, under ~/.local/share/uvm, off scratch. If you installed
tools under 0.7.0, run uv-manager doctor once to record them. Each cluster's uv page has the
details, including what to do if you switch back to 0.7.0.