Repository files navigation

Set up your GitHub Actions workflow with a specific version ofuv.

• Install a version of uv and add it to PATH
• Cache the installed version of uv to speed up consecutive runs on self-hosted runners
• Register problem matchers for error output
• (Optional) Persist the uv's cache in the GitHub Actions Cache
• (Optional) Verify the checksum of the downloaded uv executable

• Usage
  • Install the latest version (default)
  • Install a specific version
  • Install a version by supplying a semver range
  • Validate checksum
  • Enable Caching
    • Cache dependency glob
  • Local cache path
  • GitHub authentication token
  • UV_TOOL_DIR
  • UV_TOOL_BIN_DIR
• How it works
• FAQ

-name:Install the latest version of uvuses:astral-sh/setup-uv@v3with:version:"latest"

For an example workflow, seehere.

-name:Install a specific version of uvuses:astral-sh/setup-uv@v3with:version:"0.4.4"

You can also specify asemver rangeto install the latest version that satisfies the range.

-name:Install a semver range of uvuses:astral-sh/setup-uv@v3with:version:">=0.4.0"

-name:Pinning a minor version of uvuses:astral-sh/setup-uv@v3with:version:"0.4.x"

You can also specify a checksum to validate the downloaded file. Checksums up to the default versionare automatically verified by this action. The sha256 hashes can be found on thereleases page of the uv repo.

-name:Install a specific version and validate the checksumuses:astral-sh/setup-uv@v3with:version:"0.3.1"checksum:"e11b01402ab645392c7ad6044db63d37e4fd1e745e015306993b07695ea5f9f8"

If you enable caching, theuv cache will be cached tothe GitHub Actions Cache. This can speed up runs that reuse the cache by several minutes.

You can optionally define a custom cache key suffix.

-name:Enable caching and define a custom cache key suffixid:setup-uvuses:astral-sh/setup-uv@v3with:enable-cache:truecache-suffix:"optional-suffix"

When the cache was successfully restored, the outputcache-hit will be set totrue and you canuse it in subsequent steps. For example, to use the cache in the above case:

-name:Do something if the cache was restoredif:steps.setup-uv.outputs.cache-hit == 'true'run:echo "Cache was restored"

If you want to control when the cache is invalidated, specify a glob pattern with thecache-dependency-glob input. The cache will be invalidated if any file matching the glob patternchanges. The glob matches files relative to the repository root.

-name:Define a cache dependency globuses:astral-sh/setup-uv@v3with:enable-cache:truecache-dependency-glob:"**/requirements*.txt"

-name:Define a list of cache dependency globsuses:astral-sh/setup-uv@v3with:enable-cache:truecache-dependency-glob:|      **/requirements*.txt      **/pyproject.toml

-name:Never invalidate the cacheuses:astral-sh/setup-uv@v3with:enable-cache:truecache-dependency-glob:""

This action controls where uv stores its cache on the runner's filesystem by settingUV_CACHE_DIR.It defaults tosetup-uv-cache in theTMP dir,D:\a\_temp\uv-tool-dir on Windows and/tmp/setup-uv-cache on Linux/macOS. You can change the default by specifying the path with thecache-local-path input.

-name:Define a custom uv cache pathuses:astral-sh/setup-uv@v3with:cache-local-path:"/path/to/cache"

By default, the uv cache is pruned after every run, removing pre-built wheels, but retaining anywheels that were built from source. On GitHub-hosted runners, it's typically faster to omit thosepre-built wheels from the cache (and instead re-download them from the registry on each run).However, on self-hosted or local runners, preserving the cache may be more efficient. Seethedocumentation formore.

If you want to persist the entire cache across runs, disable cache pruning with theprune-cacheinput.

-name:Don't prune the cache before saving ituses:astral-sh/setup-uv@v3with:enable-cache:trueprune-cache:false

This action uses the GitHub API to fetch the uv release artifacts. To avoid hitting the GitHub APIrate limit too quickly, an authentication token can be provided via thegithub-token input. Bydefault, theGITHUB_TOKEN secret is used, which is automatically provided by GitHub Actions.

If the defaultpermissions for the GitHub tokenare not sufficient, you can provide a custom GitHub token with the necessary permissions.

-name:Install the latest version of uv with a custom GitHub tokenuses:astral-sh/setup-uv@v3with:github-token:${{ secrets.CUSTOM_GITHUB_TOKEN }}

On WindowsUV_TOOL_DIR is set touv-tool-dir in theTMP dir (e.g.D:\a\_temp\uv-tool-dir).On GitHub hosted runners this is on the much fasterD: drive.

On all other platforms the tool environments are placed in thedefault location.

If you want to change this behaviour (especially on self-hosted runners) you can use thetool-dirinput:

-name:Install the latest version of uv with a custom tool diruses:astral-sh/setup-uv@v3with:tool-dir:"/path/to/tool/dir"

On WindowsUV_TOOL_BIN_DIR is set touv-tool-bin-dir in theTMP dir (e.g.D:\a\_temp\uv-tool-bin-dir). On GitHub hosted runners this is on the much fasterD: drive. Thispath is also automatically added to the PATH.

On all other platforms the tool binaries get installed to thedefault location.

If you want to change this behaviour (especially on self-hosted runners) you can use thetool-bin-dir input:

-name:Install the latest version of uv with a custom tool bin diruses:astral-sh/setup-uv@v3with:tool-bin-dir:"/path/to/tool-bin/dir"

This action downloads uv from the uv repo's officialGitHub Releases and uses theGitHub Actions Toolkit to cache it as a tool to speed upconsecutive runs on self-hosted runners.

The installed version of uv is then added to the runner PATH, enabling subsequent steps to invoke itby name (uv).

No. This action is modelled as a drop-in replacement foractions/setup-python when using uv. Withsetup-uv, you can install a specific version of Python usinguv python install rather thanrelying onactions/setup-python.

For example:

-name:Checkout the repositoryuses:actions/checkout@main-name:Install the latest version of uvuses:astral-sh/setup-uv@v3with:enable-cache:true-name:Testrun:uv run --frozen pytest

To install a specific version of Python, useuv python install:

-name:Install the latest version of uvuses:astral-sh/setup-uv@v3with:enable-cache:true-name:Install Python 3.12run:uv python install 3.12

By default, this action installs the latest version of uv.

If you require the installed version in subsequent steps of your workflow, use theuv-versionoutput:

-name:Checkout the repositoryuses:actions/checkout@main-name:Install the default version of uvid:setup-uvuses:astral-sh/setup-uv@v3-name:Print the installed versionrun:echo "Installed uv version is ${{ steps.setup-uv.outputs.uv-version }}"

setup-uv was initially written and published byKevin Stillhammerbefore moving under the officialAstral GitHub organization. You cansupport Kevin's work in open source onBuy me a coffee orPayPal.

MIT