2024-08-24 05:58:26 +08:00
# setup-uv
Set up your GitHub Actions workflow with a specific version of [uv ](https://docs.astral.sh/uv/ ).
2024-09-05 21:24:32 +08:00
- Install a version of uv and add it to PATH
2024-09-05 05:14:10 +08:00
- Cache the installed version of uv to speed up consecutive runs on self-hosted runners
- Register problem matchers for error output
2024-09-05 21:24:32 +08:00
- (Optional) Persist the uv's cache in the GitHub Actions Cache
- (Optional) Verify the checksum of the downloaded uv executable
2024-08-24 05:58:26 +08:00
2024-08-24 06:03:11 +08:00
## Contents
2024-09-05 05:14:10 +08:00
- [Usage ](#usage )
- [Install specific version ](#install-specific-version )
- [Install latest version ](#install-latest-version )
- [Validate checksum ](#validate-checksum )
- [Enable Caching ](#enable-caching )
- [Local cache path ](#local-cache-path )
- [Cache dependency glob ](#cache-dependency-glob )
2024-09-11 16:18:23 +08:00
- [GitHub authentication token ](#github-authentication-token )
2024-09-05 05:14:10 +08:00
- [How it works ](#how-it-works )
- [FAQ ](#faq )
2024-08-24 06:03:11 +08:00
2024-08-24 05:58:26 +08:00
## Usage
2024-09-05 21:24:32 +08:00
### Install the latest version (default)
2024-08-24 05:58:26 +08:00
```yaml
2024-09-05 21:24:32 +08:00
- name: Install the latest version of uv
2024-09-06 20:46:33 +08:00
uses: astral-sh/setup-uv@v2
2024-08-24 05:58:26 +08:00
with:
2024-09-05 21:24:32 +08:00
version: "latest"
2024-08-24 05:58:26 +08:00
```
2024-09-05 21:38:39 +08:00
For an example workflow, see
[here ](https://github.com/charliermarsh/autobot/blob/e42c66659bf97b90ca9ff305a19cc99952d0d43f/.github/workflows/ci.yaml ).
> [!TIP]
>
> Using `latest` requires that uv download the executable on every run, which incurs a cost
> (especially on self-hosted runners). As a best practice, consider pinning the version to a
> specific release.
2024-08-24 05:58:26 +08:00
2024-09-05 21:24:32 +08:00
### Install a specific version
2024-08-24 05:58:26 +08:00
```yaml
2024-09-05 21:24:32 +08:00
- name: Install a specific version of uv
2024-09-06 20:46:33 +08:00
uses: astral-sh/setup-uv@v2
2024-08-24 05:58:26 +08:00
with:
2024-09-05 21:24:32 +08:00
version: "0.4.4"
2024-08-24 05:58:26 +08:00
```
### Validate checksum
2024-09-05 20:06:45 +08:00
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 ](https://github.com/astral-sh/uv/releases ) of the uv repo.
2024-08-24 05:58:26 +08:00
```yaml
- name: Install a specific version and validate the checksum
2024-09-06 20:46:33 +08:00
uses: astral-sh/setup-uv@v2
2024-08-24 05:58:26 +08:00
with:
2024-09-05 20:06:45 +08:00
version: "0.3.1"
checksum: "e11b01402ab645392c7ad6044db63d37e4fd1e745e015306993b07695ea5f9f8"
2024-08-24 05:58:26 +08:00
```
### Enable caching
2024-09-05 21:24:32 +08:00
If you enable caching, the [uv cache ](https://docs.astral.sh/uv/concepts/cache/ ) will be cached to
the GitHub Actions Cache. This can speed up runs that reuse the cache by several minutes. The cache
will always be reused on self-hosted runners.
2024-08-24 05:58:26 +08:00
You can optionally define a custom cache key suffix.
```yaml
- name: Enable caching and define a custom cache key suffix
id: setup-uv
2024-09-06 20:46:33 +08:00
uses: astral-sh/setup-uv@v2
2024-08-24 05:58:26 +08:00
with:
enable-cache: true
2024-09-05 20:06:45 +08:00
cache-suffix: "optional-suffix"
2024-08-24 05:58:26 +08:00
```
2024-09-05 21:24:32 +08:00
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:
2024-08-24 05:58:26 +08:00
```yaml
- name: Do something if the cache was restored
if: steps.setup-uv.outputs.cache-hit == 'true'
run: echo "Cache was restored"
```
#### Local cache path
2024-09-05 21:24:32 +08:00
If you want to save the cache to a local path other than the default path (`/tmp/setup-uv-cache`),
specify the path with the `cache-local-path` input.
2024-08-24 05:58:26 +08:00
```yaml
- name: Define a custom uv cache path
2024-09-06 20:46:33 +08:00
uses: astral-sh/setup-uv@v2
2024-08-24 05:58:26 +08:00
with:
enable-cache: true
2024-09-05 20:06:45 +08:00
cache-local-path: "/path/to/cache"
2024-08-24 05:58:26 +08:00
```
#### Cache dependency glob
2024-09-05 21:24:32 +08:00
If you want to control when the cache is invalidated, specify a glob pattern with the
2024-09-05 20:06:45 +08:00
`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.
2024-08-24 05:58:26 +08:00
```yaml
2024-08-25 22:21:20 +08:00
- name: Define a cache dependency glob
2024-09-06 20:46:33 +08:00
uses: astral-sh/setup-uv@v2
2024-08-24 05:58:26 +08:00
with:
enable-cache: true
2024-09-05 20:06:45 +08:00
cache-dependency-glob: "uv.lock"
2024-08-24 05:58:26 +08:00
```
```yaml
2024-08-25 22:21:20 +08:00
- name: Define a cache dependency glob
2024-09-06 20:46:33 +08:00
uses: astral-sh/setup-uv@v2
2024-08-24 05:58:26 +08:00
with:
enable-cache: true
2024-09-05 20:06:45 +08:00
cache-dependency-glob: "**requirements*.txt"
2024-08-24 05:58:26 +08:00
```
2024-09-06 20:44:31 +08:00
```yaml
- name: Define a list of cache dependency globs
2024-09-11 16:18:23 +08:00
uses: astral-sh/setup-uv@v2
2024-09-06 20:44:31 +08:00
with:
enable-cache: true
cache-dependency-glob: |
2024-09-12 20:58:45 +08:00
**requirements*.txt
**pyproject.toml
2024-09-06 20:44:31 +08:00
```
2024-09-11 16:18:23 +08:00
### GitHub authentication token
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.
2024-08-24 05:58:26 +08:00
2024-09-11 16:18:23 +08:00
If the default
[permissions for the GitHub token ](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token )
are not sufficient, you can provide a custom GitHub token with the necessary permissions.
2024-08-24 05:58:26 +08:00
```yaml
2024-09-11 16:18:23 +08:00
- name: Install the latest version of uv with a custom GitHub token
2024-09-06 20:46:33 +08:00
uses: astral-sh/setup-uv@v2
2024-08-24 05:58:26 +08:00
with:
2024-09-11 16:18:23 +08:00
github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
2024-08-24 05:58:26 +08:00
```
## How it works
2024-09-05 21:24:32 +08:00
This action downloads uv from the uv repo's official
[GitHub Releases ](https://github.com/astral-sh/uv ) and uses the
[GitHub Actions Toolkit ](https://github.com/actions/toolkit ) to cache it as a tool to speed up
consecutive runs on self-hosted runners.
2024-08-24 05:58:26 +08:00
2024-09-05 21:24:32 +08:00
The installed version of uv is then added to the runner PATH, enabling subsequent steps to invoke it
by name (`uv`).
2024-08-24 05:58:26 +08:00
## FAQ
2024-09-05 21:38:39 +08:00
### Do I still need `actions/setup-python` alongside `setup-uv`?
2024-08-24 05:58:26 +08:00
2024-09-05 21:38:39 +08:00
No. This action is modelled as a drop-in replacement for `actions/setup-python` when using uv. With
`setup-uv` , you can install a specific version of Python using `uv python install` rather than
2024-09-05 21:54:40 +08:00
relying on `actions/setup-python` .
2024-08-24 05:58:26 +08:00
2024-09-05 21:24:32 +08:00
For example:
2024-08-24 05:58:26 +08:00
```yaml
- name: Checkout the repository
uses: actions/checkout@main
- name: Install the latest version of uv
2024-09-06 20:46:33 +08:00
uses: astral-sh/setup-uv@v2
2024-08-24 05:58:26 +08:00
with:
enable-cache: true
- name: Test
2024-08-25 22:21:20 +08:00
run: uv run --frozen pytest
2024-08-24 05:58:26 +08:00
```
2024-09-05 21:24:32 +08:00
To install a specific version of Python, use
2024-09-05 20:06:45 +08:00
[`uv python install` ](https://docs.astral.sh/uv/guides/install-python/ ):
2024-08-28 19:28:02 +08:00
```yaml
- name: Install the latest version of uv
2024-09-06 20:46:33 +08:00
uses: astral-sh/setup-uv@v2
2024-08-28 19:28:02 +08:00
with:
enable-cache: true
- name: Install Python 3.12
run: uv python install 3.12
```
2024-08-24 05:58:26 +08:00
### What is the default version?
2024-09-05 21:24:32 +08:00
By default, this action installs the latest version of uv.
2024-08-24 05:58:26 +08:00
2024-09-05 21:24:32 +08:00
If you require the installed version in subsequent steps of your workflow, use the `uv-version`
output:
2024-08-24 05:58:26 +08:00
```yaml
- name: Checkout the repository
2024-08-25 22:21:20 +08:00
uses: actions/checkout@main
2024-08-24 05:58:26 +08:00
- name: Install the default version of uv
id: setup-uv
2024-09-06 20:46:33 +08:00
uses: astral-sh/setup-uv@v2
2024-08-24 05:58:26 +08:00
- name: Print the installed version
run: echo "Installed uv version is ${{ steps.setup-uv.outputs.uv-version }}"
```
2024-09-05 05:13:00 +08:00
## Acknowledgements
`setup-uv` was initially written and published by [Kevin Stillhammer ](https://github.com/eifinger )
2024-09-05 20:06:45 +08:00
before moving under the official [Astral ](https://github.com/astral-sh ) GitHub organization. You can
support Kevin's work in open source on [Buy me a coffee ](https://www.buymeacoffee.com/eifinger ) or
[PayPal ](https://paypal.me/kevinstillhammer ).
2024-09-05 05:13:00 +08:00
## License
MIT
2024-08-24 05:58:26 +08:00
2024-09-05 05:13:00 +08:00
< div align = "center" >
< a target = "_blank" href = "https://astral.sh" style = "background:none" >
< img src = "https://raw.githubusercontent.com/astral-sh/uv/main/assets/svg/Astral.svg" alt = "Made by Astral" >
< / a >
< / div >