mirrors/uv
1
0
Fork 0
mirror of https://github.com/astral-sh/uv.git synced 2025-09-01 00:07:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Document official setup-uv action (#7056)

Browse source 
## 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
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

328
docs/guides/integration/github.md
View file

@ -2,165 +2,67 @@
## 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
jobs:
uv-example-linux:
name: python-linux
runs-on: ubuntu-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
```
=== "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:
=== "Linux"
```yaml title="example.yml"
name: Example on Linux
jobs:
uv-example-linux:
name: python-linux
runs-on: ubuntu-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
```
=== "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 name: Example
jobs: jobs:
uv-example-multiplatform: uv-example:
name: python-${{ matrix.os }} name: python
runs-on: ubuntu-latest
strategy:
matrix:
os:
- ubuntu-latest
- windows-latest
- macos-latest
fail-fast: false
runs-on: ${{ matrix.os }}
steps: steps:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
- name: Set up uv - name: Install uv
if: ${{ matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest' }} uses: astral-sh/setup-uv@v2
run: curl -LsSf https://astral.sh/uv/install.sh | sh ```
- name: Set up uv It is considered best practice to pin to a specific uv version, e.g., with:
if: ${{ matrix.os == 'windows-latest' }}
run: irm https://astral.sh/uv/install.ps1 | iex ```yaml title="example.yml" hl_lines="14 15"
shell: powershell name: Example
jobs:
uv-example:
name: python
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
with:
# Install a specific version of uv.
version: "0.4.5"
``` ```
## 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"
steps: name: Example
# ... setup up uv ...
- name: Set up Python jobs:
run: uv python install uv-example:
name: python
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
- name: Set up Python
run: uv python install
``` ```
This will respect the Python version pinned in the project. This will respect the Python version pinned in the project.
@ -178,12 +80,22 @@ 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"
steps: name: Example
# ... setup up uv ...
- name: Set up Python ${{ matrix.python-version }} jobs:
run: uv python install ${{ matrix.python-version }} uv-example:
name: python
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
- name: Set up Python ${{ matrix.python-version }}
run: uv python install ${{ matrix.python-version }}
``` ```
Alternatively, the official GitHub `setup-python` action can be used. This can be faster, because Alternatively, the official GitHub `setup-python` action can be used. This can be faster, because
@ -193,23 +105,47 @@ 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"
steps: name: Example
- name: "Set up Python"
uses: actions/setup-python@v5 jobs:
with: uv-example:
python-version-file: ".python-version" name: python
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
- name: "Set up Python"
uses: actions/setup-python@v5
with:
python-version-file: ".python-version"
``` ```
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"
steps: name: Example
- name: "Set up Python"
uses: actions/setup-python@v5 jobs:
with: uv-example:
python-version-file: "pyproject.toml" name: python
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
- name: "Set up Python"
uses: actions/setup-python@v5
with:
python-version-file: "pyproject.toml"
``` ```
## Syncing and running ## Syncing and running
@ -217,16 +153,29 @@ 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"
steps: name: Example
# ... setup up Python and uv ...
- name: Install the project jobs:
run: uv sync --all-extras --dev uv-example:
name: python
runs-on: ubuntu-latest
- name: Run tests steps:
# For example, using `pytest` - uses: actions/checkout@v4
run: uv run pytest tests
- name: Install uv
uses: astral-sh/setup-uv@v2
- name: Set up Python
run: uv python install
- name: Install the project
run: uv sync --all-extras --dev
- name: Run tests
# For example, using `pytest`
run: uv run pytest tests
``` ```
!!! tip !!! tip
@ -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: