Crear una aplicación Python

Los paquetes de compilación admiten la configuración idiomática de los lenguajes a través de variables de entorno.

Especificar la versión de Python

De forma predeterminada, el paquete de compilación de Python Runtime usa la última versión estable del intérprete de Python. Si tu aplicación requiere una versión específica, puedes especificarla incluyendo un archivo .python-version en el directorio raíz de la aplicación.

3.14

Usar GOOGLE_PYTHON_VERSION

También se puede especificar la versión de Python mediante la variable de entorno GOOGLE_PYTHON_VERSION. Si se definen ambas configuraciones, el valor de GOOGLE_PYTHON_VERSION tiene prioridad sobre el archivo .python-version. De forma predeterminada, si no se especifican el archivo .python-version ni la variable de entorno GOOGLE_PYTHON_VERSION, se usa la versión LTS más reciente de Python.

Para configurar el paquete de compilación para que use Python 3.13 al implementar tu aplicación, sigue estos pasos:

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

También puedes usar un descriptor de proyecto project.toml para codificar la variable de entorno junto con los archivos de tu proyecto. Consulta las instrucciones para compilar la aplicación con variables de entorno.

Especificar dependencias

Especifica las dependencias de tu aplicación para las versiones de Python compatibles con cualquiera de los siguientes métodos:

• Usa un archivo requirements.txt en el directorio raíz. Este archivo debe estar en el mismo directorio que el archivo main.py que contiene el código fuente. El archivo requirements.txt contiene una línea por paquete. Cada línea contiene el nombre del paquete y, opcionalmente, la versión solicitada. Para evitar que la compilación se vea afectada por los cambios en la versión de las dependencias, te recomendamos que fijes los paquetes de dependencias a una versión específica.

  A continuación, se muestra un ejemplo de archivo requirements.txt:

  functions-framework
  requests==2.20.0
  numpy
  

• Usa un archivo pyproject.toml para especificar las dependencias. Si gestionas las dependencias de tu aplicación en un archivo pyproject.toml en lugar de en el archivo requirements.txt, el paquete de compilación de Python determinará el gestor de paquetes en función de la configuración que especifiques en el archivo pyproject.toml. Para obtener más información, consulta el artículo Desplegar aplicaciones Python con un archivo pyproject.toml.

  Si tu aplicación usa tanto el archivo pyproject.toml como el archivo requirements.txt, este último tiene prioridad.requirements.txt

  • A continuación, se muestra un ejemplo de archivo 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"
    

Gestor de paquetes

Si gestionas tus dependencias con un requirements.txt file, el gestor de paquetes predeterminado varía en función de la versión de Python que configures.

Si usas un archivo pyproject.toml para gestionar las dependencias en lugar de un archivo requirements.txt, el paquete de compilación de Python determinará el gestor de paquetes en función de los ajustes de configuración del archivo pyproject.toml. El buildpack es compatible con los gestores de paquetes pip, uv y Poetry. Para obtener más información, consulta Implementar aplicaciones de Python con un archivo pyproject.toml.

Python 3.14 y versiones posteriores

A partir de la versión 3.14 (vista previa) de Python, el paquete de compilación de Python usa el gestor de paquetes uv como instalador predeterminado de las dependencias que especifiques en el archivo requirements.txt.

Para usar pip como gestor de paquetes, configura la variable de entorno GOOGLE_PYTHON_PACKAGE_MANAGER="pip".

Python 3.13 y versiones anteriores

En las versiones de Python 3.13 y anteriores, el paquete de compilación de Python usa el administrador de paquetes pip para instalar las dependencias que definas en el archivo requirements.txt.

Para usar uv (vista previa) como gestor de paquetes, configura la variable de entorno GOOGLE_PYTHON_PACKAGE_MANAGER="uv".

Configurar la función Imagen en imagen

Es posible configurar el comportamiento de pip mediante variables de entorno:

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

Dependencias privadas de Artifact Registry

Un repositorio de Python de Artifact Registry puede alojar dependencias privadas de tu función de Python. Al compilar una aplicación en Cloud Build, el paquete de compilación de Python generará automáticamente credenciales de Artifact Registry para la cuenta de servicio de Cloud Build. Solo tiene que incluir la URL de Artifact Registry en su requirements.txt sin generar credenciales adicionales. Por ejemplo:

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

Punto de entrada de la aplicación

En la siguiente sección se describe el punto de entrada predeterminado del paquete de compilación de Python.

Punto de entrada para los despliegues de origen de Cloud Run

Esta función solo está disponible si despliegas tu código fuente en Cloud Run con el tiempo de ejecución de Python. Esta función no se aplica si compilas tu imagen de contenedor directamente con pack build fuera del proceso de despliegue de origen de Cloud Run.

El paquete de compilación de Python es compatible con frameworks web modernos, como FastAPI, Gradio y Streamlit.

Versión 3.12 de Python y anteriores

Si usas la versión 3.12 o una anterior de Python, el paquete de compilación de Python usará Gunicorn de forma predeterminada como servidor HTTP WSGI para tu carga de trabajo. El paquete de compilación de Python define el punto de entrada predeterminado como gunicorn -b :8080 main:app.

Python 3.13 y versiones posteriores

En Python 3.13 y versiones posteriores, el paquete de compilación de Python define el punto de entrada predeterminado para los despliegues de origen de Cloud Run en función de la configuración del servidor web o del framework en el archivo requirements.txt. Este ajuste predeterminado solo se aplica a los despliegues de origen de servicios de Cloud Run, no a las funciones de Cloud Run.

Cuando despliegas un servicio de Cloud Run desde una fuente con el tiempo de ejecución de Python, el buildpack determina la versión de Python y el punto de entrada predeterminado de las siguientes formas:

• Si no especificas una versión de Python en tus archivos de origen, el paquete de compilación de Python definirá de forma predeterminada la versión de Python más reciente compatible. El buildpack determina el punto de entrada predeterminado en función del servidor web o del framework que hayas configurado en tu archivo requirements.txt.

• Si no especifica un servidor web o un framework en el archivo requirements.txt, el paquete de compilación de Python usará Gunicorn de forma predeterminada como servidor HTTP WSGI para su carga de trabajo. El paquete de compilación de Python define el punto de entrada predeterminado como gunicorn -b :8080 main:app.

• El paquete de compilación de Python define el punto de entrada predeterminado según el siguiente orden de precedencia, tal como se define en el archivo requirements.txt:

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

Configurar el servidor web o el framework

En la siguiente tabla se muestran los puntos de entrada predeterminados de cada configuración común de Python en el archivo requirements.txt al implementar en Cloud Run desde el código fuente:

Configuración principal	Punto de entrada predeterminado	Variables de entorno
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

Para evitar errores de implementación, usa una versión de Python compatible en tus archivos de origen y especifica un servidor web en el archivo requirements.txt.

También puede especificar el punto de entrada ejecutando el siguiente comando de implementación de origen:

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

Haz los cambios siguientes:

• SERVICE: el nombre del servicio en el que quieras implementar la aplicación.
• ENTRYPOINT: el punto de entrada predeterminado que quieras usar para tu código fuente.

Si no puedes desplegar tu código fuente en Cloud Run o encuentras errores en los registros, consulta la guía de solución de problemas de Cloud Run.

Punto de entrada para el resto de las implementaciones

El paquete de compilación de Python usa Gunicorn como servidor HTTP WSGI predeterminado para tu carga de trabajo. Las aplicaciones creadas con el paquete de compilación de Python inician el proceso gunicorn con la configuración predeterminada, de forma similar a la siguiente:

gunicorn --bind :8080 main:app

Personalizar el punto de entrada de la aplicación

Puedes personalizar el comando de inicio de las aplicaciones mediante una Procfile o una variable de entorno. Es posible que tengas que hacerlo para personalizar las configuraciones de punto de entrada predeterminadas.

Puedes crear un Procfile con tus ajustes personalizados en el directorio raíz. Ejemplo:

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

Importante: Cuando anules los valores predeterminados de Gunicorn, debes incluir gunicorn como dependencia de paquete en el archivo requirements.txt de tu proyecto.

También puedes usar la variable de entorno GOOGLE_ENTRYPOINT con el comando pack. Ejemplo:

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

Variables de entorno

El paquete de compilación de Python admite las siguientes variables de entorno para personalizar tu contenedor:

PIP_<key>

Consulta la documentación de pip.

Ejemplo: PIP_DEFAULT_TIMEOUT=60 define --default-timeout=60 para los comandos pip.

Desplegar aplicaciones Python con un archivo pyproject.toml

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

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

Los buildpacks de Python admiten proyectos que configures con el archivo pyproject.toml. Esta función te permite desplegar aplicaciones que gestionas con Poetry, uv o pip directamente en Cloud Run y Cloud Run Functions. Esta función no está disponible en App Engine.

El paquete de compilación de Python solo usa el archivo pyproject.toml cuando no hay ningún archivo requirements.txt en el directorio raíz. Si tu aplicación usa tanto el archivo pyproject.toml como el archivo requirements.txt, este último tiene prioridad.requirements.txt

Configuraciones de buildpacks admitidas

Los buildpacks de Python admiten las siguientes configuraciones:

• Buildpack de pip: instala las dependencias directamente desde pyproject.toml si detecta que se cumplen todas las condiciones siguientes:

  • Hay un archivo pyproject.toml en el directorio raíz y no has configurado herramientas de alta prioridad, como un archivo poetry.lock, una sección [tool.poetry] o un archivo uv.lock.

  • Has definido la variable de entorno GOOGLE_PYTHON_PACKAGE_MANAGER como pip.

• Paquete de compilación uv: admite proyectos de Python que gestionas con uv. Este paquete de compilación se activa si detecta alguna de las siguientes condiciones:

  • Hay un archivo uv.lock y un archivo pyproject.toml en la raíz del proyecto.
  • Hay un archivo pyproject.toml en la raíz del proyecto y has asignado el valor uv a la variable de entorno GOOGLE_PYTHON_PACKAGE_MANAGER.
  • Hay un archivo pyproject.toml y no incluyes otros archivos de bloqueo de alta precedencia, como poetry.lock o uv.lock, ni configuraciones como [tool.poetry], y no defines la variable de entorno GOOGLE_PYTHON_PACKAGE_MANAGER.

• Buildpack de Poetry: admite proyectos de Python que gestionas con Poetry. Este buildpack se activa si detecta alguna de las siguientes condiciones:

  • En la raíz del proyecto hay un archivo poetry.lock y un archivo pyproject.toml.
  • Hay un archivo pyproject.toml en la raíz del proyecto y una sección [tool.poetry] en el archivo pyproject.toml.

Precedencia del gestor de paquetes

Los buildpacks de Python determinan el gestor de paquetes predeterminado en función de la configuración, según el siguiente orden de prioridad:

1. Se da la máxima prioridad al archivo requirements.txt. Solo si este archivo está presente, el paquete de compilación de Python usará el gestor de paquetes predeterminado para instalar las dependencias en el paso de compilación. Si no hay ningún archivo requirements.txt, el proceso de detección pasa al siguiente paso.

2. A continuación, el paquete de compilación comprueba el archivo pyproject.toml para ver si hay un archivo poetry.lock o una sección [tool.poetry]. Si se encuentra, el proceso de compilación continúa usando Poetry para instalar las dependencias.

3. Si no se detecta la configuración de Poetry, el paquete de compilación busca un archivo uv.lock. Si se encuentra, el proceso de compilación continúa usando uv para instalar las dependencias.

4. Si no hay archivos de bloqueo, el paquete de compilación comprueba la variable de entorno GOOGLE_PYTHON_PACKAGE_MANAGER para ver si hay una configuración pip o uv.

5. Predeterminado. Si no defines una variable de entorno y solo usas un archivo pyproject.toml sin uv ni Poetry, el paquete de compilación usará de forma predeterminada uv para todas las versiones de Python compatibles.

Punto de entrada con un archivo pyproject.toml

Cuando implementas una aplicación con un archivo pyproject.toml en lugar de usar un archivo requirements.txt, el paquete de compilación de Python usa un método diferente para determinar el punto de entrada. Para obtener información sobre cómo configurar un punto de entrada de aplicación con un archivo requirements.txt, consulta Punto de entrada de aplicación.

El paquete de compilación busca un punto de entrada en el siguiente orden de prioridad:

1. Si hay un archivo Procfile en tu directorio raíz o configuras la variable de entorno GOOGLE_ENTRYPOINT, estas configuraciones siempre anularán cualquier punto de entrada determinado por las secuencias de comandos pyproject.toml.

2. El paquete de compilación de Python utiliza las secuencias de comandos personalizadas que configures en las secciones [tool.poetry.scripts] y [project.scripts]. Si configuras una secuencia de comandos que incluye start, este es tu punto de entrada. Por ejemplo, poetry run start o uv run start.

3. Si no configuras una secuencia de comandos start, pero defines otra, esta será el punto de entrada predeterminado. Por ejemplo, poetry run mycmd o uv run mycmd.

A diferencia de las compilaciones basadas en requirements.txt, el paquete de compilación de Python no instala gunicorn automáticamente para los proyectos de pyproject.toml. Para usar gunicorn o cualquier otro servidor, debes añadirlo explícitamente a las dependencias de tu archivo pyproject.toml.

Si no configuras scripts personalizados en el archivo pyproject.toml, los buildpacks intentarán detectar frameworks comunes, como gunicorn, uvicorn o fastapi, a partir de las dependencias de pyproject.toml y determinarán un punto de entrada predeterminado.