Notice: Over the next few months, we're reorganizing the App Engine documentation site to make it easier to find content and better align with the rest of Google Cloud products. The same content will be available, but the navigation will now match the rest of the Cloud products.

Python 3.10 is now generally available.

Python 3 Runtime Environment

The Python 3 runtime is the software stack responsible for installing your web service's code and its dependencies and running your service.

The Python 3 runtime for App Engine in the standard environment is declared in the app.yaml file:

Python 3.10

runtime: python310

Python 3.9

runtime: python39

Python 3.8

runtime: python38

Python 3.7

runtime: python37

Python 3 versions

The Python 3 runtime supports Python 3.7, Python 3.8, Python 3.9, and Python 3.10 and uses the latest stable release of the version that is specified in your app.yaml file. App Engine automatically updates to new patch release versions, but it will not automatically update the minor version.

For example, your application might be deployed at Python 3.7.0 and later automatically updated to Python 3.7.1, but it will not be automatically updated to the next minor version Python 3.8.0.

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how App Engine performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Try App Engine free

The runtime's environment

App Engine runs Python 3 apps in a container secured by gVisor on an up-to-date Ubuntu Linux distribution.

  • Python 3.7, 3.8, and 3.9 run on Ubuntu 18.04
  • Python 3.10 runs on Ubuntu 22.04

Dependencies

During deployment, App Engine uses the Python package manager pip to install dependencies defined in the requirements.txt metadata file located in your project's root directory. You do not need to upload dependencies as App Engine performs a fresh install.

Dependency specification using the Pipfile/Pipfile.lock standard is currently not supported and your project must not have these files present.

Application startup

The runtime starts your app by running the command you specify in the entrypoint field in your app.yaml file. The entrypoint should start a web server that listens on the port specified by the PORT environment variable. For example:

entrypoint: gunicorn -b :$PORT main:app

The web framework that your app uses is responsible for routing requests to the appropriate handlers in your app.

If your app meets the following requirements, App Engine will start your app with the gunicorn web server if you don't specify the entrypoint field:

  • The root of your app directory contains a main.py file with a WSGI-compatible object called app.

  • Your app does not contain Pipfile or Pipfile.lock files.

App Engine will also automatically add the gunicorn to your requirements.txt file if you don't specify the entrypoint field.

Entrypoint best practices

  • Do not include gunicorn in your requirements.txt file unless you are specifying the entrypoint.

  • For the best performance, the entrypoint should be lightweight because it runs whenever a new instance of your application is created.

  • You can use the entrypoint field to tune the performance of your app. For example, if you use gunicorn as your web server, you can use the --workers flag in the entrypoint field to configure the number of workers serving your app.

    The number of workers you specify should match the instance class of your App Engine app:

    Instance class Workers
    F1 2
    F2 4
    F4 8
    F4_1G 8
    B1 2
    B2 4
    B4 8
    B4_1G 8
    B8 8

    This guidance serves as a starting point for selecting the number of workers. You may need to use a different number of workers depending on your app's performance characteristics. The example below shows an App Engine deployment that uses two gunicorn workers for serving apps:

    entrypoint: gunicorn -b :$PORT -w 2 main:app

  • We recommend that you configure your web server to listen and respond to HTTP requests on the port specified by your $PORT environment variable. Using the default port 8080 prevents App Engine from using its NGINX layer to compress HTTP responses. Note that if you use port 8080, warnings about port 8080 and NGINX will show in your app's log files.

Other web frameworks

In addition to Django and Flask, you can use other web frameworks with App Engine, such as uwsgi and Tornado. The following example shows how to use uwsgi with App Engine:

appengine/standard_python3/custom-server/app.yaml 
runtime: python39
entrypoint: uwsgi --http-socket :$PORT --wsgi-file main.py --callable app --master --processes 1 --threads 2
appengine/standard_python3/custom-server/requirements.txt 
uwsgi==2.0.20
flask==2.1.0

Environment variables

The following environment variables are set by the runtime:

Environment variable Description
GAE_APPLICATION The ID of your App Engine application. This ID is prefixed with 'region code~' such as 'e~' for applications deployed in Europe.
GAE_DEPLOYMENT_ID The ID of the current deployment.
GAE_ENV The App Engine environment. Set to standard.
GAE_INSTANCE The ID of the instance on which your service is currently running.
GAE_MEMORY_MB The amount of memory available to the application process, in MB.
GAE_RUNTIME The runtime specified in your app.yaml file.
GAE_SERVICE The service name specified in your app.yaml file. If no service name is specified, it is set to default.
GAE_VERSION The current version label of your service.
GOOGLE_CLOUD_PROJECT The Cloud project ID associated with your application.
PORT The port that receives HTTP requests.

You can define additional environment variables in your app.yaml file, but the above values cannot be overridden.

HTTPS and forwarding proxies

App Engine terminates HTTPS connections at the load balancer and forwards requests to your application. Some applications need to determine the original request IP and protocol. The user's IP address is available in the standard X-Forwarded-For header. Applications that require this information should configure their web framework to trust the proxy.

Filesystem

The runtime includes a full filesystem. The filesystem is read-only except for the location /tmp, which is a virtual disk storing data in your App Engine instance's RAM.

Metadata server

Each instance of your application can use the App Engine metadata server to query information about the instance and your project.

You can access the metadata server through the following endpoints:

  • http://metadata
  • http://metadata.google.internal

Requests sent to the metadata server must include the request header Metadata-Flavor: Google. This header indicates that the request was sent with the intention of retrieving metadata values.

The following table lists the endpoints where you can make HTTP requests for specific metadata:

Metadata endpoint Description
/computeMetadata/v1/project/numeric-project-id The project number assigned to your project.
/computeMetadata/v1/project/project-id The project ID assigned to your project.
/computeMetadata/v1/instance/zone The zone the instance is running in.
/computeMetadata/v1/instance/service-accounts/default/aliases
/computeMetadata/v1/instance/service-accounts/default/email The default service account email assigned to your project.
/computeMetadata/v1/instance/service-accounts/default/ Lists all the default service accounts for your project.
/computeMetadata/v1/instance/service-accounts/default/scopes Lists all the supported scopes for the default service accounts.
/computeMetadata/v1/instance/service-accounts/default/token Returns the auth token that can be used to authenticate your application to other Google Cloud APIs.

For example, to retrieve your project ID, send a request to http://metadata.google.internal/computeMetadata/v1/project/project-id.