Skip to content

setup-uv: uv for GitHub Actions

uv

setup-uv is Astral’s GitHub Action for installing uv and adding its executables to the runner’s PATH. It also manages uv’s download cache. Installing the action does not install project dependencies or run tests; subsequent workflow steps do that work.

Version selection

The action release and the installed uv version are separate pins. uses: astral-sh/setup-uv@... selects the action; the version input selects uv.

Without an explicit version, setup-uv looks for required-version in uv.toml or [tool.uv] in pyproject.toml, then falls back to the latest uv release. version-file selects another supported file. A version range resolves using resolution-strategy, whose default is highest.

GitHub recommends pinning third-party actions to a full commit SHA. The setup-uv upgrade guide covers resolving releases and maintaining pins. A full release tag identifies a release; a full commit SHA also protects against a tag being moved.

Common inputs

Input Meaning and default
version uv version or range; omitted means project required-version, then latest
version-file File supplying the uv version; automatic discovery checks uv.toml before pyproject.toml
python-version Sets UV_PYTHON for later uv commands; no default override
working-directory Directory for action commands and configuration discovery; defaults to the checkout workspace
activate-environment Creates and activates a virtual environment for later steps; defaults to false
enable-cache auto, true, or false; defaults to auto
cache-dependency-glob Files whose hashes contribute to the cache key; defaults cover requirements/constraints files, pyproject.toml, uv.lock, and script lockfiles

working-directory configures the action, not subsequent run: steps. A monorepo workflow must also set those steps’ working directory.

Python selection

python-version sets an environment request for uv; it does not change the project’s requires-python metadata. Later uv commands must still satisfy that requirement. Without an override, uv uses the project’s normal interpreter selection, including .python-version.

For a test matrix, passing ${{ matrix.python-version }} selects each job’s interpreter. Creating a virtual environment through activate-environment: true is optional when commands already use uv run.

Cache behavior

The default enable-cache: auto enables caching on GitHub-hosted runners except for release events, tag pushes, pull_request_target, and workflow_run. Explicit true also enables caching on self-hosted runners and overrides those event exclusions. Privileged jobs need a reviewed cache trust boundary, not an unconditional cache toggle.

A cache hit reuses downloads and built artifacts; it does not replace the lockfile or guarantee that the project environment is installed. The setup-uv step restores caches; its post step saves them after a successful job. save-cache: auto excludes merge_group events.

Additional controls include:

  • restore-cache and save-cache: control reads and writes independently.
  • cache-suffix: adds a manual cache-key discriminator.
  • prune-cache: prunes before saving; defaults to false.
  • cache-python: caches managed Python installations; defaults to false.

Use the dependency-cache guide for project workflows or the uvx cache guide for standalone tools.

Outputs

A step with an id exposes uv-version, uv-path, and uvx-path. Cache-related outputs include cache-hit and cache-key; venv identifies an activated environment when requested. These report setup state, not whether application tests passed.

Strengths and limits

  • Combines uv installation, version selection, and cache handling in one action.
  • Supports GitHub-hosted Linux, macOS, and Windows workflows.
  • Keeps project dependency installation explicit rather than hiding it in setup.
  • Requires a compatible GitHub Actions runner; local shell testing cannot verify cache save/restore behavior on the service.

For an executable project workflow, use setting up GitHub Actions with uv.

Last updated on