Skip to content

Commit 3824407

Browse files
charliermarshcharliermarsh
committed
Document official setup-uv action
1 parent 86c8906 commit 3824407

File tree

1 file changed

+148
-163
lines changed

1 file changed

+148
-163
lines changed

‎docs/guides/integration/github.md

Lines changed: 148 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -2,165 +2,70 @@
22

33
## Installation
44

5-
uv installation differs depending on the platform:
5+
For use with GitHub Actions, we recommend the official
6+
[`astral-sh/setup-uv`](https://github.com/astral-sh/setup-uv) action, which installs uv, adds it to
7+
PATH, (optionally) persists the cache, and more, with support for all uv-supported platforms.
68

7-
=== "Linux"
9+
To install the latest version of uv:
810

9-
```yaml title="example.yml"
10-
name: Example on Linux
11-
12-
jobs:
13-
uv-example-linux:
14-
name: python-linux
15-
runs-on: ubuntu-latest
16-
17-
steps:
18-
- uses: actions/checkout@v4
19-
20-
- name: Set up uv
21-
# Install latest uv version using the installer
22-
run: curl -LsSf https://astral.sh/uv/install.sh | sh
23-
```
24-
25-
=== "macOS"
26-
27-
```yaml title="example.yml"
28-
name: Example on macOS
29-
30-
jobs:
31-
uv-example-macos:
32-
name: python-macos
33-
runs-on: macos-latest
34-
35-
steps:
36-
- uses: actions/checkout@v4
37-
38-
- name: Set up uv
39-
# Install latest uv version using the installer
40-
run: curl -LsSf https://astral.sh/uv/install.sh | sh
41-
```
42-
43-
=== "Windows"
44-
45-
```yaml title="example.yml"
46-
name: Example on Windows
11+
```yaml title="example.yml" hl_lines="14-16"
12+
name: Example
4713

48-
jobs:
49-
uv-example-windows:
50-
name: python-windows
51-
runs-on: windows-latest
14+
jobs:
15+
uv-example:
16+
name: python
17+
runs-on: ubuntu-latest
5218

53-
steps:
54-
- uses: actions/checkout@v4
19+
steps:
20+
- uses: actions/checkout@v4
5521

56-
- name: Set up uv
57-
# Install latest uv version using the installer
58-
run: irm https://astral.sh/uv/install.ps1 | iex
59-
shell: powershell
60-
```
22+
- name: Install uv
23+
uses: astral-sh/setup-uv@v1
24+
with:
25+
# Install the latest version of uv (default).
26+
version: "latest"
27+
```
6128
6229
It is considered best practice to pin to a specific uv version, e.g., with:
6330
64-
=== "Linux"
65-
66-
```yaml title="example.yml"
67-
name: Example on Linux
68-
69-
jobs:
70-
uv-example-linux:
71-
name: python-linux
72-
runs-on: ubuntu-latest
73-
74-
steps:
75-
- uses: actions/checkout@v4
76-
77-
- name: Set up uv
78-
# Install a specific uv version using the installer
79-
run: curl -LsSf https://astral.sh/uv/0.4.5/install.sh | sh
80-
```
81-
82-
=== "macOS"
83-
84-
```yaml title="example.yml"
85-
name: Example on macOS
86-
87-
jobs:
88-
uv-example-macos:
89-
name: python-macos
90-
runs-on: macos-latest
91-
92-
steps:
93-
- uses: actions/checkout@v4
94-
95-
- name: Set up uv
96-
# Install a specific uv version using the installer
97-
run: curl -LsSf https://astral.sh/uv/0.4.5/install.sh | sh
98-
```
99-
100-
=== "Windows"
101-
102-
```yaml title="example.yml"
103-
name: Example on Windows
104-
105-
jobs:
106-
uv-example-windows:
107-
name: python-windows
108-
runs-on: windows-latest
109-
110-
steps:
111-
- uses: actions/checkout@v4
112-
113-
- name: Set up uv
114-
# Install a specific uv version using the installer
115-
run: irm https://astral.sh/uv/0.4.5/install.ps1 | iex
116-
shell: powershell
117-
```
118-
119-
### Using a matrix
120-
121-
If you need to support multiple platforms, you can use a matrix:
122-
123-
```yaml title="example.yml"
31+
```yaml title="example.yml" hl_lines="14 15"
12432
name: Example
12533

12634
jobs:
127-
uv-example-multiplatform:
128-
name: python-${{ matrix.os }}
129-
130-
strategy:
131-
matrix:
132-
os:
133-
- ubuntu-latest
134-
- windows-latest
135-
- macos-latest
136-
137-
fail-fast: false
138-
139-
runs-on: ${{ matrix.os }}
35+
uv-example:
36+
name: python
37+
runs-on: ubuntu-latest
14038

14139
steps:
14240
- uses: actions/checkout@v4
14341

144-
- name: Set up uv
145-
if: ${{ matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest' }}
146-
run: curl -LsSf https://astral.sh/uv/install.sh | sh
147-
148-
- name: Set up uv
149-
if: ${{ matrix.os == 'windows-latest' }}
150-
run: irm https://astral.sh/uv/install.ps1 | iex
151-
shell: powershell
42+
- name: Install uv
43+
uses: astral-sh/setup-uv@v1
44+
with:
45+
# Install a specific version of uv.
46+
version: "0.4.5"
15247
```
15348
15449
## Setting up Python
15550
15651
Python can be installed with the `python install` command:
15752

158-
```yaml title="example.yml"
159-
steps:
160-
# ... setup up uv ...
53+
```yaml title="example.yml" hl_lines="14 15"
54+
name: Example
55+
56+
jobs:
57+
uv-example:
58+
name: python
59+
runs-on: ubuntu-latest
60+
61+
steps:
62+
- uses: actions/checkout@v4
63+
64+
- name: Install uv
65+
uses: astral-sh/setup-uv@v1
16166
162-
- name: Set up Python
163-
run: uv python install
67+
- name: Set up Python
68+
run: uv python install
16469
```
16570

16671
This will respect the Python version pinned in the project.
@@ -178,12 +83,22 @@ strategy:
17883

17984
Provide the version to the `python install` invocation:
18085

181-
```yaml title="example.yml"
182-
steps:
183-
# ... setup up uv ...
86+
```yaml title="example.yml" hl_lines="14 15"
87+
name: Example
18488
185-
- name: Set up Python ${{ matrix.python-version }}
186-
run: uv python install ${{ matrix.python-version }}
89+
jobs:
90+
uv-example:
91+
name: python
92+
runs-on: ubuntu-latest
93+
94+
steps:
95+
- uses: actions/checkout@v4
96+
97+
- name: Install uv
98+
uses: astral-sh/setup-uv@v1
99+
100+
- name: Set up Python ${{ matrix.python-version }}
101+
run: uv python install ${{ matrix.python-version }}
187102
```
188103

189104
Alternatively, the official GitHub `setup-python` action can be used. This can be faster, because
@@ -193,40 +108,77 @@ Set the
193108
[`python-version-file`](https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#using-the-python-version-file-input)
194109
option to use the pinned version for the project:
195110

196-
```yaml title="example.yml"
197-
steps:
198-
- name: "Set up Python"
199-
uses: actions/setup-python@v5
200-
with:
201-
python-version-file: ".python-version"
111+
```yaml title="example.yml" hl_lines="14 15 16 17"
112+
name: Example
113+
114+
jobs:
115+
uv-example:
116+
name: python
117+
runs-on: ubuntu-latest
118+
119+
steps:
120+
- uses: actions/checkout@v4
121+
122+
- name: Install uv
123+
uses: astral-sh/setup-uv@v1
124+
125+
- name: "Set up Python"
126+
uses: actions/setup-python@v5
127+
with:
128+
python-version-file: ".python-version"
202129
```
203130

204131
Or, specify the `pyproject.toml` file to ignore the pin and use the latest version compatible with
205132
the project's `requires-python` constraint:
206133

207-
```yaml title="example.yml"
208-
steps:
209-
- name: "Set up Python"
210-
uses: actions/setup-python@v5
211-
with:
212-
python-version-file: "pyproject.toml"
134+
```yaml title="example.yml" hl_lines="17"
135+
name: Example
136+
137+
jobs:
138+
uv-example:
139+
name: python
140+
runs-on: ubuntu-latest
141+
142+
steps:
143+
- uses: actions/checkout@v4
144+
145+
- name: Install uv
146+
uses: astral-sh/setup-uv@v1
147+
148+
- name: "Set up Python"
149+
uses: actions/setup-python@v5
150+
with:
151+
python-version-file: "pyproject.toml"
213152
```
214153

215154
## Syncing and running
216155

217156
Once uv and Python are installed, the project can be installed with `uv sync` and commands can be
218157
run in the environment with `uv run`:
219158

220-
```yaml title="example.yml"
221-
steps:
222-
# ... setup up Python and uv ...
159+
```yaml title="example.yml" hl_lines="17-22"
160+
name: Example
223161
224-
- name: Install the project
225-
run: uv sync --all-extras --dev
162+
jobs:
163+
uv-example:
164+
name: python
165+
runs-on: ubuntu-latest
226166
227-
- name: Run tests
228-
# For example, using `pytest`
229-
run: uv run pytest tests
167+
steps:
168+
- uses: actions/checkout@v4
169+
170+
- name: Install uv
171+
uses: astral-sh/setup-uv@v1
172+
173+
- name: Set up Python
174+
run: uv python install
175+
176+
- name: Install the project
177+
run: uv sync --all-extras --dev
178+
179+
- name: Run tests
180+
# For example, using `pytest`
181+
run: uv run pytest tests
230182
```
231183
232184
!!! tip
@@ -239,7 +191,40 @@ steps:
239191

240192
It may improve CI times to store uv's cache across workflow runs.
241193

242-
The cache can be saved and restored with the official GitHub `cache` action:
194+
The [`astral-sh/setup-uv`](https://github.com/astral-sh/setup-uv) has built-in support for
195+
persisting the cache:
196+
197+
```yaml title="example.yml"
198+
- name: Enable caching
199+
uses: astral-sh/setup-uv@v1
200+
with:
201+
enable-cache: true
202+
```
203+
204+
You can configure the action to use a custom cache directory:
205+
206+
```yaml title="example.yml"
207+
- name: Define a custom uv cache path
208+
uses: astral-sh/setup-uv@v1
209+
with:
210+
enable-cache: true
211+
cache-local-path: "/path/to/cache"
212+
```
213+
214+
Or invalidate it when the lockfile or its inputs change:
215+
216+
```yaml title="example.yml"
217+
- name: Define a cache dependency glob
218+
uses: astral-sh/setup-uv@v1
219+
with:
220+
enable-cache: true
221+
cache-dependency-glob: "uv.lock"
222+
```
223+
224+
Note that `astral-sh/setup-uv` will automatically use a separate cache key for each host
225+
architecture and platform.
226+
227+
Alternatively, you can manage the cache manually with the `actions/cache` action:
243228

244229
```yaml title="example.yml"
245230
jobs:

0 commit comments

Comments
 (0)