astral-sh/setup-uv: no @v10 tag, one cache key, and Python selection

By Kaveh Alemi·Latchkey

astral-sh/setup-uv installs uv, puts it on PATH and, on GitHub-hosted runners, saves the uv cache under a key built from the platform, the Python version and a hash of your dependency files. Since v8 it publishes no major tags, so astral-sh/setup-uv@v10 does not resolve: pin a full version or a commit SHA.

Most setup-uv questions are one of three: why @v8, @v9 or @v10 fails to resolve, why the cache never restores on a branch or on a self-hosted runner, and whether you still need actions/setup-python. The answers are in the release notes and in a few lines of src/utils/inputs.ts and src/cache/restore-cache.ts.

The first stops a workflow before any step runs. setup-uv has published only full version tags since v8, so @v10, the form most other actions use, is not a ref GitHub can resolve. v10.3.3 is the current release, and everything below is read from that tag.

Pinning: there is no @v10

v8.0.0 was the first immutable release, and its notes say the project will stop publishing major and minor tags because floating tags expose users to supply chain attacks. @v7 and earlier still exist. Anything later fails before the job starts with: Unable to resolve action astral-sh/setup-uv@v10, unable to find version v10. That message is the title of issue #1091.

Pin the commit SHA with the version in a comment, and let Dependabot or Renovate bump it. Pin uv itself separately with version, as uv's own GitHub Actions guide recommends; otherwise the action looks for required-version in uv.toml or pyproject.toml and falls back to the latest uv.

  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
  - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
    with:
      version: "0.13.8"
  - run: uv sync --locked
  - run: uv run pytest

Twenty-seven inputs, four you will touch

Twenty-seven inputs. The ones most workflows touch are version, python-version, enable-cache and cache-dependency-glob.

enable-cache, and the key it saves under

With auto, caching is on only when RUNNER_ENVIRONMENT is github-hosted. GitHub documents the other value as self-hosted, which covers every runner GitHub does not host, so on those auto means off and you set enable-cache: true. At v10.3.3 auto also turns caching off for tag pushes, pull_request_target, workflow_run and release, to keep those events from restoring a poisoned cache; v10.0.0 introduced the event list.

The key is setup-uv-2-, then the architecture, platform, OS name and version, and the Python version, then -pruned and -py when those options are on, then a hash of the files matching cache-dependency-glob, then your suffix. There are no restore keys, so a changed lockfile starts from an empty cache. The cache itself lives where UV_CACHE_DIR points, which the action sets to /tmp/setup-uv-cache on Linux and macOS unless you or your config already chose a path. Since v9 nothing is pruned before the save; prune-cache: true brings back uv cache prune --ci, which drops pre-built wheels and keeps the ones uv built from source. If the glob matches nothing, the action warns that the cache will never get invalidated, and the warning itself tells you to check that the repository was checked out first.

Two jobs with the same dependency files but different resolution strategies compute the same key and race to save it. The README's answer is a cache-suffix per strategy. On an exact hit the post step saves nothing. When caching is on and uv wrote nothing, the post step fails with Cache path <path> does not exist on disk. unless ignore-nothing-to-cache is set.

  - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
    with:
      enable-cache: true
      cache-dependency-glob: uv.lock
      cache-suffix: ${{ matrix.resolution }}

python-version and activate-environment

python-version exports UV_PYTHON, which overrides .python-version and the version in pyproject.toml for every later uv command; it is the documented way to drive a matrix. It does not activate anything. Until v6 it also created a venv; v6 moved that to activate-environment, which runs uv venv, adds the venv's bin directory to PATH and sets VIRTUAL_ENV.

The docs warn against activation for most workflows: a dependency that ships its own uv, such as hatch, then shadows the uv the action installed. uv run gives the same environment without touching PATH.

v6 to v10: activation, tags, pruning, auto cache

setup-uv or setup-python plus pip

They are not exclusive. uv's own guide shows both: uv python install after setup-uv, or setup-python before it, and says setup-python can be faster because GitHub keeps several Python versions on the runner image. The setup-uv README puts that at about a second.

The real difference is the cache. setup-python's pip cache stores pip's download cache with a restore key that falls back to an older entry; setup-uv stores the uv cache, including wheels uv built from source, on one key. Caching pip and Poetry measures what the pip cache is worth.

Key takeaways

• There is no @v8, @v9 or @v10 tag: pin the commit SHA and pin uv with version.
• enable-cache: auto is off on any runner GitHub does not host and on four sensitive event types.
• The cache has no restore keys, so a lockfile change means a cold cache.
• python-version sets UV_PYTHON; activation is separate and usually unnecessary.

Frequently asked questions

Related guides

References

• astral-sh/setup-uv README and action.yml at v10.3.3 (read 2026-11-12)
• astral-sh/setup-uv docs/caching.md
• astral-sh/setup-uv v8.0.0 release notes: no more major tags
• uv docs: using uv in GitHub Actions
• GitHub Docs: default environment variables, RUNNER_ENVIRONMENT
• Python documentation
• pip documentation
• GitHub Actions documentation