Compila una aplicación de Python

Los paquetes de compilación admiten la configuración de lenguaje idiomático a través de variables de entorno.

Especifica la versión de Python

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

3.14

Utilizar GOOGLE_PYTHON_VERSION

También es posible especificar la versión de Python con la variable de entorno GOOGLE_PYTHON_VERSION. Si ambas configuraciones se establecen, el valor GOOGLE_PYTHON_VERSION tiene prioridad sobre la propiedad .python-version. De forma predeterminada, cuando no se especifican el archivo .python-version y la variable de entorno GOOGLE_PYTHON_VERSION, se usa la última versión de LTS de Python.

Para configurar el paquete de compilación para que use Python 3.13 cuando implementes tu app, haz lo siguiente:

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

También puedes usar un descriptor de proyectos 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.

Especifica las dependencias

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

• 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 tu código fuente. El archivo requirements.txt contiene una línea por paquete. Cada línea contiene el nombre del paquete y, de manera opcional, la versión solicitada. Para evitar que la compilación se vea afectada por los cambios en la versión de la dependencia, considera fijar los paquetes de dependencias a una versión específica.

  El siguiente es un archivo requirements.txt de ejemplo:

  functions-framework
  requests==2.20.0
  numpy
  

• Usa un archivo pyproject.toml para especificar dependencias. Si administras las dependencias de tu aplicación en un archivo pyproject.toml en lugar del archivo requirements.txt, el paquete de compilación de Python determinará el administrador de paquetes según la configuración que especifiques en el archivo pyproject.toml. Para obtener más información, consulta Implementa aplicaciones de Python con un archivo pyproject.toml.

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

  • El siguiente es un archivo pyproject.toml de ejemplo:

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

Administrador de paquetes

Si administras tus dependencias con un requirements.txt file, el administrador de paquetes predeterminado varía según la versión de Python que configures.

Si usas un archivo pyproject.toml para administrar las dependencias en lugar de un archivo requirements.txt, el buildpack de Python determinará el administrador de paquetes según la configuración del archivo pyproject.toml. El paquete de compilación admite los administradores de paquetes pip, uv y Poetry. Para obtener más información, consulta Implementa aplicaciones de Python con un archivo pyproject.toml.

Python 3.14 y versiones posteriores

A partir de la versión 3.14 de Python (versión preliminar) y versiones posteriores, el paquete de compilación de Python usa el administrador de paquetes uv como instalador predeterminado para las dependencias que especifiques en tu archivo requirements.txt.

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

Python 3.13 y versiones anteriores

Para la versión 3.13 y las anteriores de Python, 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 (versión preliminar) como administrador de paquetes, configura la variable de entorno GOOGLE_PYTHON_PACKAGE_MANAGER="uv".

Configura pip

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 para tu función de Python. Cuando compilas una aplicación en Cloud Build, el paquete de compilación de Python generará de forma automática las credenciales de Artifact Registry para la cuenta de servicio de Cloud Build. Solo debes incluir la URL de Artifact Registry en la 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 para el paquete de compilación de Python.

Punto de entrada para las implementaciones de origen de Cloud Run

Esta función solo está disponible si implementas tu código fuente en Cloud Run con el entorno 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 implementación de la fuente de Cloud Run.

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

Versión 3.12 de Python y versiones anteriores

Si usas la versión 3.12 y versiones anteriores de Python, el paquete de compilación de Python usa Gunicorn de forma predeterminada como el servidor HTTP WSGI para tu carga de trabajo. El paquete de compilación de Python establece el punto de entrada predeterminado en gunicorn -b :8080 main:app.

Python 3.13 y versiones posteriores

Para Python 3.13 y versiones posteriores, el paquete de compilación de Python establece el punto de entrada predeterminado para las implementaciones de origen de Cloud Run según la configuración del servidor web o del framework en tu archivo requirements.txt. Este parámetro de configuración predeterminado solo se aplica a las implementaciones de código fuente de servicios de Cloud Run, no a las funciones de Cloud Run.

Cuando implementas un servicio de Cloud Run desde la fuente con el entorno de ejecución de Python, el paquete de compilación determina la versión de Python y el punto de entrada predeterminado de las siguientes maneras:

• Si no especificas una versión de Python en tus archivos fuente, el buildpack de Python establece la versión de Python compatible más reciente como la predeterminada. El paquete de compilación determina el punto de entrada predeterminado según el servidor web o el framework que configuraste en tu archivo requirements.txt.

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

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

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

Configura el servidor web o el framework

En la siguiente tabla, se muestran los puntos de entrada predeterminados para cada configuración común de Python en el archivo requirements.txt cuando se realiza la implementación en Cloud Run desde la 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 fuente y especifica un servidor web en tu archivo requirements.txt.

Como alternativa, también puedes especificar el punto de entrada ejecutando el siguiente comando de implementación de código fuente:

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

Reemplaza lo siguiente:

• SERVICE: Es el nombre del servicio en el que deseas realizar la implementación.
• ENTRYPOINT: Es el punto de entrada predeterminado que deseas usar para tu código fuente.

Si no puedes implementar 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 todas las demás implementaciones

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

gunicorn --bind :8080 main:app

Personaliza el punto de entrada de la aplicación

Puedes personalizar el comando de inicio de las aplicaciones con un Procfile o una variable de entorno. Es posible que debas hacerlo para personalizar la configuración predeterminada del punto de entrada.

Puedes crear un Procfile con tu configuración personalizada en el directorio raíz. Ejemplo:

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

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

Como alternativa, 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 configura --default-timeout=60 para los comandos pip.

Implementa aplicaciones de Python con un archivo pyproject.toml

Versión preliminar — Deploy Python applications to Cloud Run and Cloud Run functions with a pyproject.toml file

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Los buildpacks de Python admiten proyectos que configuras con el archivo pyproject.toml. Esta función te permite implementar aplicaciones que administras 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 usa el archivo pyproject.toml solo cuando no hay un archivo requirements.txt presente en tu directorio raíz. Si tu aplicación usa el archivo pyproject.toml y el archivo requirements.txt, el archivo requirements.txt tiene prioridad.

Configuraciones de buildpacks compatibles

Los paquetes de compilación de Python admiten los siguientes parámetros de configuración:

• buildpack de pip: Instala dependencias directamente desde pyproject.toml si detecta todas las siguientes condiciones:

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

  • Estableciste la variable de entorno GOOGLE_PYTHON_PACKAGE_MANAGER en pip.

• Paquete de compilación de uv: Admite proyectos de Python que administras con uv. Este buildpack se activa si detecta alguna de las siguientes condiciones:

  • En la raíz del proyecto, hay un archivo uv.lock y un archivo pyproject.toml.
  • Hay un archivo pyproject.toml en la raíz del proyecto y estableciste la variable de entorno GOOGLE_PYTHON_PACKAGE_MANAGER en uv.
  • Hay un archivo pyproject.toml presente y no incluyes otros archivos de bloqueo de alta prioridad, como poetry.lock, uv.lock o configuraciones como [tool.poetry], y no estableces la variable de entorno GOOGLE_PYTHON_PACKAGE_MANAGER.

• Paquete de compilación de Poetry: Admite proyectos de Python que administras con Poetry. Este buildpack se activa si detecta alguna de las siguientes condiciones:

  • En la raíz del proyecto, se encuentran 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 administrador de paquetes

Los paquetes de compilación de Python determinan el administrador de paquetes predeterminado según la configuración en el siguiente orden de prioridad:

1. Se le otorga la mayor precedencia al archivo requirements.txt. Solo si este archivo está presente, el paquete de compilación de Python usa el administrador de paquetes predeterminado para instalar dependencias en el paso de compilación. Si no hay un archivo requirements.txt, el proceso de detección continúa con el siguiente paso.

2. Luego, el buildpack verifica si el archivo pyproject.toml contiene 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 buildpack busca un archivo uv.lock. Si se encuentra, el proceso de compilación continúa usando uv para instalar dependencias.

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

5. Predeterminado. Si no configuras una variable de entorno y solo usas un archivo pyproject.toml sin uv ni Poetry, el paquete de compilación usará uv de forma predeterminada 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 la aplicación con un archivo requirements.txt, consulta Punto de entrada de la aplicación.

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

1. Si existe un Procfile en tu directorio raíz o configuras la variable de entorno GOOGLE_ENTRYPOINT, estas configuraciones siempre anulan 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 configuras en las secciones [tool.poetry.scripts] y [project.scripts]. Si configuras un script que incluye start, este será 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, la secuencia de comandos que definas 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 agregarlo explícitamente a las dependencias en tu archivo pyproject.toml.

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