# setup-uv

setup-uv is a GitHub Action that installs and configures [uv](https://docs.astral.sh/uv/), the extremely fast Python package installer and resolver from Astral. It provides seamless integration with GitHub Actions workflows by downloading uv from official releases, adding it to PATH, and optionally enabling caching to speed up consecutive runs. The action supports version pinning, semver ranges, and automatic version detection from project configuration files.

The action offers comprehensive features including GitHub Actions cache integration for uv's dependency cache, checksum validation for security, problem matchers for error output, virtual environment activation, and Python version management. It automatically handles platform-specific configurations for Linux, macOS, and Windows runners, making it the recommended way to use uv in CI/CD pipelines.

## Basic Installation

Install the latest version of uv or a version specified in your project's configuration files.

```yaml
# Install latest version (or version from uv.toml/pyproject.toml if present)
- name: Install uv
  uses: astral-sh/setup-uv@v7

# Use the installed uv
- name: Install dependencies
  run: uv sync

- name: Run tests
  run: uv run pytest
```

## Specific Version Installation

Install a specific version of uv using exact version numbers, semver ranges, or PEP 440 specifiers.

```yaml
# Exact version
- name: Install specific version
  uses: astral-sh/setup-uv@v7
  with:
    version: "0.4.4"

# Semver range - installs latest matching version
- name: Install with semver range
  uses: astral-sh/setup-uv@v7
  with:
    version: ">=0.4.0"

# Pin to minor version
- name: Pin minor version
  uses: astral-sh/setup-uv@v7
  with:
    version: "0.4.x"

# PEP 440 specifier
- name: Install with PEP 440
  uses: astral-sh/setup-uv@v7
  with:
    version: ">=0.4.25,<0.5"

# Install oldest compatible version (useful for testing compatibility)
- name: Install lowest compatible version
  uses: astral-sh/setup-uv@v7
  with:
    version: ">=0.4.0"
    resolution-strategy: "lowest"
```

## Version from File

Install uv version defined in project configuration files like pyproject.toml, uv.toml, requirements.txt, or .tool-versions.

```yaml
# Read version from specific file
- name: Install from pyproject.toml
  uses: astral-sh/setup-uv@v7
  with:
    version-file: "pyproject.toml"

# Example pyproject.toml with required-version:
# [tool.uv]
# required-version = ">=0.4.0"

# Example uv.toml:
# required-version = "0.4.4"

# Example .tool-versions (asdf format):
# uv 0.4.4
```

## Python Version Configuration

Set the Python version that uv should use via the UV_PYTHON environment variable.

```yaml
# Set Python version
- name: Setup uv with Python 3.12
  uses: astral-sh/setup-uv@v7
  with:
    python-version: "3.12"

- name: Run with specified Python
  run: uv run python --version

# Free-threaded Python (3.13t)
- name: Setup with free-threaded Python
  uses: astral-sh/setup-uv@v7
  with:
    python-version: "3.13t"

# Matrix testing multiple Python versions
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13"]
    steps:
      - uses: actions/checkout@v5
      - name: Install uv with Python ${{ matrix.python-version }}
        uses: astral-sh/setup-uv@v7
        with:
          python-version: ${{ matrix.python-version }}
      - name: Run tests
        run: uv run --frozen pytest
```

## Cache Configuration

Enable and configure the GitHub Actions cache for uv's dependency cache to speed up workflow runs.

```yaml
# Basic caching (enabled by default on GitHub-hosted runners)
- name: Setup uv with caching
  id: setup-uv
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true

# Check if cache was restored
- name: Cache status
  run: |
    echo "Cache hit: ${{ steps.setup-uv.outputs.cache-hit }}"
    echo "Cache key: ${{ steps.setup-uv.outputs.cache-key }}"

# Custom cache dependency glob
- name: Setup with custom cache dependency
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
    cache-dependency-glob: |
      **/requirements*.txt
      **/pyproject.toml
      **/uv.lock

# Add cache suffix (useful when using different resolution strategies)
- name: Setup with cache suffix
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
    cache-suffix: "lowest-resolution"

# Disable cache pruning (useful for self-hosted runners)
- name: Setup without cache pruning
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
    prune-cache: false

# Cache Python installations too
- name: Setup with Python caching
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
    cache-python: true
```

## Cache Restore and Save Control

Fine-grained control over cache restoration and saving behavior.

```yaml
# Only restore cache, don't save (useful for PR workflows)
- name: Setup with restore-only cache
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
    save-cache: false

# Only save cache, don't restore (useful for cache warming)
- name: Setup with save-only cache
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
    restore-cache: false

# Custom local cache path
- name: Setup with custom cache path
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
    cache-local-path: "/path/to/cache"

# Ignore when nothing to cache
- name: Setup ignoring empty cache
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
    ignore-nothing-to-cache: true
```

## Environment Activation

Automatically activate a virtual environment for use in subsequent workflow steps.

```yaml
# Activate default .venv
- name: Setup uv with environment activation
  uses: astral-sh/setup-uv@v7
  with:
    activate-environment: true

- name: Install packages directly (venv is active)
  run: uv pip install requests pytest

- name: Run Python (uses activated venv)
  run: python -c "import requests; print(requests.__version__)"

# Custom venv path
- name: Setup with custom venv path
  uses: astral-sh/setup-uv@v7
  with:
    activate-environment: true
    venv-path: ${{ runner.temp }}/custom-venv

# Access venv output
- name: Setup and get venv path
  id: setup-uv
  uses: astral-sh/setup-uv@v7
  with:
    activate-environment: true

- name: Print venv location
  run: echo "Venv at: ${{ steps.setup-uv.outputs.venv }}"
```

## Working Directory

Configure the working directory for all uv operations and file lookups.

```yaml
# Monorepo with subproject
- name: Setup uv for subproject
  uses: astral-sh/setup-uv@v7
  with:
    working-directory: packages/my-subproject

- name: Install and test subproject
  working-directory: packages/my-subproject
  run: |
    uv sync
    uv run pytest
```

## Tool Directory Configuration

Configure custom directories for uv tools and their binaries.

```yaml
# Custom tool directories
- name: Setup uv with custom tool dirs
  uses: astral-sh/setup-uv@v7
  with:
    tool-dir: "/custom/tool/dir"
    tool-bin-dir: "/custom/tool-bin/dir"

# Install and use a tool
- name: Install ruff as a tool
  run: uv tool install ruff

- name: Use ruff
  run: ruff check .
```

## Checksum Validation

Validate the downloaded uv executable with a SHA256 checksum for security.

```yaml
# Install with checksum validation
- name: Install uv with checksum
  uses: astral-sh/setup-uv@v7
  with:
    version: "0.3.1"
    checksum: "e11b01402ab645392c7ad6044db63d37e4fd1e745e015306993b07695ea5f9f8"

# Note: Checksums for recent versions are automatically validated
# Find checksums at: https://github.com/astral-sh/uv/releases
```

## Custom Manifest File

Use a custom manifest file for uv versions and download URLs (useful for self-hosted builds).

```yaml
# Use custom manifest
- name: Setup uv with custom manifest
  uses: astral-sh/setup-uv@v7
  with:
    manifest-file: "https://example.com/my-custom-manifest.json"

# Example manifest.json format:
# [
#   {
#     "version": "0.7.13",
#     "artifactName": "uv-aarch64-apple-darwin.tar.gz",
#     "arch": "aarch64",
#     "platform": "apple-darwin",
#     "downloadUrl": "https://example.com/uv-aarch64-apple-darwin.tar.gz"
#   }
# ]
```

## GitHub Token Configuration

Configure the GitHub token for API rate limiting and authentication.

```yaml
# Use default token (automatic)
- name: Setup uv
  uses: astral-sh/setup-uv@v7

# Custom token with elevated permissions
- name: Setup uv with custom token
  uses: astral-sh/setup-uv@v7
  with:
    github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
```

## Problem Matchers

Control automatic problem matcher registration for Python error highlighting.

```yaml
# Default: problem matchers enabled
- name: Setup uv
  uses: astral-sh/setup-uv@v7

# Disable problem matchers
- name: Setup uv without problem matchers
  uses: astral-sh/setup-uv@v7
  with:
    add-problem-matchers: false
```

## Action Outputs

Access information about the installed uv version and configuration via action outputs.

```yaml
- name: Setup uv
  id: setup-uv
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
    activate-environment: true
    python-version: "3.12"

- name: Display all outputs
  run: |
    echo "uv version: ${{ steps.setup-uv.outputs.uv-version }}"
    echo "uv path: ${{ steps.setup-uv.outputs.uv-path }}"
    echo "uvx path: ${{ steps.setup-uv.outputs.uvx-path }}"
    echo "Cache hit: ${{ steps.setup-uv.outputs.cache-hit }}"
    echo "Cache key: ${{ steps.setup-uv.outputs.cache-key }}"
    echo "Venv path: ${{ steps.setup-uv.outputs.venv }}"
    echo "Python version: ${{ steps.setup-uv.outputs.python-version }}"
    echo "Python cache hit: ${{ steps.setup-uv.outputs.python-cache-hit }}"
```

## Complete CI/CD Workflow Example

A comprehensive example showing a complete testing workflow with setup-uv.

```yaml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.10", "3.11", "3.12"]

    steps:
      - uses: actions/checkout@v5

      - name: Setup uv
        uses: astral-sh/setup-uv@v7
        with:
          python-version: ${{ matrix.python-version }}
          enable-cache: true
          cache-suffix: ${{ matrix.python-version }}

      - name: Install dependencies
        run: uv sync --all-extras

      - name: Run linting
        run: uv run ruff check .

      - name: Run type checking
        run: uv run mypy .

      - name: Run tests
        run: uv run pytest --cov=src --cov-report=xml

      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage.xml

  build:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v5

      - name: Setup uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      - name: Build package
        run: uv build

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
```

## Summary

setup-uv is the official GitHub Action for integrating uv into CI/CD workflows. It provides a robust solution for Python project automation by handling uv installation, version management, caching, and environment configuration. The action supports all major platforms (Linux, macOS, Windows) and offers fine-grained control over caching behavior, making it suitable for both GitHub-hosted and self-hosted runners. Key features include automatic version detection from project files, semver/PEP 440 version constraints, checksum validation, and problem matchers for enhanced error reporting.

Common integration patterns include: basic workflows with `uv sync` and `uv run` for dependency management and test execution; matrix builds testing across multiple Python versions; monorepo setups using the `working-directory` input; and optimized caching configurations for faster CI runs. For most projects, simply adding `uses: astral-sh/setup-uv@v7` with `enable-cache: true` provides an excellent out-of-the-box experience. Advanced users can leverage custom manifests for private uv builds, configure tool directories for persistent tool installations, and fine-tune cache behavior for specific use cases.