astral-sh/setup-uv@v10.3.3
Set up your GitHub Actions workflow with a specific version of uv.
At a glance
- Latest major
v10.3.3- Repository
- astral-sh/setup-uv
- Inputs
- 27 (0 required)
- Outputs
- 9
- Runs using
node24- License
- MIT
- Last checked
Inputs and outputs come straight from the action's official action.yml. See our editorial standards.
Usage
- uses: astral-sh/[email protected]Inputs
| Name | Required | Default | Description |
|---|---|---|---|
version | No | none | The version of uv to install, e.g., `0.5.0`, `latest`, or `latest-known`. Defaults to the version in pyproject.toml or `latest`. |
version-file | No | none | Path to a file containing the version of uv to install, e.g., uv.toml, pyproject.toml, .tool-versions, requirements.txt or uv.lock. A selected .tool-versions file can also provide the Python version. Defaults to searching for uv.toml and if not found pyproject.toml. |
python-version | No | none | The version of Python to set UV_PYTHON to. Overrides the Python version from .tool-versions. |
python-arch | No | none | The Python architecture to set UV_PYTHON_ARCH to, e.g., x86_64 or aarch64. Overrides UV_PYTHON_ARCH. |
activate-environment | No | false | Use uv venv to activate a venv ready to be used by later steps. |
venv-path | No | none | Custom path for the virtual environment when using activate-environment. Defaults to '.venv' in the working directory. |
no-project | No | false | Pass --no-project when creating the venv with activate-environment. |
working-directory | No | ${{ github.workspace }} | The directory to execute all commands in and look for files such as pyproject.toml |
checksum | No | none | The checksum of the uv version to install |
github-token | No | ${{ github.token }} | Used when downloading uv from GitHub releases. |
enable-cache | No | auto | Enable the GitHub Actions cache for uv. 'auto' enables caching on GitHub-hosted runners except for release, tag push, pull_request_target, and workflow_run events. |
cache-dependency-glob | No | **/*requirements*.txt
**/*requirements*.in
**/*constraints*.txt
**/*constraints*.in
**/pyproject.toml
**/uv.lock
**/*.py.lock | Glob pattern to match files relative to the working directory to control the cache. |
restore-cache | No | true | Whether to restore the cache if found. |
save-cache | No | auto | Whether to save the cache after the run. 'auto' disables saving for merge_group events. |
cache-suffix | No | none | Suffix for the cache key |
cache-local-path | No | none | Local path to store the cache. |
prune-cache | No | false | Prune cache before saving. |
cache-python | No | false | Upload managed Python installations to the Github Actions cache. |
ignore-nothing-to-cache | No | false | Ignore when nothing is found to cache. |
ignore-empty-workdir | No | false | Ignore when the working directory is empty. |
tool-dir | No | none | Custom path to set UV_TOOL_DIR to. |
tool-bin-dir | No | none | Custom path to set UV_TOOL_BIN_DIR to. |
manifest-file | No | none | URL to a custom manifest file in the astral-sh/versions format. |
download-from-astral-mirror | No | true | Download uv from the Astral mirror instead of directly from GitHub Releases. |
add-problem-matchers | No | true | Add problem matchers. |
quiet | No | false | Suppress info-level log output. Only warnings and errors are shown. |
resolution-strategy | No | highest | Resolution strategy to use when resolving version ranges. 'highest' uses the latest compatible version, 'lowest' uses the oldest compatible version. |
Outputs
| Name | Description |
|---|---|
uv-version | The installed uv version. Useful when using latest. |
uv-path | The path to the installed uv binary. |
uvx-path | The path to the installed uvx binary. |
cache-hit | A boolean value to indicate a cache entry was found |
cache-key | The cache key used for storing/restoring the cache |
venv | Path to the activated venv if activate-environment is true |
python-version | The Python version that was set. |
python-runtime-id | An opaque identifier reported by uv for the activated venv's Python runtime. Empty when activate-environment is false. |
python-cache-hit | A boolean value to indicate the Python cache entry was found |
Read an output with ${{ steps.<step-id>.outputs.<name> }}; the step needs an id.
Examples
Install uv with caching
Fast Python dependency manager; the cache is keyed on uv.lock.
name: Example
on:
push:
branches: [main]
permissions:
contents: read
jobs:
example:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: astral-sh/setup-uv
uses: astral-sh/[email protected]
with:
enable-cache: true
- run: uv sync --locked
- run: uv run pytestEach example passed actionlint (syntax, expressions and the inputs it knows for this action). They were not run in a live repository, so replace placeholder values such as names, ARNs and paths with your own.
Something out of date or wrong? Report it on our Contact page. This page is rebuilt from the action's repository roughly once a week.