Set up your GitHub Actions workflow with a specific version of uv.

• Install a version of uv and add it to the path
• Cache the installed version of uv to speed up consecutive runs on self-hosted runners
• Register problem matchers for error output
• Optional: Cache the uv cache
• Optional: Verify the checksum of the downloaded uv executable

• Usage
  • Install specific version
  • Install latest version
  • Validate checksum
  • Enable Caching
    • Local cache path
    • Cache dependency glob
  • API rate limit
• How it works
• FAQ

Example workflow in a real world project can be found here

You can also specify a specific version of uv

- name: Install a specific version
  uses: eifinger/setup-uv@v1
  with:
    version: '0.3.0'

By default this action installs the version defined as default in action.yml. This gets automatically updated in a new release of this action when a new version of uv is released. If you don't want to wait for a new release of this action you can use use version: latest.

- name: Install a specific version
  uses: eifinger/setup-uv@v1
  with:
    version: 'latest'

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

- name: Install a specific version and validate the checksum
  uses: eifinger/setup-uv@v1
  with:
    version: '0.3.1'
    checksum: 'e11b01402ab645392c7ad6044db63d37e4fd1e745e015306993b07695ea5f9f8'

If you enable caching the uv cache will be cached to the GitHub Actions Cache. This can speed up runs which can reuse the cache by several minutes. The cache will always be reused on self-hosted runners.

You can optionally define a custom cache key suffix.

- name: Enable caching and define a custom cache key suffix
  id: setup-uv
  uses: eifinger/setup-uv@v1
  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 the example above you can use it like this:

- 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 save the cache to a local path other than the default path (/tmp/setup-uv-cache) you can specify the path with the cache-local-path input.

- name: Define a custom uv cache path
  uses: eifinger/setup-uv@v1
  with:
    enable-cache: true
    cache-local-path: '/path/to/cache'

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

- name: Define a cache dependency glob
  uses: eifinger/setup-uv@v1
  with:
    enable-cache: true
    cache-dependency-glob: 'uv.lock'

- name: Define a cache dependency glob
  uses: eifinger/setup-uv@v1
  with:
    enable-cache: true
    cache-dependency-glob: '**requirements*.txt'

To avoid hitting the error API rate limit exceeded you can supply a GitHub token with the github-token input.

- name: Install uv and supply a GitHub token
  uses: eifinger/setup-uv@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

This action downloads uv from the releases of the uv repo 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 so other steps can just use it by calling uv.

No! This action was modelled as a drop-in replacement for actions/setup-python when using uv.

A simple example workflow could look like this:

- name: Checkout the repository
  uses: actions/checkout@main
- name: Install the latest version of uv
  uses: eifinger/setup-uv@v1
  with:
    enable-cache: true
- name: Test
  run: uv run --frozen pytest

If you want to have a specific python version installed you can use the command uv python install:

- name: Install the latest version of uv
  uses: eifinger/setup-uv@v1
  with:
    enable-cache: true
- name: Install Python 3.12
  run: uv python install 3.12

By default this action installs the version defined as default in action.yml. When a new release of uv is published this triggers an automatic release of this action with the new version as default.

If you have to know the version installed for other steps of your workflow you can use the uv-version output:

- name: Checkout the repository
  uses: actions/checkout@main
- name: Install the default version of uv
  id: setup-uv
  uses: eifinger/setup-uv@v1
- name: Print the installed version
  run: echo "Installed uv version is ${{ steps.setup-uv.outputs.uv-version }}"