Créer une application Python

Les buildpacks sont compatibles avec la configuration idiomatique du langage via des variables d'environnement.

Spécifier la version de Python

Par défaut, le buildpack d'exécution Python utilise la dernière version stable de l'interpréteur Python. Si votre application nécessite une version spécifique, vous pouvez en spécifier une en incluant un fichier .python-version dans le répertoire racine de l'application.

3.14

Utiliser GOOGLE_PYTHON_VERSION

Il est également possible de spécifier la version de Python à l'aide de la variable d'environnement GOOGLE_PYTHON_VERSION. Si les deux options sont spécifiées, la valeur de GOOGLE_PYTHON_VERSION est prioritaire sur le fichier .python-version. Par défaut, si aucune des options n'est spécifiée (ni le fichier .python-version, ni la variable d'environnement GOOGLE_PYTHON_VERSION), la dernière version LTS de Python est utilisée.

Pour configurer le buildpack afin d'utiliser Python 3.13 lors du déploiement de votre application, procédez comme suit :

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

Vous pouvez également utiliser un descripteur de projet project.toml pour encoder la variable d'environnement avec vos fichiers de projet. Consultez les instructions décrivant la compilation de l'application avec des variables d'environnement.

Spécifier des dépendances

Spécifiez les dépendances de votre application pour les versions Python compatibles en utilisant l'une des approches suivantes :

• Utilisez un fichier requirements.txt dans le répertoire racine. Ce fichier doit se trouver dans le même répertoire que le fichier main.py qui contient votre code source. Le fichier requirements.txt contient une ligne par package. Chaque ligne contient le nom du package et, éventuellement, la version demandée. Pour éviter que votre compilation ne soit affectée par les modifications de version de dépendance, envisagez d'épingler vos packages de dépendances sur une version spécifique.

  Voici un exemple de fichier requirements.txt :

  functions-framework
  requests==2.20.0
  numpy
  

• Utilisez un fichier pyproject.toml pour spécifier les dépendances. Si vous gérez les dépendances de votre application dans un fichier pyproject.toml au lieu du fichier requirements.txt, le buildpack Python détermine le gestionnaire de packages en fonction de la configuration que vous spécifiez dans le fichier pyproject.toml. Pour en savoir plus, consultez Déployer des applications Python avec un fichier pyproject.toml.

  Si votre application utilise à la fois le fichier pyproject.toml et le fichier requirements.txt, le fichier requirements.txt est prioritaire.

  • Voici un exemple de fichier 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"
    

Gestionnaire de packages

Si vous gérez vos dépendances à l'aide d'un fichier requirements.txt file, le gestionnaire de packages par défaut varie en fonction de la version de Python que vous configurez.

Si vous utilisez un fichier pyproject.toml pour gérer les dépendances au lieu d'un fichier requirements.txt, le buildpack Python détermine le gestionnaire de packages en fonction de vos paramètres de configuration dans le fichier pyproject.toml. Le pack de création est compatible avec les gestionnaires de packages pip, uv et Poetry. Pour en savoir plus, consultez Déployer des applications Python avec un fichier pyproject.toml.

Python 3.14 et versions ultérieures

À partir de la version 3.14 de Python (bêta), le buildpack Python utilise le gestionnaire de packages uv comme programme d'installation par défaut pour les dépendances que vous spécifiez dans votre fichier requirements.txt.

Pour utiliser pip comme gestionnaire de packages, configurez la variable d'environnement GOOGLE_PYTHON_PACKAGE_MANAGER="pip".

Python 3.13 et versions antérieures

Pour Python 3.13 et les versions antérieures, le buildpack Python utilise le gestionnaire de packages pip pour installer les dépendances que vous définissez dans le fichier requirements.txt.

Pour utiliser uv (aperçu) comme gestionnaire de packages, configurez la variable d'environnement GOOGLE_PYTHON_PACKAGE_MANAGER="uv".

Configurer pip

Il est possible de configurer le comportement de pip à l'aide de variables d'environnement :

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

Dépendances privées d'Artifact Registry

Un dépôt Python Artifact Registry peut héberger des dépendances privées pour votre fonction Python. Lors de la compilation d'une application sur Cloud Build, le buildpack Python génère automatiquement des identifiants Artifact Registry pour le compte de service Cloud Build. Il vous suffit d'inclure l'URL Artifact Registry dans votre fichier requirements.txt sans générer d'identifiants supplémentaires. Par exemple :

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

Point d'entrée de l'application

La section suivante décrit le point d'entrée par défaut pour le buildpack Python.

Point d'entrée pour les déploiements de sources Cloud Run

Cette fonctionnalité n'est disponible que si vous déployez votre code source sur Cloud Run avec le runtime Python. Cette fonctionnalité ne s'applique pas si vous créez votre image de conteneur directement à l'aide de pack build en dehors du processus de déploiement de la source Cloud Run.

Le buildpack Python est compatible avec les frameworks Web modernes tels que FastAPI, Gradio et Streamlit.

Python 3.12 et versions antérieures

Si vous utilisez Python 3.12 ou une version antérieure, le buildpack Python utilise par défaut Gunicorn comme serveur HTTP WSGI pour votre charge de travail. Le buildpack Python définit le point d'entrée par défaut sur gunicorn -b :8080 main:app.

Python 3.13 et versions ultérieures

Pour Python 3.13 et les versions ultérieures, le buildpack Python définit le point d'entrée par défaut pour les déploiements de sources Cloud Run en fonction de la configuration du serveur Web ou du framework dans votre fichier requirements.txt. Ce paramètre par défaut ne s'applique qu'aux déploiements de sources de services Cloud Run, et non aux fonctions Cloud Run.

Lorsque vous déployez un service Cloud Run à partir de la source à l'aide de l'environnement d'exécution Python, le buildpack détermine la version Python et le point d'entrée par défaut de la manière suivante :

• Si vous ne spécifiez pas de version de Python dans vos fichiers sources, le buildpack Python définit la version par défaut sur la dernière version de Python compatible. Le buildpack détermine le point d'entrée par défaut en fonction du serveur Web ou du framework que vous avez configuré dans votre fichier requirements.txt.

• Si vous ne spécifiez pas de serveur Web ni de framework dans votre fichier requirements.txt, le buildpack Python utilise par défaut Gunicorn comme serveur HTTP WSGI pour votre charge de travail. Le buildpack Python définit le point d'entrée par défaut sur gunicorn -b :8080 main:app.

• Le buildpack Python définit le point d'entrée par défaut en fonction de l'ordre de priorité suivant, tel que défini dans le fichier requirements.txt :

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

Configurer le serveur Web ou le framework

Pour chaque configuration Python courante du fichier requirements.txt, le tableau suivant indique les points d'entrée par défaut lors du déploiement sur Cloud Run à partir de la source :

Configuration principale	Point d'entrée par défaut	Variables d'environnement
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

Pour éviter les échecs de déploiement, utilisez une version Python compatible dans vos fichiers sources et spécifiez un serveur Web dans votre fichier requirements.txt.

Vous pouvez également spécifier le point d'entrée en exécutant la commande de déploiement de la source suivante :

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

Remplacez les éléments suivants :

• SERVICE : nom du service sur lequel vous souhaitez déployer.
• ENTRYPOINT : point d'entrée par défaut que vous souhaitez utiliser pour votre code source.

Si vous ne parvenez pas à déployer votre code source sur Cloud Run ou si vous trouvez des erreurs dans les journaux, consultez le guide de dépannage Cloud Run.

Point d'entrée pour tous les autres déploiements

Le buildpack Python utilise Gunicorn comme serveur HTTP WSGI par défaut pour votre charge de travail. Les applications créées avec le buildpack Python lancent le processus gunicorn avec des paramètres par défaut, semblables à ceux de l'exécution :

gunicorn --bind :8080 main:app

Personnaliser le point d'entrée de l'application

Vous pouvez personnaliser la commande de démarrage des applications à l'aide d'un Procfile ou d'une variable d'environnement. Vous devrez peut-être le faire pour personnaliser les configurations de point d'entrée par défaut.

Vous pouvez créer un fichier Procfile avec vos paramètres personnalisés dans le répertoire racine. Exemple :

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

Important : Lorsque vous remplacez les valeurs par défaut de Gunicorn, vous devez inclure gunicorn en tant que dépendance du package dans le fichier requirements.txt de votre projet.

Vous pouvez également utiliser la variable d'environnement GOOGLE_ENTRYPOINT avec la commande pack. Exemple :

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

Variables d'environnement

Le buildpack Python est compatible avec les variables d'environnement suivantes, afin de personnaliser votre conteneur :

PIP_<key>

Consultez la documentation sur pip.

Exemple : PIP_DEFAULT_TIMEOUT=60 permet de définir le paramètre --default-timeout=60 pour les commandes pip.

Déployer des applications Python avec un fichier pyproject.toml

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

Cette fonctionnalité est soumise(s) aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Les buildpacks Python sont compatibles avec les projets que vous configurez avec le fichier pyproject.toml. Cette fonctionnalité vous permet de déployer les applications que vous gérez avec Poetry, uv ou pip directement sur Cloud Run et Cloud Run Functions. Cette fonctionnalité n'est pas disponible dans App Engine.

Le buildpack Python n'utilise le fichier pyproject.toml que lorsqu'aucun fichier requirements.txt n'est présent dans votre répertoire racine. Si votre application utilise à la fois le fichier pyproject.toml et le fichier requirements.txt, le fichier requirements.txt est prioritaire.

Configurations de buildpacks compatibles

Les buildpacks Python sont compatibles avec les configurations suivantes :

• Buildpack pip : installe les dépendances directement à partir de pyproject.toml s'il détecte toutes les conditions suivantes :

  • Un fichier pyproject.toml est présent dans le répertoire racine et vous ne configurez pas d'outils de haute priorité tels qu'un fichier poetry.lock, une section [tool.poetry] ou un fichier uv.lock.

  • Vous avez défini la variable d'environnement GOOGLE_PYTHON_PACKAGE_MANAGER sur pip.

• Buildpack uv : compatible avec les projets Python que vous gérez avec uv. Ce buildpack s'active s'il détecte l'une des conditions suivantes :

  • Un fichier uv.lock et un fichier pyproject.toml sont présents dans la racine du projet.
  • Un fichier pyproject.toml est présent à la racine du projet et vous avez défini la variable d'environnement GOOGLE_PYTHON_PACKAGE_MANAGER sur uv.
  • Un fichier pyproject.toml est présent et vous n'incluez pas d'autres fichiers de verrouillage de haute priorité tels que poetry.lock, uv.lock ou des configurations telles que [tool.poetry], et vous ne définissez pas la variable d'environnement GOOGLE_PYTHON_PACKAGE_MANAGER.

• Buildpack Poetry : compatible avec les projets Python que vous gérez avec Poetry. Ce buildpack s'active s'il détecte l'une des conditions suivantes :

  • Un fichier poetry.lock et un fichier pyproject.toml sont présents à la racine du projet.
  • Un fichier pyproject.toml est présent à la racine du projet et une section [tool.poetry] est présente dans le fichier pyproject.toml.

Priorité du gestionnaire de packages

Les buildpacks Python déterminent le gestionnaire de packages par défaut en fonction de la configuration, dans l'ordre de priorité suivant :

1. La priorité la plus élevée est accordée au fichier requirements.txt. Le buildpack Python n'utilise le gestionnaire de packages par défaut pour installer les dépendances lors de l'étape de compilation que si ce fichier est présent. Si aucun fichier requirements.txt n'est présent, le processus de détection passe à l'étape suivante.

2. Le buildpack vérifie ensuite le fichier pyproject.toml pour trouver un fichier poetry.lock ou une section [tool.poetry]. Si le fichier est trouvé, le processus de compilation utilise Poetry pour installer les dépendances.

3. Si la configuration Poetry n'est pas détectée, le buildpack recherche un fichier uv.lock. Si des dépendances sont trouvées, le processus de compilation utilise uv pour les installer.

4. Si aucun fichier de verrouillage n'est présent, le buildpack vérifie si la variable d'environnement GOOGLE_PYTHON_PACKAGE_MANAGER contient une configuration pip ou uv.

5. Par défaut. Si vous ne définissez pas de variable d'environnement et que vous n'utilisez qu'un fichier pyproject.toml sans uv ni Poetry, le buildpack utilise par défaut uv pour toutes les versions Python compatibles.

Point d'entrée avec un fichier pyproject.toml

Lorsque vous déployez une application avec un fichier pyproject.toml au lieu d'un fichier requirements.txt, le buildpack Python utilise une méthode différente pour déterminer le point d'entrée. Pour savoir comment configurer un point d'entrée d'application avec un fichier requirements.txt, consultez Point d'entrée d'application.

Le pack de création recherche un point d'entrée dans l'ordre de priorité suivant :

1. Si un fichier Procfile existe dans votre répertoire racine ou si vous configurez la variable d'environnement GOOGLE_ENTRYPOINT, ces configurations remplacent toujours tout point d'entrée déterminé par les scripts pyproject.toml.

2. Le buildpack Python utilise les scripts personnalisés que vous configurez dans les sections [tool.poetry.scripts] et [project.scripts]. Si vous configurez un script qui inclut start, il s'agit de votre point d'entrée. Par exemple, poetry run start ou uv run start.

3. Si vous ne configurez pas de script start, mais que vous définissez un autre script, celui-ci devient le point d'entrée par défaut. Par exemple, poetry run mycmd ou uv run mycmd.

Contrairement aux compilations basées sur requirements.txt, le buildpack Python n'installe pas automatiquement gunicorn pour les projets pyproject.toml. Pour utiliser gunicorn ou tout autre serveur, vous devez l'ajouter explicitement aux dépendances dans votre fichier pyproject.toml.

Si vous ne configurez pas de scripts personnalisés dans le fichier pyproject.toml, les buildpacks tentent de détecter les frameworks courants, tels que gunicorn, uvicorn ou fastapi, à partir de vos dépendances pyproject.toml et déterminent un point d'entrée par défaut.