astral-sh/setup-uv

Install uv (the fast Python package manager) with built-in cache upload and restore.

Official actionCategory: Language & Toolchain SetupLatest v8View on GitHub

What it does

astral-sh/setup-uv installs uv so later steps can run uv sync, uv run, or uvx. The version defaults to what is pinned in pyproject.toml, or latest.

It also handles caching of the uv cache directory (enable-cache defaults to auto) and can set the Python version via UV_PYTHON or activate a ready-to-use venv.

Usage

workflow (.yml)

steps:
  - uses: actions/checkout@v4
  - uses: astral-sh/setup-uv@v8
    with:
      python-version: '3.13'
  - run: uv sync --locked
  - run: uv run pytest

Inputs

Input	Description	Default	Required
`version`	The version of uv to install, e.g. 0.5.0. Defaults to the version in pyproject.toml or latest.	-	No
`version-file`	File containing the uv version, e.g. uv.toml, pyproject.toml, .tool-versions, uv.lock.	-	No
`python-version`	The version of Python to set UV_PYTHON to.	-	No
`activate-environment`	Use uv venv to activate a venv ready to be used by later steps.	`false`	No
`enable-cache`	Enable uploading of the uv cache.	`auto`	No
`cache-suffix`	Suffix for the cache key.	-	No
`working-directory`	Directory to execute commands in and look for files such as pyproject.toml.	`${{ github.workspace }}`	No

Outputs

Output	Description
`uv-version`	The installed uv version. Useful when using latest.
`uv-path`	The path to the installed uv binary.
`cache-hit`	Whether a cache entry was found.
`venv`	Path to the activated venv if activate-environment is true.

Notes

You usually do not need actions/setup-python alongside this action: uv installs and manages Python itself when python-version is set.

Common errors

The post-run cache save fails when there is nothing in the uv cache directory (for example, the job never ran a uv command); set ignore-nothing-to-cache: true or make sure a uv command actually runs.
uv: command not found in a later step means the setup step did not run first in that job; each job needs its own setup-uv step.

Security and pinning

Pin the action to a commit SHA and pin version to an exact uv release; a floating latest changes resolver behavior between runs.

Alternatives and related

actions/setup-pythonInstall a specific Python version and cache pip, pipenv, or poetry dependencies. actions/cacheCache any files between workflow runs, keyed on a hash of your lockfiles.

Frequently asked questions

Do I still need actions/setup-python with setup-uv?

Generally no. Pass python-version to setup-uv and uv will download and manage the interpreter itself, including caching it when cache-python is enabled.

Why is my uv cache never restored on feature branches?

GitHub Actions cache is scoped by branch: branches can read the default branch cache but not each other's. Make sure a run on the default branch has saved a cache first.