Crea un'applicazione Python

I buildpack supportano la configurazione idiomatica del linguaggio tramite le variabili di ambiente.

Specificare la versione di Python

Per impostazione predefinita, il buildpack Python Runtime utilizza la versione stabile più recente dell'interprete Python. Se la tua applicazione richiede una versione specifica, puoi specificarne una includendo un file .python-version nella directory root dell'applicazione.

3.14

Utilizza GOOGLE_PYTHON_VERSION

È anche possibile specificare la versione di Python utilizzando la variabile di ambiente GOOGLE_PYTHON_VERSION. Se sono impostate entrambe le configurazioni, il valore GOOGLE_PYTHON_VERSION ha la precedenza sul file .python-version. Per impostazione predefinita, quando 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 Python 3.13 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 creare l'applicazione con le variabili di ambiente.

Specifica le dipendenze

Specifica le dipendenze dell'applicazione per le versioni di 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.

  Ecco 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 maggiori informazioni, vedi Eseguire il deployment di applicazioni Python con un file pyproject.toml.

  Se la tua applicazione utilizza sia il file pyproject.toml sia il file requirements.txt, il file requirements.txt ha la precedenza.

  • Ecco 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 requirements.txt file, il gestore di pacchetti predefinito varia in base alla versione di Python che configuri.

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 ulteriori informazioni, vedi Eseguire il deployment di applicazioni Python con un file pyproject.toml.

Python 3.14 e versioni successive

A partire dalla versione 3.14 (anteprima) e successive di Python, 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 dei pacchetti, configura la variabile di ambiente GOOGLE_PYTHON_PACKAGE_MANAGER="pip".

Python 3.13 e precedenti

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

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

Configurare la funzionalità 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 di 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 il punto di ingresso predefinito per il buildpack Python.

Punto di ingresso per i deployment delle origini Cloud Run

Questa funzionalità è disponibile solo se esegui il deployment del codice sorgente su 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 dell'origine Cloud Run.

Il buildpack Python supporta framework web moderni come FastAPI, Gradio e Streamlit.

Python versione 3.12 e precedenti

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

Python 3.13 e versioni successive

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

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

• Se non specifichi una versione di Python nei file sorgente, il buildpack Python imposta come predefinita l'ultima versione di Python supportata. Il buildpack determina il punto di ingresso predefinito in base al server web o al framework che hai 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 carico di lavoro. Il buildpack Python imposta il punto di ingresso predefinito su gunicorn -b :8080 main:app.

• Il buildpack Python imposta il punto di ingresso 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

Configura il server web o il framework

Per ogni configurazione Python comune nel file requirements.txt, la seguente tabella mostra i punti di ingresso predefiniti durante il deployment in Cloud Run dall'origine:

Configurazione principale	Punto di ingresso 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

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

In alternativa, puoi specificare il punto di ingresso eseguendo il seguente comando di deployment dell'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: il punto di ingresso predefinito che vuoi utilizzare per il codice sorgente.

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

Punto di accesso 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 il punto di ingresso dell'applicazione

Puoi personalizzare il comando di avvio delle applicazioni utilizzando un Procfile o una variabile di ambiente. Potresti doverlo fare per personalizzare le configurazioni predefinite dei punti di ingresso.

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

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

Importante: quando esegui l'override dei valori predefiniti 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.

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

Anteprima — Deploy Python applications to Cloud Run and Cloud Run functions with a pyproject.toml file

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

I buildpack Python supportano i progetti che configuri con il file pyproject.toml. Questa funzionalità ti consente di eseguire il deployment delle applicazioni che gestisci con Poetry, uv o pip direttamente su 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 la tua applicazione utilizza sia il file pyproject.toml sia il file requirements.txt, il file requirements.txt ha la precedenza.

Configurazioni dei buildpack supportate

I buildpack Python supportano le seguenti configurazioni:

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

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

  • Hai impostato la variabile di ambiente GOOGLE_PYTHON_PACKAGE_MANAGER su pip.

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

  • Nella directory root del progetto sono presenti un file uv.lock e un file pyproject.toml.
  • Un file pyproject.toml è presente nella radice del progetto e hai impostato 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 che gestisci con Poetry. Questo buildpack si attiva se rileva una delle seguenti condizioni:

  • Un file poetry.lock e un file pyproject.toml sono presenti nella directory principale del progetto.
  • Un file pyproject.toml è presente nella directory principale del progetto e una sezione [tool.poetry] è presente nel file pyproject.toml.

Priorità del gestore di pacchetti

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

1. La precedenza più alta viene data 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 compilazione. Se un file requirements.txt non è presente, la procedura di rilevamento passa al passaggio successivo.

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

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

4. Se i file di blocco non sono presenti, 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 file pyproject.toml senza uv o Poetry, il buildpack utilizza per impostazione predefinita uv per tutte le versioni di Python supportate.

Punto di ingresso 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 il punto di ingresso. Per informazioni sulla configurazione di un punto di ingresso dell'applicazione con un file requirements.txt, vedi Punto di ingresso dell'applicazione.

Il buildpack cerca un punto di ingresso nel seguente ordine di precedenza:

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

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

3. Se non configuri uno script start, ma definisci un altro script, lo script che definisci è il punto di ingresso 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 framework comuni, come gunicorn, uvicorn o fastapi dalle dipendenze pyproject.toml e determinano un punto di ingresso predefinito.