setup-uv: uv for GitHub Actions
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-cacheandsave-cache: control reads and writes independently.cache-suffix: adds a manual cache-key discriminator.prune-cache: prunes before saving; defaults tofalse.cache-python: caches managed Python installations; defaults tofalse.
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.