uv ‐ python package and project manager - CoBrALab/documentation GitHub Wiki

uv

uv is a fast, Python package manager written in Rust. It can also be used to manage virtual environments with lockfiles, and it serves as a drop-in replacement for pip.
For more information, visit the official documentation: https://docs.astral.sh/uv/.

[!IMPORTANT] uv is available in the cobralab module on Trillium, separate installation is not required.

Installation on Compute Canada - Trillium

To install uv on Compute Canada, you can use the install script provided on the official website:

uv Installation Guide

Alternatively, if you prefer not to pipe scripts into your shell, you can manually download and install the tool via GitHub releases. Here’s an example for version 0.8.15:

  1. Download
curl -LO https://github.com/astral-sh/uv/releases/download/0.8.15/uv-x86_64-unknown-linux-gnu.tar.gz
  1. Extract
tar -xzvf uv-x86_64-unknown-linux-gnu.tar.gz
  1. Move files to .local/bin
mv uv-x86_64-unknown-linux-gnu/uv $HOME/.local/bin
mv uv-x86_64-unknown-linux-gnu/uvx $HOME/.local/bin
  1. Verify installation
uv --version

Running Scripts

If a script has no dependencies, it can be run with the following command:

uv run script.py

You can also provide arguments:

uv run script.py argument1

For more information, refer to the Scripts section of the uv documentation.

Virtual Environments (venv)

It is highly recommended to use virtual environments when working on Python projects. uv requires using a virtual environment by default.

  1. Create a venv

    uv venv

  2. Activate the environment

    source .venv/bin/activate

  3. Deactivate the environment

    deactivate

Installing packages from requirements.txt

Once the venv has been set up, packages can be installed from a requirements.txt file as follows:

uv pip install -r requirements.txt

Tools

uv can be used to run tools using the following command:

uv tool run ruff

Alternatively, use:

uvx ruff

Tools are installed into temporary, isolated environments when using these commands. If you'd prefer to install the tool permanently, use:

uv tool install

For more information, refer to the Tools section of the uv documentation.

Projects

uv can manage projects. Notably dependencies are listed in a pyproject.toml file.

Creating a New Project

To create a new project, run:

uv init my-project

Adding Dependencies

To add a package to your pyproject.toml file, use the following command:

uv add requests

You can also install packages from a Git repository:

# Install over HTTP(S).
uv add git+https://github.com/encode/httpx

# Install over SSH.
uv add git+ssh://[email protected]/encode/httpx

Lockfiles

To ensure reproducibility a lockfile can be used.

uv lock

This command will generate a lockfile, uv.lock. This file can be committed to version control
To install from a lockfile:

uv sync

For more details, refer to the Projects dependency section and the Projects Guide in the uv documentation.