CI/CD pipelines

GitLab CI/CD

For GitLab CI/CD pipelines there are various Docker images with pre-installed uv: Available images.

.gitlab-ci.yml
 1variables:
 2 UV_VERSION: 0.11
 3 PYTHON_VERSION: 3.14
 4 BASE_LAYER: trixie-slim
 5 # GitLab CI creates a separate mountpoint for the build directory,
 6 # so we need to copy instead of using hard links.
 7 UV_LINK_MODE: copy
 8
 9
10stages:
11  - build
12
13uv-install:
14  stage: build
15  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
16  variables:
17    UV_CACHE_DIR: .uv-cache
18  cache:
19    - key:
20        files:
21          - uv.lock
22      paths:
23        - $UV_CACHE_DIR
24  script:
25    # YOUR UV COMMANDS
26    - uv cache prune --ci
Line 25

This reduces the cache size, see also Caching in continuous integration.

See also

GitHub Actions

The official astral-sh/setup-uv GitHub action installs uv, adds it to PATH and provides a cache for the installed packages:

ci.yml
name: ci

jobs:
  test:
    name: python
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      with:
        persist-credentials: false

    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      with:
        persist-credentials: false

You can then install either a single Python version or a matrix with uv:

ci.yml
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version-file: "pyproject.toml"

or

ci.yml
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
  with:
    python-version-file: .python-version

or

ci.yml
strategy:
  matrix:
    python-version:

      - "3.10"
      - "3.11"
      - "3.12"
      - "3.13"
      - "3.14"

steps:
  - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
  - name: Install uv and set the Python version
    uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
    with:
      python-version: ${{ matrix.python-version }}

See also

uv sync and uv run

Once uv and Python are installed, the project can be installed with uv sync and commands can be executed in the environment with uv run, for example for pytest:

ci.yml
- name: Install the project
  run: uv sync --group tests

- name: Run tests
  run: uv run pytest

Caching

The uv cache improves runtimes:

ci.yml
- name: Enable caching
  uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
  with:
    enable-cache: true

Invalidates the cache if uv.lock changes:

ci.yml
- name: Define a cache dependency glob
  uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

  with:
    enable-cache: true
    cache-dependency-glob: "uv.lock"