# setup-uv: uv for GitHub Actions


[setup-uv](https://github.com/astral-sh/setup-uv) is Astral's GitHub Action for installing [uv](https://pydevtools.com/handbook/reference/uv.md) 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](https://docs.github.com/en/actions/reference/security/secure-use#using-third-party-actions). The [setup-uv upgrade guide](https://pydevtools.com/handbook/how-to/how-to-upgrade-setup-uv-in-github-actions.md) 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](https://pydevtools.com/handbook/how-to/how-to-change-the-python-version-of-a-uv-project.md), 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](https://pydevtools.com/handbook/how-to/how-to-cache-uv-dependencies-in-ci.md) for project workflows or the [uvx cache guide](https://pydevtools.com/handbook/how-to/how-to-cache-uvx-tools-in-github-actions.md) 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](https://pydevtools.com/handbook/tutorial/setting-up-github-actions-with-uv.md).
