Crea un'applicazione Python

I buildpack supportano la configurazione idiomatica della lingua tramite le variabili di ambiente.

Specificare la versione di Python

Per impostazione predefinita, il buildpack del runtime Python utilizza l'ultima versione stabile dell'interprete Python. Se la tua applicazione richiede una versione specifica, puoi specificarla includendo un file .python-version nella directory principale dell'applicazione.

3.14

Utilizzare GOOGLE_PYTHON_VERSION

È anche possibile specificare la versione di Python utilizzando la variabile di ambiente GOOGLE_PYTHON_VERSION. Se vengono impostate entrambe le configurazioni, il valore GOOGLE_PYTHON_VERSION ha la precedenza sul file .python-version. Per impostazione predefinita, se non vengono specificati sia il file .python-version sia la variabile di ambiente GOOGLE_PYTHON_VERSION, viene utilizzata l'ultima versione LTS di Python.

Per configurare il buildpack in modo che utilizzi una versione Python supportata durante il deployment dell'app:

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

Puoi anche utilizzare un descrittore di progetto project.toml per codificare la variabile di ambiente insieme ai file di progetto. Consulta le istruzioni per la creazione dell'applicazione con le variabili di ambiente.

Specificare le dipendenze

Specifica le dipendenze dell'applicazione per le versioni Python supportate utilizzando uno dei seguenti approcci:

• Utilizza un file requirements.txt nella directory principale. Questo file deve trovarsi nella stessa directory del file main.py che contiene il codice sorgente. Il file requirements.txt contiene una riga per pacchetto. Ogni riga contiene il nome del pacchetto e, facoltativamente, la versione richiesta. Per evitare che la build sia interessata dalle modifiche alla versione delle dipendenze, ti consigliamo di bloccare i pacchetti di dipendenze su una versione specifica.

  Di seguito è riportato un esempio di file requirements.txt:

  functions-framework
  requests==2.20.0
  numpy
  

• Utilizza un file pyproject.toml per specificare le dipendenze. Se gestisci le dipendenze dell'applicazione in un file pyproject.toml anziché nel file requirements.txt, il buildpack Python determina il gestore di pacchetti in base alla configurazione specificata nel file pyproject.toml. Per saperne di più, consulta Eseguire il deployment di applicazioni Python con un file pyproject.toml.

  Se l'applicazione utilizza sia il file pyproject.toml sia il file requirements.txt, quest'ultimo ha la precedenza.requirements.txt

  • Di seguito è riportato un esempio di file 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"
    

Gestore di pacchetti

Se gestisci le dipendenze utilizzando un requirements.txt file, il gestore di pacchetti predefinito varia in base alla versione di Python configurata.

Se utilizzi un file pyproject.toml per gestire le dipendenze anziché un file requirements.txt, il buildpack Python determina il gestore di pacchetti in base alle impostazioni di configurazione nel file pyproject.toml. Il buildpack supporta i gestori di pacchetti pip, uv e Poetry. Per saperne di più, consulta Eseguire il deployment di applicazioni Python con un pyproject.toml file.

Python 3.14 e versioni successive

A partire dalla versione Python 3.14 e successive, il buildpack Python utilizza il gestore di pacchetti uv come programma di installazione predefinito per le dipendenze specificate nel file requirements.txt.

Per utilizzare pip come gestore di pacchetti, configura la variabile di ambiente GOOGLE_PYTHON_PACKAGE_MANAGER="pip".

Python 3.13 e versioni precedenti

Per la versione Python 3.13 e precedenti, il buildpack Python utilizza il gestore di pacchetti pip per installare le dipendenze definite nel file requirements.txt.

Per utilizzare uv come gestore di pacchetti, configura la variabile di ambiente GOOGLE_PYTHON_PACKAGE_MANAGER="uv".

Configurare pip

È possibile configurare il comportamento di pip utilizzando le variabili di ambiente:

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

Dipendenze private di Artifact Registry

Un repository Python di Artifact Registry può ospitare le dipendenze private della tua funzione Python. Quando crei un'applicazione su Cloud Build, il buildpack Python genera automaticamente le credenziali Artifact Registry per il service account Cloud Build. Devi solo includere l'URL di Artifact Registry nel tuo file requirements.txt senza generare credenziali aggiuntive. Ad esempio:

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

Entry point dell'applicazione

La sezione seguente descrive l'entry point predefinito per il buildpack Python.

Entry point per i deployment di origine di Cloud Run

Questa funzionalità è disponibile solo se esegui il deployment del codice sorgente in Cloud Run con il runtime Python. Questa funzionalità non è applicabile se crei l'immagine container direttamente utilizzando pack build al di fuori del processo di deployment di origine di Cloud Run.

Il buildpack Python supporta i framework web moderni come FastAPI, Gradio, Streamlit e Agent Development Kit (ADK).

Python versione 3.12 e precedenti

Se utilizzi Python versione 3.12 e precedenti, il Python buildpack utilizza per impostazione predefinita Gunicorn come server HTTP WSGI per il tuo workload. Il buildpack Python imposta l'entry point predefinito su gunicorn -b :8080 main:app.

Python versione 3.13 e successive

Per Python versione 3.13 e successive, il buildpack Python imposta l'entry point predefinito per i deployment di origine di Cloud Run in base alla configurazione del server web o del framework nel requirements.txt file. Questa impostazione predefinita si applica solo ai deployment di origine del servizio Cloud Run, non alle funzioni Cloud Run.

Quando esegui il deployment di un servizio Cloud Run dall'origine utilizzando il runtime Python, il buildpack determina la versione di Python e l'entry point predefinito nei seguenti modi:

• Se non specifichi una versione di Python nei file di origine, il buildpack Python imposta come predefinita l'ultima versione di Python supportata. Il buildpack determina l'entry point predefinito in base al server web o al framework configurato nel file requirements.txt.

• Se non specifichi un server web o un framework nel file requirements.txt, il buildpack Python utilizza per impostazione predefinita Gunicorn come server HTTP WSGI per il tuo workload. Il buildpack Python imposta l'entry point predefinito su gunicorn -b :8080 main:app.

• Il buildpack Python imposta l'entry point predefinito in base al seguente ordine di precedenza, come definito nel file requirements.txt:

  1. gunicorn
  2. uvicorn
  3. fastapi[standard]
  4. gradio
  5. streamlit
  6. google-adk

Configurare il server web o il framework

Per ogni configurazione Python comune nel file requirements.txt, la tabella seguente mostra gli entry point predefiniti quando esegui il deployment in Cloud Run dall'origine:

Configurazione principale	Entry point predefinito	Variabili di ambiente
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
google-adk	adk api_server --host 0.0.0.0 --port 8080

Per evitare errori di deployment, utilizza una versione Python supportata nei file di origine e specifica un server web nel file requirements.txt.

In alternativa, puoi anche specificare l'entry point eseguendo il seguente comando di deployment di origine:

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

Sostituisci quanto segue:

• SERVICE: il nome del servizio di cui vuoi eseguire il deployment.
• ENTRYPOINT: l'entry point predefinito che vuoi utilizzare per il codice sorgente.

Se non riesci a eseguire il deployment del codice sorgente in Cloud Run o trovi errori nei log, consulta la guida alla risoluzione dei problemi di Cloud Run.

Entry point per tutti gli altri deployment

Il buildpack Python utilizza Gunicorn come server HTTP WSGI predefinito per il tuo workload. Le app create con il buildpack Python avviano il processo gunicorn con le impostazioni predefinite, in modo simile all'esecuzione di:

gunicorn --bind :8080 main:app

Personalizzare l'entry point dell'applicazione

Puoi personalizzare il comando di avvio delle applicazioni utilizzando un Procfile o una variabile di ambiente. Potrebbe essere necessario farlo per personalizzare le configurazioni dell'entry point predefinito.

Puoi creare un Procfile con le impostazioni personalizzate nella directory principale. Esempio:

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

Importante: quando sostituisci le impostazioni predefinite di Gunicorn, devi includere gunicorn come dipendenza del pacchetto nel file requirements.txt del progetto.

In alternativa, puoi utilizzare la variabile di ambiente GOOGLE_ENTRYPOINT con il comando pack. Esempio:

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

Variabili di ambiente

Il buildpack Python supporta le seguenti variabili di ambiente per personalizzare il container

PIP_<key>

Consulta la documentazione di pip.

Esempio: PIP_DEFAULT_TIMEOUT=60 imposta --default-timeout=60 per i comandi pip.

Eseguire il deployment di applicazioni Python con un file pyproject.toml

I buildpack Python supportano i progetti configurati con il file pyproject.toml. Questa funzionalità ti consente di eseguire il deployment delle applicazioni gestite con Poetry, uv o pip direttamente in Cloud Run e Cloud Run Functions. Questa funzionalità non è disponibile in App Engine.

Il buildpack Python utilizza il file pyproject.toml solo se nella directory principale non è presente un file requirements.txt. Se l'applicazione utilizza sia il file pyproject.toml sia il file requirements.txt, quest'ultimo ha la precedenza.requirements.txt

Configurazioni dei buildpack supportate

I buildpack Python supportano le seguenti configurazioni:

• Buildpack pip: installa le dipendenze direttamente da pyproject.toml se rileva tutte le seguenti condizioni:

  • Nella directory principale è presente un file pyproject.toml e non configuri strumenti con priorità elevata come un file poetry.lock, una sezione [tool.poetry] o un file uv.lock.

  • Imposta la variabile di ambiente GOOGLE_PYTHON_PACKAGE_MANAGER su pip.

• Buildpack uv: supporta i progetti Python gestiti con uv. Questo buildpack si attiva se rileva una delle seguenti condizioni:

  • Nella radice del progetto sono presenti un file uv.lock e un file pyproject.toml.
  • Nella radice del progetto è presente un file pyproject.toml e imposti la variabile di ambiente GOOGLE_PYTHON_PACKAGE_MANAGER su uv.
  • È presente un file pyproject.toml e non includi altri file di blocco con priorità elevata come poetry.lock, uv.lock o configurazioni come [tool.poetry], e non imposti la variabile di ambiente GOOGLE_PYTHON_PACKAGE_MANAGER.

• Buildpack Poetry: supporta i progetti Python gestiti con Poetry. Questo buildpack si attiva se rileva una delle seguenti condizioni:

  • Nella radice del progetto sono presenti un file poetry.lock e un file pyproject.toml.
  • Nella radice del progetto è presente un file pyproject.toml e una sezione [tool.poetry] nel file pyproject.toml.

Precedenza del gestore di pacchetti

I buildpack Python determinano il gestore di pacchetti predefinito in base alla configurazione nel seguente ordine di precedenza:

1. La priorità più alta viene assegnata al file requirements.txt. Solo se questo file è presente, il buildpack Python utilizza il gestore di pacchetti predefinito per installare le dipendenze nel passaggio di build. Se non è presente un file requirements.txt, il processo di rilevamento passa al passaggio successivo.

2. Il buildpack controlla quindi il file pyproject.toml per verificare la presenza di un file poetry.lock o di una sezione [tool.poetry]. Se viene trovato, il processo di compilazione procede utilizzando Poetry per installare le dipendenze.

3. Se non viene rilevata la configurazione di Poetry, il buildpack controlla la presenza di un file uv.lock. Se viene trovato, il processo di compilazione procede utilizzando uv per installare le dipendenze.

4. Se non sono presenti file di blocco, il buildpack controlla la variabile di ambiente GOOGLE_PYTHON_PACKAGE_MANAGER per una configurazione pip o uv.

5. Valore predefinito. Se non imposti una variabile di ambiente e utilizzi solo un pyproject.toml file senza uv o Poetry, il buildpack utilizza per impostazione predefinita uv per tutte le versioni Python supportate.

Entry point con un file pyproject.toml

Quando esegui il deployment di un'applicazione con un file pyproject.toml anziché utilizzare un file requirements.txt, il buildpack Python utilizza un metodo diverso per determinare l'entry point. Per informazioni sulla configurazione di un entry point dell'applicazione con un file requirements.txt, consulta Entry point dell'applicazione.

Il buildpack cerca un entry point nel seguente ordine di precedenza:

1. Se nella directory principale esiste un Procfile o se configuri la variabile di ambiente GOOGLE_ENTRYPOINT, queste configurazioni sostituiscono sempre qualsiasi entry point determinato dagli script pyproject.toml.

2. Il buildpack Python utilizza gli script personalizzati configurati nelle sezioni [tool.poetry.scripts] e [project.scripts]. Se configuri uno script che include start, questo è il tuo entry point. Ad esempio, poetry run start o uv run start.

3. Se non configuri uno script start, ma ne definisci un altro, lo script definito è l'entry point predefinito. Ad esempio, poetry run mycmd o uv run mycmd.

A differenza delle build basate su requirements.txt, il buildpack Python non installa automaticamente gunicorn per i progetti pyproject.toml. Per utilizzare gunicorn o qualsiasi altro server, devi aggiungerlo esplicitamente alle dipendenze nel file pyproject.toml.

Se non configuri script personalizzati nel file pyproject.toml, i buildpack tentano di rilevare i framework comuni, come gunicorn, uvicorn o fastapi, dalle dipendenze pyproject.toml e determinano un entry point predefinito.