Set up your GitHub Actions workflow with a specific version of uv.
- 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
- How it works
- FAQ
- name: Install the latest version of uv
uses: astral-sh/setup-uv@v4
with:
version: "latest"
For an example workflow, see here.
- name: Install a specific version of uv
uses: astral-sh/setup-uv@v4
with:
version: "0.4.4"
You can specify a semver range to install the latest version that satisfies the range.
- name: Install a semver range of uv
uses: astral-sh/setup-uv@v4
with:
version: ">=0.4.0"
- name: Pinning a minor version of uv
uses: astral-sh/setup-uv@v4
with:
version: "0.4.x"
You can use the input python-version
to
- set the environment variable
UV_PYTHON
for the rest of your workflow - create a new virtual environment with the specified python version
- activate the virtual environment for the rest of your workflow
This will override any python version specifications in pyproject.toml
and .python-version
- name: Install the latest version of uv and set the python version to 3.13t
uses: astral-sh/setup-uv@v4
with:
python-version: 3.13t
- run: uv pip install --python=3.13t pip
You can combine this with a matrix to test multiple python versions:
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.9", "3.10", "3.11", "3.12"]
steps:
- uses: actions/checkout@v4
- name: Install the latest version of uv and set the python version
uses: astral-sh/setup-uv@v4
with:
python-version: ${{ matrix.python-version }}
- name: Test with python ${{ matrix.python-version }}
run: uv run --frozen pytest
You can specify a checksum to validate the downloaded executable. Checksums up to the default version are automatically verified by this action. The sha256 hashes can be found on the releases page of the uv repo.
- name: Install a specific version and validate the checksum
uses: astral-sh/setup-uv@v4
with:
version: "0.3.1"
checksum: "e11b01402ab645392c7ad6044db63d37e4fd1e745e015306993b07695ea5f9f8"
If you enable caching, the uv cache will be uploaded to the GitHub Actions cache. This can speed up runs that reuse the cache by several minutes.
Tip
On self-hosted runners this is usually not needed since the cache generated by uv on the runner's filesystem is not removed after a run. For more details see Local cache path.
You can optionally define a custom cache key suffix.
- name: Enable caching and define a custom cache key suffix
id: setup-uv
uses: astral-sh/setup-uv@v4
with:
enable-cache: true
cache-suffix: "optional-suffix"
When the cache was successfully restored, the output cache-hit
will be set to true
and you can
use it in subsequent steps. For example, to use the cache in the above case:
- name: Do something if the cache was restored
if: steps.setup-uv.outputs.cache-hit == 'true'
run: echo "Cache was restored"
If you want to control when the GitHub Actions cache is invalidated, specify a glob pattern with the
cache-dependency-glob
input. The GitHub Actions cache will be invalidated if any file matching the glob pattern
changes. If you use relative paths, they are relative to the repository root.
Note
The default is
cache-dependency-glob: |
**/requirements*.txt
**/uv.lock
- name: Define a cache dependency glob
uses: astral-sh/setup-uv@v4
with:
enable-cache: true
cache-dependency-glob: "**/pyproject.toml"
- name: Define a list of cache dependency globs
uses: astral-sh/setup-uv@v4
with:
enable-cache: true
cache-dependency-glob: |
**/requirements*.txt
**/pyproject.toml
- name: Define an absolute cache dependency glob
uses: astral-sh/setup-uv@v4
with:
enable-cache: true
cache-dependency-glob: "/tmp/my-folder/requirements*.txt"
- name: Never invalidate the cache
uses: astral-sh/setup-uv@v4
with:
enable-cache: true
cache-dependency-glob: ""
This action controls where uv stores its cache on the runner's filesystem by setting UV_CACHE_DIR
.
It defaults to setup-uv-cache
in the TMP
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 the
cache-local-path
input.
- name: Define a custom uv cache path
uses: astral-sh/setup-uv@v4
with:
cache-local-path: "/path/to/cache"
By default, the uv cache is pruned after every run, removing pre-built wheels, but retaining any wheels that were built from source. On GitHub-hosted runners, it's typically faster to omit those pre-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. See the documentation for more information.
If you want to persist the entire cache across runs, disable cache pruning with the prune-cache
input.
- name: Don't prune the cache before saving it
uses: astral-sh/setup-uv@v4
with:
enable-cache: true
prune-cache: false
By default, the action will fail if caching is enabled but there is nothing to upload (the uv cache directory does not exist).
If you want to ignore this, set the ignore-nothing-to-cache
input to true
.
- name: Ignore nothing to cache
uses: astral-sh/setup-uv@v4
with:
enable-cache: true
ignore-nothing-to-cache: true
This action uses the GitHub API to fetch the uv release artifacts. To avoid hitting the GitHub API
rate limit too quickly, an authentication token can be provided via the github-token
input. By
default, the GITHUB_TOKEN
secret is used, which is automatically provided by GitHub Actions.
If the default permissions for the GitHub token are not sufficient, you can provide a custom GitHub token with the necessary permissions.
- name: Install the latest version of uv with a custom GitHub token
uses: astral-sh/setup-uv@v4
with:
github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
On Windows UV_TOOL_DIR
is set to uv-tool-dir
in the TMP
dir (e.g. D:\a\_temp\uv-tool-dir
).
On GitHub hosted runners this is on the much faster D:
drive.
On all other platforms the tool environments are placed in the default location.
If you want to change this behaviour (especially on self-hosted runners) you can use the tool-dir
input:
- name: Install the latest version of uv with a custom tool dir
uses: astral-sh/setup-uv@v4
with:
tool-dir: "/path/to/tool/dir"
On Windows UV_TOOL_BIN_DIR
is set to uv-tool-bin-dir
in the TMP
dir (e.g.
D:\a\_temp\uv-tool-bin-dir
). On GitHub hosted runners this is on the much faster D:
drive. This
path is also automatically added to the PATH.
On all other platforms the tool binaries get installed to the default location.
If you want to change this behaviour (especially on self-hosted runners) you can use the
tool-bin-dir
input:
- name: Install the latest version of uv with a custom tool bin dir
uses: astral-sh/setup-uv@v4
with:
tool-bin-dir: "/path/to/tool-bin/dir"
This action supports expanding the ~
character to the user's home directory for the following inputs:
cache-local-path
tool-dir
tool-bin-dir
cache-dependency-glob
- name: Expand the tilde character
uses: astral-sh/setup-uv@v4
with:
cache-local-path: "~/path/to/cache"
tool-dir: "~/path/to/tool/dir"
tool-bin-dir: "~/path/to/tool-bin/dir"
cache-dependency-glob: "~/my-cache-buster"
This action downloads uv from the uv repo's official GitHub Releases and uses the GitHub Actions Toolkit to cache it as a tool to speed up consecutive runs on self-hosted runners.
The installed version of uv is then added to the runner PATH, enabling subsequent steps to invoke it
by name (uv
).
With setup-uv
, you can install a specific version of Python using uv python install
rather than
relying on actions/setup-python
.
Using actions/setup-python
can be faster, because GitHub caches the Python versions alongside the runner.
For example:
- name: Checkout the repository
uses: actions/checkout@main
- name: Install the latest version of uv
uses: astral-sh/setup-uv@v4
with:
enable-cache: true
- name: Test
run: uv run --frozen pytest # Uses the Python version automatically installed by uv
To install a specific version of Python, use
uv python install
:
- name: Install the latest version of uv
uses: astral-sh/setup-uv@v4
with:
enable-cache: true
- name: Install Python 3.12
run: 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 the uv-version
output:
- name: Checkout the repository
uses: actions/checkout@main
- name: Install the default version of uv
id: setup-uv
uses: astral-sh/setup-uv@v4
- name: Print the installed version
run: echo "Installed uv version is ${{ steps.setup-uv.outputs.uv-version }}"
setup-uv
was initially written and published by Kevin Stillhammer
before moving under the official Astral GitHub organization. You can
support Kevin's work in open source on Buy me a coffee or
PayPal.
MIT