Python-Anwendung erstellen

Buildpacks unterstützen die sprachspezifische Konfiguration über Umgebungsvariablen.

Python-Version angeben

Standardmäßig verwendet das Python-Laufzeit-Buildpack die aktuellste stabile Version des Python-Interpreters. Wenn Ihre Anwendung eine bestimmte Version erfordert, können Sie eine angeben. Dazu schließen Sie eine .python-version-Datei in das Stammverzeichnis Ihrer Anwendung ein.

3.14

GOOGLE_PYTHON_VERSION verwenden

Es ist auch möglich, die Python-Version über die Umgebungsvariable GOOGLE_PYTHON_VERSION anzugeben. Wenn beide Konfigurationen festgelegt sind, hat der GOOGLE_PYTHON_VERSION-Wert Vorrang vor der .python-version-Datei. Sind sowohl die .python-version-Datei als auch die Umgebungsvariable GOOGLE_PYTHON_VERSION nicht angegeben, wird standardmäßig die neueste LTS-Version von Python verwendet.

So konfigurieren Sie bei der Bereitstellung Ihrer Anwendung ein Buildpack zur Verwendung von Python 3.13:

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

Sie können auch den project.toml-Projektdeskriptor verwenden, um die Umgebungsvariable zusammen mit den Projektdateien zu codieren. Weitere Informationen finden Sie unter Anwendung mit Umgebungsvariablen erstellen.

Abhängigkeiten angeben

Geben Sie die Anwendungsabhängigkeiten für unterstützte Python-Versionen mit einer der folgenden Methoden an:

• Verwenden Sie eine requirements.txt-Datei im Stammverzeichnis. Diese Datei muss sich im selben Verzeichnis wie die Datei main.py befinden, die den Quellcode enthält. Die Datei requirements.txt enthält eine Zeile pro Paket. Jede Zeile enthält den Paketnamen und optional die angeforderte Version. Es empfiehlt sich, Ihre Abhängigkeitspakete an eine bestimmte Version anzuheften, um zu verhindern, dass Ihr Build von Änderungen an der Abhängigkeitsversion beeinträchtigt wird.

  Hier sehen Sie eine requirements.txt-Beispieldatei:

  functions-framework
  requests==2.20.0
  numpy
  

• Verwenden Sie eine pyproject.toml-Datei, um Abhängigkeiten anzugeben. Wenn Sie die Anwendungsabhängigkeiten in einer pyproject.toml-Datei anstelle der requirements.txt-Datei verwalten, bestimmt der Python-Buildpack den Paketmanager anhand der Konfiguration, die Sie in der pyproject.toml-Datei angeben. Weitere Informationen finden Sie unter Python-Anwendungen mit einer pyproject.toml-Datei bereitstellen.

  Wenn Ihre Anwendung sowohl die Datei pyproject.toml als auch die Datei requirements.txt verwendet, hat die Datei requirements.txt Vorrang.

  • Hier sehen Sie eine pyproject.toml-Beispieldatei:

    [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"
    

Paketmanager

Wenn Sie Ihre Abhängigkeiten mit einem requirements.txt file verwalten, variiert der Standardpaketmanager je nach der von Ihnen konfigurierten Python-Version.

Wenn Sie eine pyproject.toml-Datei zum Verwalten von Abhängigkeiten anstelle einer requirements.txt-Datei verwenden, ermittelt das Python-Buildpack den Paketmanager anhand Ihrer Konfigurationseinstellungen in der pyproject.toml-Datei. Das Buildpack unterstützt die Paketmanager pip, uv und Poetry. Weitere Informationen finden Sie unter Python-Anwendungen mit einer pyproject.toml-Datei bereitstellen.

Python 3.14 und höher

Ab Python-Version 3.14 (Vorschau) und höher verwendet das Python-Buildpack den Paketmanager uv als Standardinstallationsprogramm für die Abhängigkeiten, die Sie in Ihrer requirements.txt-Datei angeben.

Wenn Sie pip als Paketmanager verwenden möchten, konfigurieren Sie die Umgebungsvariable GOOGLE_PYTHON_PACKAGE_MANAGER="pip".

Python 3.13 und frühere Versionen

Für Python-Version 3.13 und früher verwendet das Python-Buildpack den Paketmanager pip, um Abhängigkeiten zu installieren, die Sie in der Datei requirements.txt definieren.

Wenn Sie uv (Vorabversion) als Paketmanager verwenden möchten, konfigurieren Sie die Umgebungsvariable GOOGLE_PYTHON_PACKAGE_MANAGER="uv".

PIP konfigurieren

Es ist möglich, das Verhalten von PIP über Umgebungsvariablen zu konfigurieren:

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

Private Abhängigkeiten von Artifact Registry

Ein Artifact Registry-Python-Repository kann private Abhängigkeiten für Ihre Python-Funktion hosten. Wenn Sie eine Anwendung in Cloud Build erstellen, generiert das Python-Buildpack automatisch Artifact Registry-Anmeldedaten für das Cloud Build-Dienstkonto. Sie müssen nur die Artifact Registry-URL in requirements.txt aufnehmen, ohne zusätzliche Anmeldedaten zu generieren. Beispiele:

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

Anwendungseinstiegspunkt

Im folgenden Abschnitt wird der Standard-Einstiegspunkt für den Python-Buildpack beschrieben.

Einstiegspunkt für Cloud Run-Quellbereitstellungen

Diese Funktion ist nur verfügbar, wenn Sie Ihren Quellcode mit der Python-Laufzeit in Cloud Run bereitstellen. Diese Funktion ist nicht anwendbar, wenn Sie Ihr Container-Image direkt mit pack build außerhalb des Cloud Run-Quellcode-Bereitstellungsprozesses erstellen.

Das Python-Buildpack unterstützt moderne Webframeworks wie FastAPI, Gradio und Streamlit.

Python-Version 3.12 und früher

Wenn Sie Python-Version 3.12 oder früher verwenden, wird im Python-Buildpack standardmäßig Gunicorn als WSGI-HTTP-Server für Ihre Arbeitslast verwendet. Das Python-Buildpack legt den Standard-Einstiegspunkt auf gunicorn -b :8080 main:app fest.

Python-Version 3.13 und höher

Für Python-Version 3.13 und höher legt das Python-Buildpack den Standard-Einstiegspunkt für Cloud Run-Quellbereitstellungen basierend auf der Webserver- oder Framework-Konfiguration in Ihrer requirements.txt-Datei fest. Diese Standardeinstellung gilt nur für Quellbereitstellungen von Cloud Run-Diensten, nicht für Cloud Run-Funktionen.

Wenn Sie einen Cloud Run-Dienst aus dem Quellcode mit der Python-Laufzeit bereitstellen, bestimmt das Buildpack die Python-Version und den Standard-Einstiegspunkt auf folgende Weise:

• Wenn Sie in Ihren Quelldateien keine Python-Version angeben, wird vom Python-Buildpack standardmäßig die neueste unterstützte Python-Version festgelegt. Das Buildpack bestimmt den Standard-Einstiegspunkt basierend auf dem Webserver oder Framework, das Sie in Ihrer Datei requirements.txt konfiguriert haben.

• Wenn Sie in Ihrer requirements.txt-Datei keinen Webserver oder kein Framework angeben, verwendet das Python-Buildpack standardmäßig Gunicorn als WSGI-HTTP-Server für Ihre Arbeitslast. Das Python-Buildpack legt den Standard-Einstiegspunkt auf gunicorn -b :8080 main:app fest.

• Das Python-Buildpack legt den Standard-Einstiegspunkt basierend auf der folgenden Prioritätsreihenfolge fest, wie in der Datei requirements.txt definiert:

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

Webserver oder Framework konfigurieren

In der folgenden Tabelle sind für jede gängige Python-Konfiguration in der Datei requirements.txt die Standard-Einstiegspunkte für die Bereitstellung in Cloud Run aus der Quelle aufgeführt:

Primäre Konfiguration	Standardeinstiegspunkt	Umgebungsvariablen
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

Um Bereitstellungsfehler zu vermeiden, verwenden Sie in Ihren Quelldateien eine unterstützte Python-Version und geben Sie in der Datei requirements.txt einen Webserver an.

Alternativ können Sie den Einstiegspunkt auch mit dem folgenden Befehl für die Quellcodebereitstellung angeben:

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

Ersetzen Sie Folgendes:

• SERVICE: Der Name des Dienstes, für den Sie die Bereitstellung ausführen möchten.
• ENTRYPOINT: Der Standardeinstiegspunkt, den Sie für Ihren Quellcode verwenden möchten.

Wenn Sie Ihren Quellcode nicht in Cloud Run bereitstellen können oder Fehler in den Logs finden, lesen Sie die Anleitung zur Fehlerbehebung in Cloud Run.

Einstiegspunkt für alle anderen Bereitstellungen

Das Python-Buildpack verwendet Gunicorn als Standard-WSGI-HTTP-Server für Ihre Arbeitslast. Anwendungen, die mit dem Python-Buildpack erstellt wurden, starten den gunicorn-Prozess mit Standardeinstellungen, ähnlich wie beim Ausführen:

gunicorn --bind :8080 main:app

Anwendungseinstiegspunkt anpassen

Sie können den Startbefehl der Anwendung mithilfe eines Procfile oder einer Umgebungsvariable anpassen. Möglicherweise müssen Sie dies tun, um die Standardkonfigurationen für Einstiegspunkte anzupassen.

Sie können eine Procfile mit Ihren benutzerdefinierten Einstellungen im Stammverzeichnis erstellen. Beispiel:

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

Wichtig: Wenn Sie die Standardeinstellungen von Gunicorn überschreiben, müssen Sie gunicorn als Paketabhängigkeit in die Datei requirements.txt Ihres Projekts aufnehmen.

Alternativ können Sie die Umgebungsvariable GOOGLE_ENTRYPOINT mit dem Befehl pack verwenden. Beispiel:

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

Umgebungsvariablen

Das Python-Buildpack unterstützt folgende Umgebungsvariablen, um Ihren Container anzupassen

PIP_<key>

Weitere Informationen finden Sie in der PIP-Dokumentation.

Beispiel: PIP_DEFAULT_TIMEOUT=60 legt --default-timeout=60 für pip-Befehle fest.

Python-Anwendungen mit einer pyproject.toml-Datei bereitstellen

Vorschau – Deploy Python applications to Cloud Run and Cloud Run functions with a pyproject.toml file

Diese Funktion unterliegt den „Pre-GA-Angebotsbedingungen“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie gesehen“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

Python-Buildpacks unterstützen Projekte, die Sie mit der Datei pyproject.toml konfigurieren. Mit dieser Funktion können Sie Anwendungen, die Sie mit Poetry, uv oder pip verwalten, direkt in Cloud Run und Cloud Run Functions bereitstellen. Diese Funktion ist in App Engine nicht verfügbar.

Das Python-Buildpack verwendet die Datei pyproject.toml nur, wenn sich keine requirements.txt-Datei in Ihrem Stammverzeichnis befindet. Wenn Ihre Anwendung sowohl die Datei pyproject.toml als auch die Datei requirements.txt verwendet, hat die Datei requirements.txt Vorrang.

Unterstützte Buildpacks-Konfigurationen

Python-Buildpacks unterstützen die folgenden Konfigurationen:

• pip-Buildpack: Installiert Abhängigkeiten direkt aus pyproject.toml, wenn alle folgenden Bedingungen erfüllt sind:

  • Im Stammverzeichnis ist eine pyproject.toml-Datei vorhanden und Sie konfigurieren keine Tools mit hoher Priorität wie eine poetry.lock-Datei, einen [tool.poetry]-Abschnitt oder eine uv.lock-Datei.

  • Sie haben die Umgebungsvariable GOOGLE_PYTHON_PACKAGE_MANAGER auf pip festgelegt.

• uv-Buildpack: Unterstützt Python-Projekte, die Sie mit uv verwalten. Dieses Buildpack wird aktiviert, wenn eine der folgenden Bedingungen erfüllt ist:

  • Im Stammverzeichnis des Projekts sind eine uv.lock-Datei und eine pyproject.toml-Datei vorhanden.
  • Im Stammverzeichnis des Projekts ist eine pyproject.toml-Datei vorhanden und Sie haben die Umgebungsvariable GOOGLE_PYTHON_PACKAGE_MANAGER auf uv festgelegt.
  • Eine pyproject.toml-Datei ist vorhanden und Sie haben keine anderen Sperrdateien mit hoher Priorität wie poetry.lock oder uv.lock oder Konfigurationen wie [tool.poetry] angegeben und die Umgebungsvariable GOOGLE_PYTHON_PACKAGE_MANAGER nicht festgelegt.

• Poetry-Buildpack: Unterstützt Python-Projekte, die Sie mit Poetry verwalten. Dieser Buildpack wird aktiviert, wenn eine der folgenden Bedingungen erfüllt ist:

  • Im Stammverzeichnis des Projekts sind eine poetry.lock-Datei und eine pyproject.toml-Datei vorhanden.
  • Im Stammverzeichnis des Projekts ist eine pyproject.toml-Datei vorhanden und in der pyproject.toml-Datei ist ein [tool.poetry]-Abschnitt vorhanden.

Vorrang des Paketmanagers

Die Python-Buildpacks bestimmen den Standardpaketmanager anhand der Konfiguration in der folgenden Prioritätsreihenfolge:

1. Die höchste Priorität hat die Datei requirements.txt. Nur wenn diese Datei vorhanden ist, verwendet das Python-Buildpack den Standardpaketmanager, um Abhängigkeiten im Build-Schritt zu installieren. Wenn keine requirements.txt-Datei vorhanden ist, wird mit dem nächsten Schritt des Erkennungsprozesses fortgefahren.

2. Das Buildpack prüft dann die Datei pyproject.toml auf eine Datei poetry.lock oder einen Abschnitt [tool.poetry]. Wenn die Datei gefunden wird, wird der Build-Prozess fortgesetzt und Poetry wird zum Installieren von Abhängigkeiten verwendet.

3. Wenn keine Poetry-Konfiguration erkannt wird, sucht das Buildpack nach einer uv.lock-Datei. Wenn sie gefunden wird, wird der Build-Prozess fortgesetzt und uv wird verwendet, um Abhängigkeiten zu installieren.

4. Wenn keine Sperrdateien vorhanden sind, prüft das Buildpack die Umgebungsvariable GOOGLE_PYTHON_PACKAGE_MANAGER auf eine pip- oder uv-Konfiguration.

5. Standard. Wenn Sie keine Umgebungsvariable festlegen und nur eine pyproject.toml-Datei ohne uv oder Poetry verwenden, verwendet der Buildpack standardmäßig uv für alle unterstützten Python-Versionen.

Einstiegspunkt mit einer pyproject.toml-Datei

Wenn Sie eine Anwendung mit einer pyproject.toml-Datei anstelle einer requirements.txt-Datei bereitstellen, verwendet das Python-Buildpack eine andere Methode, um den Einstiegspunkt zu ermitteln. Informationen zum Konfigurieren eines Anwendungseinstiegspunkts mit einer requirements.txt-Datei finden Sie unter Anwendungseinstiegspunkt.

Das Buildpack sucht in der folgenden Reihenfolge nach einem Einstiegspunkt:

1. Wenn in Ihrem Stammverzeichnis eine Procfile vorhanden ist oder Sie die Umgebungsvariable GOOGLE_ENTRYPOINT konfigurieren, werden alle durch pyproject.toml-Skripts bestimmten Einstiegspunkte immer durch diese Konfigurationen überschrieben.

2. Das Python-Buildpack verwendet die benutzerdefinierten Skripts, die Sie in den Abschnitten [tool.poetry.scripts] und [project.scripts] konfigurieren. Wenn Sie ein Script konfigurieren, das start enthält, ist dies Ihr Einstiegspunkt. Beispiel: poetry run start oder uv run start.

3. Wenn Sie kein start-Skript konfigurieren, aber ein anderes Skript definieren, ist das von Ihnen definierte Skript der Standardeinstiegspunkt. Beispiel: poetry run mycmd oder uv run mycmd.

Anders als bei requirements.txt-basierten Builds wird gunicorn für pyproject.toml-Projekte nicht automatisch vom Python-Buildpack installiert. Wenn Sie gunicorn oder einen anderen Server verwenden möchten, müssen Sie ihn explizit den Abhängigkeiten in der Datei pyproject.toml hinzufügen.

Wenn Sie in der Datei pyproject.toml keine benutzerdefinierten Skripts konfigurieren, versuchen die Buildpacks, gängige Frameworks wie gunicorn, uvicorn oder fastapi aus Ihren pyproject.toml-Abhängigkeiten zu erkennen und einen Standard-Einstiegspunkt zu bestimmen.