Skip to content

Commit 2da795a

Browse files
charliermarshcharliermarsh
authored
Document official setup-uv action (#7056)
## Summary Closes #7047.
1 parent d0fa9cc commit 2da795a

File tree

2 files changed

+156
-164
lines changed

2 files changed

+156
-164
lines changed

‎.github/workflows/sync-python-releases.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ jobs:
1717
runs-on: ubuntu-latest
1818
steps:
1919
- uses: actions/checkout@v4
20-
- uses: astral-sh/setup-uv@main
20+
- uses: astral-sh/setup-uv@v2
2121
with:
2222
version: "latest"
2323
enable-cache: true

‎docs/guides/integration/github.md

Lines changed: 155 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -2,165 +2,67 @@
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="11-12"
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@v2
24+
```
6125
6226
It is considered best practice to pin to a specific uv version, e.g., with:
6327
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"
28+
```yaml title="example.yml" hl_lines="14 15"
12429
name: Example
12530

12631
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 }}
32+
uv-example:
33+
name: python
34+
runs-on: ubuntu-latest
14035

14136
steps:
14237
- uses: actions/checkout@v4
14338

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
39+
- name: Install uv
40+
uses: astral-sh/setup-uv@v2
41+
with:
42+
# Install a specific version of uv.
43+
version: "0.4.5"
15244
```
15345
15446
## Setting up Python
15547
15648
Python can be installed with the `python install` command:
15749

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

16668
This will respect the Python version pinned in the project.
@@ -178,12 +80,22 @@ strategy:
17880

17981
Provide the version to the `python install` invocation:
18082

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

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

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"
108+
```yaml title="example.yml" hl_lines="14 15 16 17"
109+
name: Example
110+
111+
jobs:
112+
uv-example:
113+
name: python
114+
runs-on: ubuntu-latest
115+
116+
steps:
117+
- uses: actions/checkout@v4
118+
119+
- name: Install uv
120+
uses: astral-sh/setup-uv@v2
121+
122+
- name: "Set up Python"
123+
uses: actions/setup-python@v5
124+
with:
125+
python-version-file: ".python-version"
202126
```
203127

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

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"
131+
```yaml title="example.yml" hl_lines="17"
132+
name: Example
133+
134+
jobs:
135+
uv-example:
136+
name: python
137+
runs-on: ubuntu-latest
138+
139+
steps:
140+
- uses: actions/checkout@v4
141+
142+
- name: Install uv
143+
uses: astral-sh/setup-uv@v2
144+
145+
- name: "Set up Python"
146+
uses: actions/setup-python@v5
147+
with:
148+
python-version-file: "pyproject.toml"
213149
```
214150

215151
## Syncing and running
216152

217153
Once uv and Python are installed, the project can be installed with `uv sync` and commands can be
218154
run in the environment with `uv run`:
219155

220-
```yaml title="example.yml"
221-
steps:
222-
# ... setup up Python and uv ...
156+
```yaml title="example.yml" hl_lines="17-22"
157+
name: Example
158+
159+
jobs:
160+
uv-example:
161+
name: python
162+
runs-on: ubuntu-latest
163+
164+
steps:
165+
- uses: actions/checkout@v4
223166
224-
- name: Install the project
225-
run: uv sync --all-extras --dev
167+
- name: Install uv
168+
uses: astral-sh/setup-uv@v2
226169
227-
- name: Run tests
228-
# For example, using `pytest`
229-
run: uv run pytest tests
170+
- name: Set up Python
171+
run: uv python install
172+
173+
- name: Install the project
174+
run: uv sync --all-extras --dev
175+
176+
- name: Run tests
177+
# For example, using `pytest`
178+
run: uv run pytest tests
230179
```
231180
232181
!!! tip
@@ -239,7 +188,50 @@ steps:
239188

240189
It may improve CI times to store uv's cache across workflow runs.
241190

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

244236
```yaml title="example.yml"
245237
jobs:

0 commit comments

Comments
 (0)