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

NameRequiredDefaultDescription
versionNononeThe version of uv to install, e.g., `0.5.0`, `latest`, or `latest-known`. Defaults to the version in pyproject.toml or `latest`.
version-fileNononePath 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-versionNononeThe version of Python to set UV_PYTHON to. Overrides the Python version from .tool-versions.
python-archNononeThe Python architecture to set UV_PYTHON_ARCH to, e.g., x86_64 or aarch64. Overrides UV_PYTHON_ARCH.
activate-environmentNofalseUse uv venv to activate a venv ready to be used by later steps.
venv-pathNononeCustom path for the virtual environment when using activate-environment. Defaults to '.venv' in the working directory.
no-projectNofalsePass --no-project when creating the venv with activate-environment.
working-directoryNo${{ github.workspace }}The directory to execute all commands in and look for files such as pyproject.toml
checksumNononeThe checksum of the uv version to install
github-tokenNo${{ github.token }}Used when downloading uv from GitHub releases.
enable-cacheNoautoEnable 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-globNo**/*requirements*.txt **/*requirements*.in **/*constraints*.txt **/*constraints*.in **/pyproject.toml **/uv.lock **/*.py.lockGlob pattern to match files relative to the working directory to control the cache.
restore-cacheNotrueWhether to restore the cache if found.
save-cacheNoautoWhether to save the cache after the run. 'auto' disables saving for merge_group events.
cache-suffixNononeSuffix for the cache key
cache-local-pathNononeLocal path to store the cache.
prune-cacheNofalsePrune cache before saving.
cache-pythonNofalseUpload managed Python installations to the Github Actions cache.
ignore-nothing-to-cacheNofalseIgnore when nothing is found to cache.
ignore-empty-workdirNofalseIgnore when the working directory is empty.
tool-dirNononeCustom path to set UV_TOOL_DIR to.
tool-bin-dirNononeCustom path to set UV_TOOL_BIN_DIR to.
manifest-fileNononeURL to a custom manifest file in the astral-sh/versions format.
download-from-astral-mirrorNotrueDownload uv from the Astral mirror instead of directly from GitHub Releases.
add-problem-matchersNotrueAdd problem matchers.
quietNofalseSuppress info-level log output. Only warnings and errors are shown.
resolution-strategyNohighestResolution strategy to use when resolving version ranges. 'highest' uses the latest compatible version, 'lowest' uses the oldest compatible version.

Outputs

NameDescription
uv-versionThe installed uv version. Useful when using latest.
uv-pathThe path to the installed uv binary.
uvx-pathThe path to the installed uvx binary.
cache-hitA boolean value to indicate a cache entry was found
cache-keyThe cache key used for storing/restoring the cache
venvPath to the activated venv if activate-environment is true
python-versionThe Python version that was set.
python-runtime-idAn opaque identifier reported by uv for the activated venv's Python runtime. Empty when activate-environment is false.
python-cache-hitA 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 pytest

Each 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.