GitHub Actionsでuvを使用する

インストール

GitHub Actionsで使用する場合、公式のastral-sh/setup-uvアクションをお勧めします。これにより、uvがインストールされ、PATHに追加され、（オプションで）キャッシュが永続化されるなど、uvがサポートするすべてのプラットフォームに対応しています。

最新バージョンのuvをインストールするには：

example.yml

name: Example

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

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

特定のuvバージョンにピン留めすることが推奨されます。例えば：

example.yml

name: Example

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

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3
        with:
          # Install a specific version of uv.
          version: "0.5.1"

Pythonのセットアップ

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

example.yml

name: Example

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

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

      - 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

name: Example

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

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

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

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

python-version-fileオプションを設定して、プロジェクトのピン留めバージョンを使用します：

example.yml

name: Example

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

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

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

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

example.yml

name: Example

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

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

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

同期と実行

uvとPythonがインストールされたら、uv syncでプロジェクトをインストールし、uv runで環境内でコマンドを実行できます：

example.yml

name: Example

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

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

      - 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

UV_PROJECT_ENVIRONMENT設定を使用して、仮想環境を作成せずにシステムPython環境にインストールすることができます。

キャッシュ

ワークフローの実行間でuvのキャッシュを保存することで、CIの時間を短縮できる場合があります。

astral-sh/setup-uvには、キャッシュを永続化するための組み込みサポートがあります：

example.yml

- name: Enable caching
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true

ランナー上でカスタムキャッシュディレクトリを使用するようにアクションを構成できます：

example.yml

- name: Define a custom uv cache path
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
    cache-local-path: "/path/to/cache"

または、ロックファイルが変更されたときに無効にします：

example.yml

- name: Define a cache dependency glob
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
    cache-dependency-glob: "uv.lock"

または、任意のrequirementsファイルが変更されたときに無効にします：

example.yml

- name: Define a cache dependency glob
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
    cache-dependency-glob: "requirements**.txt"

astral-sh/setup-uvは、ホストアーキテクチャとプラットフォームごとに自動的に別々のキャッシュキーを使用します。

または、actions/cacheアクションを使用してキャッシュを手動で管理することもできます：

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を使用する場合、キャッシュキーにはrequirements.txtを使用してください。

Note

非エフェメラルなセルフホストランナーを使用する場合、デフォルトのキャッシュディレクトリは無制限に成長する可能性があります。この場合、ジョブ間でキャッシュを共有することは最適ではないかもしれません。代わりに、キャッシュをGitHubワークスペース内に移動し、ジョブが終了したら削除します。Post Job Hookを使用します。

install_job:
  env:
    # Configure a relative location for the uv cache
    UV_CACHE_DIR: ${{ github.workspace }}/.cache/uv

ポストジョブフックを使用するには、セルフホストランナーでACTIONS_RUNNER_HOOK_JOB_STARTED環境変数をクリーンアップスクリプトのパスに設定する必要があります。以下のようなスクリプトです。

clean-uv-cache.sh

#!/usr/bin/env sh
uv cache clean

uv pipの使用

uvプロジェクトインターフェースの代わりに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フラグを使用できます。