Python
/
uv
mirror of https://github.com/astral-sh/uv
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document official `setup-uv` action (#7056) 

## Summary

Closes https://github.com/astral-sh/uv/issues/7047.
This commit is contained in:
Charlie Marsh 2024-09-05 13:59:01 -04:00 committed by GitHub
parent d0fa9ccdfa
commit 2da795ae8c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 161 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/sync-python-releases.yml vendored
View File

@ -17,7 +17,7 @@ jobs:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
- uses: astral-sh/setup-uv@main - uses: astral-sh/setup-uv@v2
with: with:
version: "latest" version: "latest"
enable-cache: true enable-cache: true

264
docs/guides/integration/github.md
View File

@ -2,162 +2,64 @@
## Installation ## Installation
uv installation differs depending on the platform: For use with GitHub Actions, we recommend the official
[`astral-sh/setup-uv`](https://github.com/astral-sh/setup-uv) action, which installs uv, adds it to
PATH, (optionally) persists the cache, and more, with support for all uv-supported platforms.
=== "Linux" To install the latest version of uv:
```yaml title="example.yml" ```yaml title="example.yml" hl_lines="11-12"
name: Example on Linux name: Example
jobs: jobs:
uv-example-linux: uv-example:
name: python-linux name: python
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
- name: Set up uv - name: Install uv
# Install latest uv version using the installer uses: astral-sh/setup-uv@v2
run: curl -LsSf https://astral.sh/uv/install.sh | sh
```
=== "macOS"
```yaml title="example.yml"
name: Example on macOS
jobs:
uv-example-macos:
name: python-macos
runs-on: macos-latest
steps:
- uses: actions/checkout@v4
- name: Set up uv
# Install latest uv version using the installer
run: curl -LsSf https://astral.sh/uv/install.sh | sh
```
=== "Windows"
```yaml title="example.yml"
name: Example on Windows
jobs:
uv-example-windows:
name: python-windows
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
- name: Set up uv
# Install latest uv version using the installer
run: irm https://astral.sh/uv/install.ps1 | iex
shell: powershell
``` ```
It is considered best practice to pin to a specific uv version, e.g., with: It is considered best practice to pin to a specific uv version, e.g., with:
=== "Linux" ```yaml title="example.yml" hl_lines="14 15"
name: Example
```yaml title="example.yml"
name: Example on Linux
jobs: jobs:
uv-example-linux: uv-example:
name: python-linux name: python
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
- name: Set up uv - name: Install uv
# Install a specific uv version using the installer uses: astral-sh/setup-uv@v2
run: curl -LsSf https://astral.sh/uv/0.4.5/install.sh | sh with:
``` # Install a specific version of uv.
version: "0.4.5"
=== "macOS"
```yaml title="example.yml"
name: Example on macOS
jobs:
uv-example-macos:
name: python-macos
runs-on: macos-latest
steps:
- uses: actions/checkout@v4
- name: Set up uv
# Install a specific uv version using the installer
run: curl -LsSf https://astral.sh/uv/0.4.5/install.sh | sh
```
=== "Windows"
```yaml title="example.yml"
name: Example on Windows
jobs:
uv-example-windows:
name: python-windows
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
- name: Set up uv
# Install a specific uv version using the installer
run: irm https://astral.sh/uv/0.4.5/install.ps1 | iex
shell: powershell
```
### Using a matrix
If you need to support multiple platforms, you can use a matrix:
```yaml title="example.yml"
name: Example
jobs:
uv-example-multiplatform:
name: python-${{ matrix.os }}
strategy:
matrix:
os:
- ubuntu-latest
- windows-latest
- macos-latest
fail-fast: false
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- name: Set up uv
if: ${{ matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest' }}
run: curl -LsSf https://astral.sh/uv/install.sh | sh
- name: Set up uv
if: ${{ matrix.os == 'windows-latest' }}
run: irm https://astral.sh/uv/install.ps1 | iex
shell: powershell
``` ```
## Setting up Python ## Setting up Python
Python can be installed with the `python install` command: Python can be installed with the `python install` command:
```yaml title="example.yml" ```yaml title="example.yml" hl_lines="14 15"
name: Example
jobs:
uv-example:
name: python
runs-on: ubuntu-latest
steps: steps:
# ... setup up uv ... - uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
- name: Set up Python - name: Set up Python
run: uv python install run: uv python install
@ -178,9 +80,19 @@ strategy:
Provide the version to the `python install` invocation: Provide the version to the `python install` invocation:
```yaml title="example.yml" ```yaml title="example.yml" hl_lines="14 15"
name: Example
jobs:
uv-example:
name: python
runs-on: ubuntu-latest
steps: steps:
# ... setup up uv ... - uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
- name: Set up Python ${{ matrix.python-version }} - name: Set up Python ${{ matrix.python-version }}
run: uv python install ${{ matrix.python-version }} run: uv python install ${{ matrix.python-version }}
@ -193,8 +105,20 @@ Set the
[`python-version-file`](https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#using-the-python-version-file-input) [`python-version-file`](https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#using-the-python-version-file-input)
option to use the pinned version for the project: option to use the pinned version for the project:
```yaml title="example.yml" ```yaml title="example.yml" hl_lines="14 15 16 17"
name: Example
jobs:
uv-example:
name: python
runs-on: ubuntu-latest
steps: steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
- name: "Set up Python" - name: "Set up Python"
uses: actions/setup-python@v5 uses: actions/setup-python@v5
with: with:
@ -204,8 +128,20 @@ steps:
Or, specify the `pyproject.toml` file to ignore the pin and use the latest version compatible with Or, specify the `pyproject.toml` file to ignore the pin and use the latest version compatible with
the project's `requires-python` constraint: the project's `requires-python` constraint:
```yaml title="example.yml" ```yaml title="example.yml" hl_lines="17"
name: Example
jobs:
uv-example:
name: python
runs-on: ubuntu-latest
steps: steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
- name: "Set up Python" - name: "Set up Python"
uses: actions/setup-python@v5 uses: actions/setup-python@v5
with: with:
@ -217,9 +153,22 @@ steps:
Once uv and Python are installed, the project can be installed with `uv sync` and commands can be Once uv and Python are installed, the project can be installed with `uv sync` and commands can be
run in the environment with `uv run`: run in the environment with `uv run`:
```yaml title="example.yml" ```yaml title="example.yml" hl_lines="17-22"
name: Example
jobs:
uv-example:
name: python
runs-on: ubuntu-latest
steps: steps:
# ... setup up Python and uv ... - uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
- name: Set up Python
run: uv python install
- name: Install the project - name: Install the project
run: uv sync --all-extras --dev run: uv sync --all-extras --dev
@ -239,7 +188,50 @@ steps:
It may improve CI times to store uv's cache across workflow runs. It may improve CI times to store uv's cache across workflow runs.
The cache can be saved and restored with the official GitHub `cache` action: The [`astral-sh/setup-uv`](https://github.com/astral-sh/setup-uv) has built-in support for
persisting the cache:
```yaml title="example.yml"
- name: Enable caching
uses: astral-sh/setup-uv@v2
with:
enable-cache: true
```
You can configure the action to use a custom cache directory on the runner:
```yaml title="example.yml"
- name: Define a custom uv cache path
uses: astral-sh/setup-uv@v2
with:
enable-cache: true
cache-local-path: "/path/to/cache"
```
Or invalidate it when the lockfile changes:
```yaml title="example.yml"
- name: Define a cache dependency glob
uses: astral-sh/setup-uv@v2
with:
enable-cache: true
cache-dependency-glob: "uv.lock"
```
Or when any requirements file changes:
```yaml title="example.yml"
- name: Define a cache dependency glob
uses: astral-sh/setup-uv@v2
with:
enable-cache: true
cache-dependency-glob: "requirements**.txt"
```
Note that `astral-sh/setup-uv` will automatically use a separate cache key for each host
architecture and platform.
Alternatively, you can manage the cache manually with the `actions/cache` action:
```yaml title="example.yml" ```yaml title="example.yml"
jobs: jobs: