Build a Python application

Buildpacks support language-idiomatic configuration through environment variables.

Specify the Python version

By default the Python Runtime buildpack uses the latest stable version of the Python interpreter. If your application requires a specific version, you can specify one by including a .python-version file in your application's root directory.

3.13

Use GOOGLE_PYTHON_VERSION

It is also possible to specify the Python version via the GOOGLE_PYTHON_VERSION environment variable. If both configurations are set, the GOOGLE_PYTHON_VERSION value takes precedence over the .python-version file. By default, when both the .python-version file and GOOGLE_PYTHON_VERSION environment variable are not specified, then the latest LTS version of Python is used.

To configure the buildpack to use Python 3.13 when deploying your app:

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

You can also use a project.toml project descriptor to encode the environment variable alongside your project files. See instructions on building the application with environment variables.

Specify dependencies with pip

The Python buildpack supports managing application dependencies using pip. Your application dependencies should be declared in a requirements.txt file the root directory.

The requirements.txt file contains one line per package. Each line contains the package name, and optionally, the requested version. For more details, see the requirements.txt reference.

The following is an example requirements.txt file:

requests==2.20.0
numpy

Configure pip

It is possible to configure the behavior of pip using environment variables:

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

Private dependencies from Artifact Registry

An Artifact Registry Python repository can host private dependencies for your Python function. When building an application on Cloud Build, the Python buildpack will automatically generate Artifact Registry credentials for the Cloud Build service account. You only need to include the Artifact Registry URL in your requirements.txt without generating additional credentials. For example:

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

Application entrypoint

The following section describes the default entrypoint for the Python buildpack.

Entrypoint for Cloud Run source deploys

This feature is only available if you deploy your source code to Cloud Run with the Python runtime. This feature isn't applicable if you are building your container image directly using pack build outside of the Cloud Run source deploy process.

The Python buildpack supports modern web frameworks such as FastAPI, Gradio, and Streamlit.

Python version 3.12 and earlier

If you're using Python version 3.12 and earlier, the Python buildpack defaults to using Gunicorn as the WSGI HTTP server for your workload. The Python buildpack sets the default entrypoint to gunicorn -b :8080 main:app.

Python version 3.13 and later

For Python version 3.13 and later, the Python buildpack sets the default entrypoint for Cloud Run source deploys based on the web server or framework configuration in your requirements.txt file. This default setting applies only to Cloud Run service source deployments, not to Cloud Run functions.

When you deploy a Cloud Run service from source using the Python runtime, the buildpack determines the Python version and the default entrypoint in the following ways:

• If you don't specify a Python version in your source files, the Python buildpack sets the default to the latest supported Python version. The buildpack determines the default entrypoint based on the web server or framework you've configured in your requirements.txt file.

• If you don't specify a web server or a framework in your requirements.txt file, the Python buildpack defaults to using Gunicorn as the WSGI HTTP server for your workload. The Python buildpack sets the default entrypoint to gunicorn -b :8080 main:app.

• The Python buildpack sets the default entrypoint based on the following order of precedence, as defined in the requirements.txt file:

  1. gunicorn
  2. uvicorn
  3. gradio
  4. streamlit.

Configure the web server or framework

For each common Python configurations in the requirements.txt file, the following table shows the default entrypoints when deploying to Cloud Run from source:

Primary configuration	Default entrypoint	Environment variables
gunicorn	gunicorn -b :8080 main:app
numpy	gunicorn -b :8080 main:app
fastapi uvicorn	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

To avoid deployment failures, use a supported Python version in your source files, and specify a web server in your requirements.txt file.

Alternatively, you can also specify the entrypoint by running the following source deploy command:

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

Replace the following:

• SERVICE: the name of the service you want to deploy to.
• ENTRYPOINT: the default entrypoint you want to use for your source code.

If you're unable to deploy your source code to Cloud Run or find errors in the logs, see the Cloud Run troubleshooting guide.

Entrypoint for all other deployments

The Python buildpack uses Gunicorn as the default WSGI HTTP server for your workload. Apps built with the Python buildpack start the gunicorn process with default settings, similar to running:

gunicorn --bind :8080 main:app

Customize the application entrypoint

You can customize the applications start command by using a Procfile or an environment variable. You might need to do this to customize the default entrypoint configurations.

You can create a Procfile with your custom settings in the root directory. Example:

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

Important: When you override the Gunicorn defaults, you must include gunicorn as a package dependency in your project's requirements.txt file.

Alternatively, you can use the GOOGLE_ENTRYPOINT environment variable with the pack command. Example:

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

Environment Variables

The Python buildpack supports the following environment variables to customize your container

PIP_<key>

See pip documentation.

Example: PIP_DEFAULT_TIMEOUT=60 sets --default-timeout=60 for pip commands.