Specificare le dipendenze in Python

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"

  • Crea un pacchetto di dipendenze locali insieme alla funzione.

    La specifica delle dipendenze mediante lo standard Pipfile/Pipfile.lock non è supportata. Il tuo progetto non deve includere questi file.

    Se utilizzi un file requirements.txt per gestire le dipendenze, Cloud Run installa Functions Framework per tuo conto quando crei una funzione. Tuttavia, ti consigliamo di includere Functions Framework come dipendenza esplicita per evitare discrepanze.

    Quando utilizzi un file pyproject.toml, devi includere Functions Framework come dipendenza perché Cloud Run non lo installa per tuo conto.

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

Esegui il comando gcloud run deploy per impostare la variabile di ambiente del gestore di pacchetti su pip:

gcloud run deploy SERVICE --source . \
  --set-build-env-vars=GOOGLE_PYTHON_PACKAGE_MANAGER=pip

Sostituisci SERVICE con il nome del tuo servizio Cloud Run.

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

Esegui il comando gcloud beta run deploy per impostare la variabile di ambiente del gestore di pacchetti su uv:

gcloud beta run deploy SERVICE --source . \
  --set-build-env-vars=GOOGLE_PYTHON_PACKAGE_MANAGER=uv

Sostituisci SERVICE con il nome del tuo servizio Cloud Run.

Crea un pacchetto di dipendenze locali

Crea pacchetti delle dipendenze ed esegui il deployment insieme alla funzione. Questo approccio è utile se la dipendenza non è disponibile quando utilizzi un gestore di pacchetti supportato o se l'accesso a internet dell'ambiente Cloud Run è limitato.

Puoi anche utilizzare un file requirements.txt per specificare dipendenze aggiuntive che non hai incluso nel pacchetto insieme alla funzione. Ad esempio, potresti utilizzare la seguente struttura di directory:

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

Importa il codice da localpackage utilizzando la seguente istruzione import:

# code in main.py
from localpackage import script

Questo approccio non esegue alcun file setup.py. Puoi raggruppare i pacchetti con questi file, ma il pacchetto potrebbe non essere eseguito correttamente in Cloud Run Functions.

Dipendenze copiate

Le dipendenze copiate sono dipendenze la cui origine è inclusa direttamente nel pacchetto di codice sorgente e ricompilata insieme al tuo codice. Utilizza la variabile di ambiente di build GOOGLE_VENDOR_PIP_DEPENDENCIES per creare dipendenze pip copiate ed evitare di installarle durante il deployment.

Crea dipendenze copiate

  1. Assicurati che python3 sia installato nel tuo sistema di sviluppo.

  2. Dichiara le dipendenze dell'applicazione in un file requirements.txt nella directory root dell'albero di sviluppo.

  3. Dichiara il framework di Functions come requisito includendo functions-framework in una riga separata nel file requirements.txt.

  4. Scarica le dipendenze della funzione nella directory locale. La procedura da eseguire varia a seconda che la dipendenza sia un file wheel Python (*.whl) o un file tar (*.tar.gz).

    1. Se la dipendenza è un file wheel Python (*.whl), scaricalo nella directory root dell'albero di sviluppo con questo comando pip:

      python3 -m pip download -r requirements.txt --only-binary=:all: \
   -d DIRECTORY \
   --python-version PYTHON_RUNTIME_VERSION \
   --platform manylinux2014_x86_64 \
   --implementation cp

      Sostituisci quanto segue:

      • DIRECTORY: il nome della directory locale in cui eseguire il download.
      • PYTHON_RUNTIME_VERSION: la versione di Python da utilizzare per i controlli di compatibilità. Ad esempio, 314 per Python 3.14.
        Questa versione deve corrispondere a uno dei runtime Python supportati.

      La struttura di directory risultante dovrebbe essere simile alla seguente: 

      myfunction/
├── main.py
└── requirements.txt
└── DIRECTORY
   ├── dependency1.whl
   └── dependency2.whl

    2. Se la dipendenza è un file tar (*.tar.gz):

      1. Se la dipendenza è scritta in Python, utilizza pip per scaricarla:

        python3 -m pip download -r requirements.txt \
   -d DIRECTORY

      2. Se una dipendenza è costituita da codice scritto in C o C++, scarica e compila il codice separatamente.

  5. Esegui il deployment della funzione e delle relative dipendenze copiate:

    gcloud functions deploy FUNCTION_NAME \
  --runtime PYTHON_RUNTIME_NAME \
  --set-build-env-vars GOOGLE_VENDOR_PIP_DEPENDENCIES=DIRECTORY

    Sostituisci quanto segue:

    • FUNCTION_NAME: il nome della funzione di cui stai eseguendo il deployment.
    • PYTHON_RUNTIME_NAME: il nome di uno dei runtime Python supportati in cui eseguire la funzione di cui è stato eseguito il deployment, ad esempio python311. Deve essere la stessa versione del runtime Python che hai utilizzato nel tuo ambiente di sviluppo locale.
    • DIRECTORY: il nome della directory contenente le dipendenze copiate.

Per saperne di più sull'utilizzo dei buildpack, consulta Crea una funzione con i buildpack.

Utilizza dipendenze private

Puoi utilizzare dipendenze private di Artifact Registry o di altri repository.

Dipendenze private di Artifact Registry

Un repository Python di Artifact Registry ospita le dipendenze private della tua funzione Python. Quando esegui il deployment in Cloud Run, il processo di compilazione genera automaticamente le credenziali di Artifact Registry per il service account Cloud Build. Includi l'URL di Artifact Registry nel tuo file requirements.txt senza generare credenziali aggiuntive. Ad esempio:

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

Se la tua build richiede più repository, utilizza un repository virtuale Artifact Registry per controllare in modo sicuro l'ordine in cui pip esegue la ricerca nei repository.

Dipendenze private di altri repository

Buildpack installa le dipendenze in un ambiente Cloud Build che non fornisce l'accesso alle chiavi SSH. Copia i pacchetti ospitati in repository che richiedono l'autenticazione basata su SSH e caricali insieme al codice del progetto.

Utilizza il comando pip install con il flag -t DIRECTORY per copiare le dipendenze private in una directory locale prima di eseguire il deployment dell'app, come segue:

  1. Copia la dipendenza in una directory locale: 
    pip install -t DIRECTORY DEPENDENCY
  2. Aggiungi un file __init__.py vuoto nella directory DIRECTORY per trasformarlo in un modulo.
  3. Esegui l'importazione da questo modulo per utilizzare la dipendenza: 
    import DIRECTORY.DEPENDENCY

Pacchetti preinstallati

Il buildpack Python installa i seguenti pacchetti Python quando esegui il deployment della funzione. Se utilizzi uno di questi pacchetti nel codice della funzione, includi le seguenti versioni nel file requirements.txt:

Per evitare problemi con gli aggiornamenti della versione delle dipendenze, blocca il pacchetto su una versione specifica.

anyio==4.5.2
blinker==1.8.2
click==8.1.8
cloudevents==1.11.0
deprecation==2.1.0
exceptiongroup==1.3.0
Flask==3.0.3
functions-framework==3.9.1
gunicorn==23.0.0
h11==0.16.0
idna==3.10
importlib_metadata==8.5.0
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==2.1.5
packaging==25.0
sniffio==1.3.1
# Install starlette 0.44.0 for Python 3.8
starlette==0.44.0; python_version == '3.8'
# Install starlette 0.49.1 for Python versions greater than 3.8
starlette==0.49.1; python_version > '3.8'
typing_extensions==4.13.2
uvicorn==0.33.0
uvicorn-worker==0.2.0
watchdog==4.0.2
Werkzeug==3.0.6
zipp==3.20.2

Il buildpack Python installa i seguenti pacchetti bloccati su una versione specifica:

  • pip (ultima versione)
  • setuptools (ultima versione)
  • wheel (determinato dai requisiti del prodotto)

Il runtime Python include anche una serie di pacchetti di sistema nell'ambiente di esecuzione.