`python/uv`¶

Common elements for Python components that use UV tooling.

Description¶

This component provides shared configuration blocks for GitLab CI/CD jobs that use UV, an extremely fast Python package and project manager. It is not intended to be used directly, but rather as a building block for other components that need UV functionality.

The component defines three reusable configuration blocks:

Image configuration: Sets up the UV Docker image
Cache configuration: Configures UV package caching for faster builds
Base configuration: Combines image and cache with retry policies

Usage¶

This component is typically included by other components internally and is not meant to be used directly in user pipelines. However, if you need to create custom jobs that use UV, you can include it:

include:
  - component: git.ligo.org/computing/gitlab/components/python/uv@<VERSION>

my_custom_job:
  extends: .uv_base
  script:
    - uv --version
    # create a virtual environment
    - uv venv
    # your custom UV commands here

No system Python installation

The default UV container image does not include a system Python installation. Before using UV commands, you must create a virtual environment with uv venv.

To support users in using the latest stable releases of python, this component sets UV_MANAGED_PYTHON=1 by default (equivalent to passing --managed-python to uv venv). This allows UV to automatically manage the Python version in the virtual environment independently of the system Python.

Inputs¶

Input	Default value	Description
`cache_dir`	`".cache/uv"`	The path to cache UV packages (relative to `CI_PROJECT_DIR`)
`image`	`ghcr.io/astral-sh/uv:debian`	The Docker image to use for UV jobs
`job_prefix`	`".uv"`	Prefix to apply to all template job names

Configuration blocks¶

This component provides the following configuration blocks that can be extended:

`.uv_image`¶

Sets the Docker image for UV jobs.

`.uv_cache`¶

Configures UV package caching with:

UV_CACHE_DIR environment variable pointing to the cache directory
GitLab cache configuration to persist UV packages between pipeline runs
Cache key based on the job name for isolation

`.uv_base`¶

Combines image and cache configuration with retry policies for robust job execution. Extends both .uv_image and .uv_cache, and includes retry configuration for runner system failures.

Components that use UV¶

The following components in this project support UV:

python/test - When uv: true is specified in inputs
python/all - When uv: true is specified in inputs

Examples¶

Custom job extending UV base¶

Custom job with UV support

include:
  - component: git.ligo.org/computing/gitlab/components/python/uv@<VERSION>

custom_uv_job:
  extends: .uv_base
  stage: test
  script:
    - uv venv
    - uv pip install -r requirements.txt
    - uv run python -m pytest

Custom cache directory¶

Custom UV cache directory

include:
  - component: git.ligo.org/computing/gitlab/components/python/uv@<VERSION>
    inputs:
      cache_dir: ".uv-cache"

my_job:
  extends: .uv_base
  script:
    - echo "UV cache is at $UV_CACHE_DIR"
    - uv --version

python/uv¶