Using uv in GitHub Actions

Installation

uvのインストールは、プラットフォームによって異なります。

Unix

example.yml

name: Example on Unix

jobs:
  uv-example-linux:
    name: python-linux
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up uv
        # Install uv using the standalone installer
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

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 uv using the standalone installer
        run: irm https://astral.sh/uv/install.ps1 | iex
        shell: powershell

Using a matrix

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

Pythonはpython installコマンドでインストールできます。:

example.yml

steps:
  # ... setup up uv ...

  - name: Set up Python
    run: uv python install

これにより、プロジェクトに固定されたPythonのバージョンが考慮されます。

または、マトリックスを使用する場合は、次のようになります。:

example.yml

strategy:
  matrix:
    python-version:
      - "3.10"
      - "3.11"
      - "3.12"

python install呼び出しにバージョンを指定します。:

example.yml

steps:
  # ... setup up uv ...

  - name: Set up Python ${{ matrix.python-version }}
    run: uv python install ${{ matrix.python-version }}

あるいは、公式のGitHubsetup-pythonアクションを使用することもできる。GitHubはランナーと一緒にPythonバージョンをキャッシュするので、これはより高速になる。

プロジェクトに固定バージョンを使用するには、python-version-fileオプションを設定します。:

example.yml

steps:
  - name: "Set up Python"
    uses: actions/setup-python@v5
    with:
      python-version-file: ".python-version"

または、ピンを無視し、プロジェクトのrequires-python制約と互換性のある最新バージョンを使用するようにpyproject.tomlファイルを指定します。:

example.yml

steps:
  - name: "Set up Python"
    uses: actions/setup-python@v5
    with:
      python-version-file: "pyproject.toml"

Syncing and running

uvとPythonがインストールされると、プロジェクトはuv syncでインストールでき、コマンドはuv runで環境内で実行できます。:

example.yml

steps:
  # ... setup up Python and uv ...

  - name: Install the project
    run: uv sync --all-extras --dev

  - name: Run tests
    # For example, using `pytest`
    run: uv run pytest tests

Caching

ワークフローの実行中にuvのキャッシュを保存すると、CI時間が改善される可能性があります。

キャッシュは、公式のGitHubcacheアクションで保存および復元できる。:

example.yml

jobs:
  install_job:
    env:
      # Configure a constant location for the uv cache
      UV_CACHE_DIR: /tmp/.uv-cache

    steps:
      # ... setup up Python and uv ...

      - name: Restore uv cache
        uses: actions/cache@v4
        with:
          path: /tmp/.uv-cache
          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
          restore-keys: |
            uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
            uv-${{ runner.os }}

      # ... install packages, run tests, etc ...

      - name: Minimize uv cache
        run: uv cache prune --ci

uv cache prune --ciコマンドは、キャッシュのサイズを小さくするために使用され、CI用に最適化されています。

パフォーマンスへの影響は、インストールされているパッケージによって異なります。

Tip

uv pipを使用する場合は、キャッシュキーでuv.lockの代わりにrequirements.txtを使用してください。

Using uv pip

uv projectインタフェースの代わりにuv pipインタフェースを使用する場合、uvはデフォルトで仮想環境を必要とします。システム環境にパッケージをインストールできるようにするには、すべてのuv呼び出しで--systemフラグを使用するか、UV_SYSTEM_PYTHON変数を設定します。

UV_SYSTEM_PYTHON変数は、さまざまなスコープで定義できます。

ワークフローを最上位レベルで定義して、ワークフロー全体をオプトインします。:

example.yml

env:
  UV_SYSTEM_PYTHON: 1

jobs: ...

または、ワークフロー内の特定のジョブをオプトインします。:

example.yml

jobs:
  install_job:
    env:
      UV_SYSTEM_PYTHON: 1
    ...

または、ジョブの特定のステップを選択します。:

example.yml

steps:
  - name: Install requirements
    run: uv pip install -r requirements.txt
    env:
      UV_SYSTEM_PYTHON: 1

再びオプトアウトするには、uvの呼び出しで--no-systemフラグを使用します。