Buildpacks support language-idiomatic configuration through environmentvariables.

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

UseGOOGLE_PYTHON_VERSION

It is also possible to specify the Python version using theGOOGLE_PYTHON_VERSION environment variable.If both configurations are set, theGOOGLE_PYTHON_VERSION value takesprecedence over the.python-version file. By default, when both the.python-version file andGOOGLE_PYTHON_VERSION environment variable are notspecified, 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.14.x"

You can also use aproject.toml project descriptor to encodethe environment variable alongside your project files. See instructions onbuilding the application with environment variables.

Specify dependencies

Specify your application dependencies forsupported Python versions using any of the following approaches:

• Use arequirements.txt file in the root directory. This file must be inthe same directory as themain.py file that contains your source code. Therequirements.txt file contains one line per package. Each line containsthe package name, and optionally, the requested version. To prevent yourbuild from being affected by dependency version changes, consider pinningyour dependency packages to a specific version.

  The following is an examplerequirements.txt file:

  functions-frameworkrequests==2.20.0numpy

• Use apyproject.toml file to specify dependencies. If you manage yourapplication dependencies in apyproject.toml file instead of therequirements.txt file, the Python buildpack determinesthe package manager based on the configuration you specify in thepyproject.toml file. For more information, seeDeploy Python applicationswith apyproject.toml file.

  If your application uses both thepyproject.toml file and therequirements.txt file, therequirements.txt file takes precedence.

  • The following is an examplepyproject.toml file:

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

Package manager

If you manage your dependencies using arequirements.txt file, the default packagemanager varies based on the Python version you configure.

If you use apyproject.toml file to manage dependencies instead of arequirements.txt file, the Python buildpack determines thepackage manager based on your configuration settings in thepyproject.tomlfile. The buildpack supports pip, uv and Poetry packagemanagers. For more information, seeDeploy Python applications with apyproject.toml file.

Configure pip

It is possible to configure the behavior of pipusing environment variables:

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

Private dependencies from Artifact Registry

AnArtifact Registry Python repositorycan host private dependencies for your Python function. When building an application onCloud Build, the Python buildpack will automatically generate Artifact Registrycredentials for theCloud Build service account.You only need to include the Artifact Registry URL in yourrequirements.txtwithout generating additional credentials. For example:

--extra-index-urlREPOSITORY_URLsampleappFlask==0.10.1google-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 youdeploy your source code to Cloud Run with the Python runtime. This featureisn't applicable if you are building your container image directly usingpack build outside of the Cloud Run source deploy process.

ThePython buildpack supportsmodern web frameworks such asFastAPI,Gradio, andStreamlit.

Python version 3.12 and earlier

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

Python version 3.13 and later

For Python version 3.13 and later, the Python buildpacksets the default entrypoint forCloud Run source deploys based on the web server or framework configuration in yourrequirements.txt file. This default setting applies only to Cloud Runservice 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 defaultentrypoint in the following ways:

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

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

• The Python buildpack sets the default entrypointbased on the following order of precedence, as defined in therequirements.txtfile:

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

Configure the web server or framework

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

To avoid deployment failures, use asupported Pythonversion in your source files, andspecify a web server in yourrequirements.txt file.

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

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

Replace the following:

• SERVICE: the name of the service you want todeploy to.
• ENTRYPOINT: the default entrypoint you want to use for your sourcecode.

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

Entrypoint for all other deployments

The Python buildpack usesGunicornas the default WSGI HTTP server for your workload. Apps built with the Pythonbuildpack start thegunicorn 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 aProcfile or an environment variable. You might need to do this to customize thedefault entrypoint configurations.

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

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

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

See pipdocumentation.

Example:PIP_DEFAULT_TIMEOUT=60 sets--default-timeout=60 forpip commands.

Deploy Python applications with apyproject.toml file

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Python buildpacks support projects you configurewith thepyproject.toml file. This feature lets you deployapplications you manage with Poetry, uv, or pip, directly to Cloud Runand Cloud Run functions. This feature isn't available in App Engine.

The Python buildpack uses thepyproject.toml file onlywhen there isn't arequirements.txt file present in your root directory. If your application uses boththepyproject.toml file and therequirements.txt file, then therequirements.txt filetakes precedence.

Supported buildpacks configurations

Python buildpacks supports the following configurations:

• pip buildpack: Installs dependencies directly frompyproject.toml if it detects all the following conditions:

  • Apyproject.toml file is present in the root directory and you don'tconfigure high-precedence tools such as apoetry.lock file, a[tool.poetry]section, or auv.lock file.

  • You set theGOOGLE_PYTHON_PACKAGE_MANAGER environment variable topip.

• uv buildpack: Supports Python projects you manage withuv. This buildpack activates if it detects anyof the following conditions:

  • Auv.lock file and apyproject.toml file are present in the projectroot.
  • Apyproject.toml file is present in the project root, and you set theGOOGLE_PYTHON_PACKAGE_MANAGER environment variable touv.
  • Apyproject.toml file is present and you don't include other high-precedencelock files such aspoetry.lock,uv.lock, or configurations such as[tool.poetry], and you don't set theGOOGLE_PYTHON_PACKAGE_MANAGER environment variable.

• Poetry buildpack: Supports Python projects you managewithPoetry. Thisbuildpack activates if it detects any of the followingconditions:

  • Apoetry.lock file and apyproject.toml file are present in theproject root.
  • Apyproject.toml file is present in the project root and a[tool.poetry] section is present in thepyproject.toml file.

Package manager precedence

The Python buildpacks determines the default package manager based on theconfiguration in the following order of precedence:

1. The highest precedence is given to therequirements.txt file. Only if thisfile is present, the Python buildpack uses thedefault packagemanager to install dependencies at the build step. Ifarequirements.txt file isn't present, the detection process moves on to the next step.

2. The buildpack then checks thepyproject.toml file forapoetry.lock file or a[tool.poetry] section. If found, the build process proceeds to usePoetry to install dependencies.

3. If Poetry configuration isn't detected, the buildpack checks for auv.lock file. If found, the build process proceeds to use uv to install dependencies.

4. If lock files aren't present, the buildpack checks theGOOGLE_PYTHON_PACKAGE_MANAGER environment variable for apip oruvconfiguration.

5. Default. If you don't set an environment variable, and use only apyproject.tomlfile without uv or Poetry, the buildpack defaults to usinguv for allsupported Python versions.

Entrypoint with apyproject.toml file

When you deploy an application with apyproject.toml file instead of using arequirements.txt file, the Python buildpack uses a differentmethod to determine the entrypoint. For information about configuring anapplication entrypoint with arequirements.txt file, seeApplication entrypoint.

The buildpack searches for an entrypoint in the following order of precedence:

1. If aProcfile exists in your root directory, or you configure theGOOGLE_ENTRYPOINT environment variable, these configurations alwaysoverride any entrypoint determined bypyproject.toml scripts.

2. The Python buildpack utilizes the custom scripts you configure inthe[tool.poetry.scripts] and the[project.scripts] sections. If you configure ascript that includesstart, this is your entrypoint.For example,poetry run start oruv run start.

3. If you don't configure astart script, but you define another script,the script you define is the default entrypoint. For example,poetry run mycmdoruv run mycmd.

Unlikerequirements.txt-based builds, the Python buildpackdoesn't automatically installgunicorn forpyproject.toml projects. To usegunicorn or any other server, you must explicitly add it to the dependencies in yourpyproject.toml file.

If you don't configurecustomscripts in thepyproject.toml file, the buildpacks attemptsto detect common frameworks, such asgunicorn,uvicorn orfastapi from yourpyproject.toml dependencies anddetermines a default entrypoint.