Python アプリケーションをビルドする

Buildpack は、環境変数を利用することで言語固有の構成に対応します。

Python のバージョンを指定する

デフォルトでは、Python Runtime Buildpack は Python インタープリタの最新の安定版を使用します。アプリケーションで特定のバージョンが必要な場合は、アプリケーションのルート ディレクトリに .python-version ファイルを配置してそのバージョンを指定します。

3.14

GOOGLE_PYTHON_VERSION を使用する

GOOGLE_PYTHON_VERSION 環境変数を使用して Python バージョンを指定することもできます。両方が構成されている場合、GOOGLE_PYTHON_VERSION 値が .python-version ファイルに優先します。.python-version ファイルと GOOGLE_PYTHON_VERSION 環境変数のどちらも指定されていない場合、デフォルトでは、最新の LTS バージョンの Python が使用されます。

アプリのデプロイ時に Python 3.13 を使用するように Buildpack を構成するには:

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env GOOGLE_PYTHON_VERSION="3.14.x"

project.toml プロジェクト記述子を使用して、プロジェクト ファイルとともに環境変数をエンコードすることもできます。環境変数を使用してアプリケーションを構築する手順をご覧ください。

依存関係を指定する

次のいずれかの方法で、サポートされている Python バージョンのアプリケーションの依存関係を指定します。

  • ルート ディレクトリで requirements.txt ファイルを使用します。このファイルは、ソースコードを含む main.py ファイルと同じディレクトリに置く必要があります。requirements.txt ファイルには、パッケージごとに 1 行が含まれています。各行にはパッケージ名が含まれます。パッケージ名以外に、リクエストされたバージョンが含まれている場合もあります。依存関係のバージョンの変更によってビルドが影響を受けないようにするには、依存関係パッケージを特定のバージョンに固定することを検討します。

    requirements.txt ファイルの例を次に示します。

    functions-framework
requests==2.20.0
numpy

  • 依存関係を指定するには、pyproject.toml ファイルを使用します。requirements.txt ファイルではなく pyproject.toml ファイルでアプリケーションの依存関係を管理する場合、Python Buildpack は pyproject.toml ファイルで指定した構成に基づいてパッケージ管理システムを決定します。詳細については、pyproject.toml ファイルを使用して Python アプリケーションをデプロイするをご覧ください。

    アプリケーションで pyproject.toml ファイルと requirements.txt ファイルの両方を使用している場合、requirements.txt ファイルが優先されます。

    • pyproject.toml ファイルの例を次に示します。

      [project]
name = "demo-app"
version = "0.1.0"
description = ""
requires-python = ">=3.10"
dependencies = [
    "flask>=3.1.1",
    "gunicorn>=23.0.0",
]

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

パッケージ マネージャー

requirements.txt file を使用して依存関係を管理する場合、デフォルトのパッケージ管理システムは、構成する Python のバージョンによって異なります。

requirements.txt ファイルではなく pyproject.toml ファイルを使用して依存関係を管理する場合、Python Buildpack は pyproject.toml ファイルの構成設定に基づいてパッケージ管理システムを決定します。この Buildpack は、pip、uv、Poetry パッケージ管理システムをサポートしています。詳細については、pyproject.toml ファイルを使用して Python アプリケーションをデプロイするをご覧ください。

Python 3.14 以降

Python バージョン 3.14（プレビュー）以降、Python Buildpack は requirements.txt ファイルで指定した依存関係のデフォルトのインストーラとして uv パッケージ管理システムを使用します。

パッケージ管理システムとして pip を使用するには、環境変数 GOOGLE_PYTHON_PACKAGE_MANAGER="pip" を構成します。

Python 3.13 以前

Python バージョン 3.13 以前の場合、Python Buildpack は pip パッケージ管理システムを使用して、requirements.txt ファイルで定義した依存関係をインストールします。

パッケージ管理システムとして uv（プレビュー）を使用するには、環境変数 GOOGLE_PYTHON_PACKAGE_MANAGER="uv" を構成します。

pip を構成する

環境変数を使用して pip の動作を構成できます。

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env PIP_DEFAULT_TIMEOUT='60'

Artifact Registry のプライベート依存関係

Artifact Registry Python リポジトリでは、Python 関数のプライベート依存関係をホストできます。Cloud Build でアプリケーションをビルドすると、Python Buildpack は Cloud Build サービス アカウントに Artifact Registry 認証情報を自動的に生成します。requirements.txt には、追加の認証情報を生成せずに、Artifact Registry URL のみを含める必要があります。例は次のとおりです。

--extra-index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

アプリケーション エントリポイント

次のセクションでは、Python Buildpack のデフォルトのエントリポイントについて説明します。

Cloud Run ソースデプロイにおけるエントリポイント

この機能は、Python ランタイムを使用して Cloud Run にソースコードをデプロイする場合にのみ使用できます。この機能は、Cloud Run ソース デプロイ プロセスの外部で pack build を使用してコンテナ イメージを直接ビルドしている場合は適用されません。

Python Buildpackは、FastAPI、Gradio、Streamlit などの最新のウェブ フレームワークに対応しています。

Python バージョン 3.12 以前

Python バージョン 3.12 以前を使用している場合、Python Buildpack はデフォルトで、ワークロードの WSGI HTTP サーバーとして Gunicorn を使用します。Python Buildpack は、デフォルトのエントリポイントを gunicorn -b :8080 main:app に設定します。

Python バージョン 3.13 以降

Python バージョン 3.13 以降では、Python Buildpack は requirements.txt ファイルのウェブサーバーまたはフレームワーク構成に基づいて、Cloud Run ソース デプロイのデフォルト エントリポイントを設定します。このデフォルト設定は、Cloud Run functions ではなく、Cloud Run サービス ソースのデプロイにのみ適用されます。

Python ランタイムを使用してソースから Cloud Run サービスをデプロイする場合、Buildpack は次の方法で Python バージョンとデフォルトのエントリポイントを決定します。

  • ソースファイルで Python バージョンを指定しない場合、Python Buildpack はデフォルトを対応している最新の Python バージョンに設定します。Buildpack は、requirements.txt ファイルで構成したウェブサーバーまたはフレームワークに基づいて、デフォルトのエントリポイントを決定します。

  • requirements.txt ファイルでウェブサーバーまたはフレームワークを指定しない場合、Python Buildpack はデフォルトで Gunicorn をワークロードの WSGI HTTP サーバーとして使用します。Python Buildpack は、デフォルトのエントリポイントを gunicorn -b :8080 main:app に設定します。

  • Python Buildpack は、requirements.txt ファイルで定義されている次の優先順位に基づいて、デフォルトのエントリポイントを設定します。

    1. gunicorn
    2. uvicorn
    3. fastapi[standard]
    4. gradio
    5. streamlit

ウェブサーバーまたはフレームワークを構成する

requirements.txt ファイルに含まれる一般的な Python 構成ごとに、ソースから Cloud Run へデプロイする際のデフォルトのエントリポイントを次の表に示します。

プライマリ構成 デフォルトのエントリポイント 環境変数
gunicorn gunicorn -b :8080 main:app
numpy gunicorn -b :8080 main:app
fastapi
uvicorn		 uvicorn main:app --host 0.0.0.0 --port 8080
fastapi[standard] uvicorn main:app --host 0.0.0.0 --port 8080
uvicorn
gunicorn		 gunicorn -b :8080 main:app
gradio python main.py GRADIO_SERVER_NAME=0.0.0.0
GRADIO_SERVER_PORT=8080
streamlit streamlit run main.py --server.address 0.0.0.0 --server.port 8080

デプロイの失敗を回避するには、ソースファイルで対応している Python バージョンを使用し、requirements.txt ファイルでウェブサーバーを指定します。

または、次のソース デプロイ コマンドを実行して、エントリポイントを指定することもできます。

  gcloud run deploy SERVICE --source .  --set-build-env-vars GOOGLE_ENTRYPOINT="ENTRYPOINT"

次のように置き換えます。

  • SERVICE: デプロイ先のサービスの名前。
  • ENTRYPOINT: ソースコードに使用するデフォルトのエントリポイント。

ソースコードを Cloud Run にデプロイできない場合や、ログにエラーが見つかった場合は、Cloud Run のトラブルシューティング ガイドをご覧ください。

その他すべてのデプロイにおけるエントリポイント

Python Buildpack は、ワークロードのデフォルトの WSGI HTTP サーバーとして Gunicorn を使用します。Python Buildpack でビルドされたアプリは、次を実行した場合と同様に、デフォルト設定で gunicorn プロセスを開始します。

gunicorn --bind :8080 main:app

アプリケーション エントリポイントをカスタマイズする

Procfile または環境変数を使用して、アプリケーションの起動コマンドをカスタマイズできます。これは、デフォルトのエントリポイント構成をカスタマイズするために必要になることがあります。

Procfile を作成するには、ルート ディレクトリのカスタム設定を使用します。例は次のとおりです。

web: gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

また、pack コマンドで GOOGLE_ENTRYPOINT 環境変数を使用することもできます。例は次のとおりです。

pack build sample-python \
  --builder gcr.io/buildpacks/builder
  --env "GOOGLE_ENTRYPOINT='gunicorn --bind :$PORT main:app'"

環境変数

Python Buildpack では、コンテナをカスタマイズするために次の環境変数を使用できます。

PIP_<key>

pip のドキュメントをご覧ください。

例: PIP_DEFAULT_TIMEOUT=60 は pip コマンドに --default-timeout=60 を設定します。

pyproject.toml ファイルを使用して Python アプリケーションをデプロイする

Python Buildpack は、pyproject.toml ファイルで構成するプロジェクトをサポートしています。この機能を使用すると、Poetry、uv、pip で管理するアプリケーションを Cloud Run と Cloud Run functions に直接デプロイできます。この機能は App Engine では使用できません。

Python Buildpack は、ルート ディレクトリに requirements.txt ファイルがない場合にのみ pyproject.toml ファイルを使用します。アプリケーションで pyproject.toml ファイルと requirements.txt ファイルの両方を使用している場合は、requirements.txt ファイルが優先されます。

サポートされている Buildpack の構成

Python Buildpack は、次の構成をサポートしています。

  • pip Buildpack: 次の条件をすべて検出した場合、pyproject.toml から依存関係を直接インストールします。

    • ルート ディレクトリに pyproject.toml ファイルが存在し、poetry.lock ファイル、[tool.poetry] セクション、uv.lock ファイルなどの優先度の高いツールを構成していない。

    • GOOGLE_PYTHON_PACKAGE_MANAGER 環境変数を pip に設定している。

  • uv Buildpack: uv で管理する Python プロジェクトをサポートします。この Buildpack は、次のいずれかの条件が検出された場合に有効になります。

    • プロジェクトのルートに uv.lock ファイルと pyproject.toml ファイルが存在する。
    • pyproject.toml ファイルがプロジェクト ルートに存在し、GOOGLE_PYTHON_PACKAGE_MANAGER 環境変数が uv に設定されている。
    • pyproject.toml ファイルが存在し、poetry.lock、uv.lock などの他の優先度の高いロックファイルや、[tool.poetry] などの構成が含まれておらず、GOOGLE_PYTHON_PACKAGE_MANAGER 環境変数が設定されていない。

  • Poetry Buildpack: Poetry で管理する Python プロジェクトをサポートします。この Buildpack は、次のいずれかの条件が検出された場合に有効になります。

    • プロジェクトのルートに poetry.lock ファイルと pyproject.toml ファイルが存在する。
    • pyproject.toml ファイルがプロジェクトのルートに存在し、[tool.poetry] セクションが pyproject.toml ファイルに存在する。

パッケージ管理システムの優先順位

Python Buildpack は、次の優先順位で構成に基づいてデフォルトのパッケージ管理システムを決定します。

  1. requirements.txt ファイルが最も優先されます。このファイルが存在する場合にのみ、Python Buildpack はデフォルトのパッケージ管理システムを使用して、ビルドステップで依存関係をインストールします。requirements.txt ファイルが存在しない場合、検出プロセスは次のステップに進みます。

  2. Buildpack は、pyproject.toml ファイルで poetry.lock ファイルまたは [tool.poetry] セクションを確認します。見つかった場合、ビルドプロセスは Poetry を使用して依存関係をインストールします。

  3. Poetry 構成が検出されない場合、Buildpack は uv.lock ファイルを確認します。見つかった場合、ビルドプロセスは uv を使用して依存関係をインストールします。

  4. ロックファイルが存在しない場合、Buildpack は GOOGLE_PYTHON_PACKAGE_MANAGER 環境変数で pip または uv 構成を確認します。

  5. デフォルト。環境変数を設定せず、uv または Poetry を使用せずに pyproject.toml ファイルのみを使用する場合、Buildpack はデフォルトで、サポートされているすべての Python バージョンに uv を使用します。

pyproject.toml ファイルを含むエントリ ポイント

requirements.txt ファイルを使用する代わりに pyproject.toml ファイルを使用してアプリケーションをデプロイすると、Python Buildpack は別の方法でエントリポイントを決定します。requirements.txt ファイルを使用してアプリケーション エントリポイントを構成する方法については、アプリケーション エントリポイントをご覧ください。

Buildpack は、次の優先順位でエントリポイントを検索します。

  1. ルート ディレクトリに Procfile が存在する場合、または GOOGLE_ENTRYPOINT 環境変数を構成する場合、これらの構成は常に pyproject.toml スクリプトによって決定されるエントリ ポイントをオーバーライドします。

  2. Python Buildpack は、[tool.poetry.scripts] セクションと [project.scripts] セクションで構成したカスタム スクリプトを利用します。start を含むスクリプトを構成する場合、これがエントリ ポイントになります。たとえば、poetry run start や uv run start です。

  3. start スクリプトを構成せずに別のスクリプトを定義すると、定義したスクリプトがデフォルトのエントリポイントになります。たとえば、poetry run mycmd や uv run mycmd です。

requirements.txt ベースのビルドとは異なり、Python Buildpack は pyproject.toml プロジェクトの gunicorn を自動的にインストールしません。gunicorn やその他のサーバーを使用するには、pyproject.toml ファイルの依存関係に明示的に追加する必要があります。

pyproject.toml ファイルでカスタム スクリプトを構成しない場合、Buildpack は pyproject.toml 依存関係から gunicorn、uvicorn、fastapi などの一般的なフレームワークを検出し、デフォルトのエントリポイントを決定します。