Overview
The Python runtime is the software stack responsible for installing your application code and its dependencies and running your application. The standard runtime is declared in app.yaml
as runtime: python
:
runtime: python
env: flex
Runtimes in the flexible environment environment are built using Docker. The Python runtime is based on Ubuntu 18.04 per the build script. This script, along with the source code for all the Python runtime builds is publicly available on GitHub.
Interpreter
You can specify whether to use Python 2 or Python 3 in your
application's app.yaml
file by using the runtime_config
directive along
with the python_version
setting:
runtime: python
env: flex
runtime_config:
python_version: 3
The default interpreter is
Python 2.7.12 if
runtime_config
or python_version
are omitted. The interpreters that are
deployed for each python_version
setting are shown in the following table:
python_version setting |
Deployed interpreter |
---|---|
2 (default) |
2.7.12 |
3.4 |
3.4.8 |
3.5 |
3.5.9 |
3 or 3.6 |
3.6.10 |
3.7 |
3.7.9 |
The only supported values for python_version
are: 2
, 3
, 3.4
,
3.5
, 3.6
, 3.7
, and they are specified publicly in
this build script. If the desired Python version is
not listed above, here are several options:
- App Engine flexible environment: Create a custom runtime and select a valid base image with the Python version you need.
- App Engine standard environment: Python 3.7, 3.8, 3.9, and 3.10 are supported.
- Cloud Functions: Python 3.7, 3.8, 3.9, and 3.10 are supported.
- Cloud Run: Containerize your app based on a container image for the Python version you need (see its Python Quickstart). As Python 3.10 images are already available, you can deploy that version today.
For the App Engine flexible environment or Cloud Run, see Building custom runtimes for Google-supplied base images or Docker Python base images for currently-available Python images, including Python 2 image information.
To further investigate containerizing App Engine apps for Cloud Run, see the codelab and video content covering containerization with Docker or without Docker. Note this content currently only covers App Engine standard environment to Cloud Run migrations.
Dependencies
The runtime looks for a
requirements.txt
file in your application's source directory and uses pip
to install any dependencies before starting your application. For more
information on declaring and managing packages, see
Using Python Libraries.
If your app requires private dependencies, you need to use a custom runtime based on the Python runtime to install the appropriate packages.
Using C libraries with Python
To enable the use of Python packages that require C extensions, the headers for the current Python version and the following Ubuntu packages are pre-installed on the system:
- build-essential
- ca-certificates
- curl
- gfortran
- git
- libatlas-dev
- libblas-dev
- libcurl4-openssl-dev
- libffi-dev
- libfreetype6-dev
- libjpeg-dev
- liblapack-dev
- libmemcached-dev
- libmysqlclient-dev
- libpng12-dev
- libpq-dev
- libquadmath0
- libsasl2-2
- libsasl2-dev
- libsasl2-modules
- libsqlite3-dev
- libssl-dev
- libxml2-dev
- libxslt1-dev
- libz-dev
- mercurial
- netbase
- pkg-config
- sasl2-bin
- swig
- wget
- zlib1g-dev
These packages allow the installation of most popular Python libraries. If your application requires additional operating-system level dependencies, you will need to use a custom runtime based on this runtime to install the appropriate packages.
Application startup
The runtime starts your application using the entrypoint
defined in app.yaml
. The entrypoint should start a process that
responds to HTTP requests on the port defined by the environment variable PORT
.
Most web applications use a WSGI server such as Gunicorn, uWSGI or Waitress.
Before you can use one of these servers, you must add them as a dependency in your application's requirements.txt
. The runtime ensures that all dependences are installed before your entrypoint is called.
Flask==2.0.2
gunicorn==20.1.0
An example entrypoint using gunicorn for a Flask application:
entrypoint: gunicorn -b :$PORT main:app
An example entrypoint using gunicorn for a Django application:
entrypoint: gunicorn -b :$PORT mydjangoapp:wsgi
Gunicorn is the recommended WSGI server, but it's completely possible to use any other WSGI server. For example, here is an entrypoint that uses uWSGI with Flask:
entrypoint: uwsgi --http :$PORT --wsgi-file main.py --callable app
For applications that can handle requests without a WSGI server, you can just execute a Python script:
entrypoint: python main.py
Recommended Gunicorn configuration
The basic entrypoint examples shown above are intended to be starting points
and may work for your web applications. Most applications, however, will need to
further configure the WSGI server. Instead of specifying all of the settings on
the entrypoint, create a gunicorn.conf.py
file in your project root directory,
where your app.yaml
is located, and specify it in your entrypoint:
entrypoint: gunicorn -c gunicorn.conf.py -b :$PORT main:app
You can read about all of Gunicorn's configuration values in its documentation.
Workers
Gunicorn uses workers to handle requests. By default, Gunicorn uses sync workers. This worker class is compatible with all web applications, but each worker can only handle one request at a time. By default, gunicorn only uses one of these workers. This can often cause your instances to be underutilized and increase latency in applications under high load.
We recommend setting the number of workers to 2-4 times the number of CPU cores for your instance plus one. You can specify this in gunicorn.conf.py
as:
import multiprocessing
workers = multiprocessing.cpu_count() * 2 + 1
Additionally, some web applications that are mostly I/O bound can see a
performance improvement by using a different worker class.
If your worker class requires additional dependencies such as gevent or tornado, those dependencies will need to be declared in your application's requirements.txt
.
HTTPS and forwarding proxies
App Engine terminates the HTTPS connection at the load balancer and forwards the
request to your application. Most applications do not need to know if the
request was sent over HTTPS or not, but applications that do need this
information should configure Gunicorn to trust the App Engine proxy in their
gunicorn.conf.py
:
forwarded_allow_ips = '*'
secure_scheme_headers = {'X-FORWARDED-PROTO': 'https'}
Gunicorn will now ensure that the wsgi.url_scheme
to 'https'
, which most web
frameworks will use as indication of the request is secure. If your WSGI server
or framework doesn't support this, just check the value of the
X-Forwarded-Proto
header manually.
Some applications also need to ascertain the user's IP address. This is
available in the X-Forwarded-For
header.
Note that the secure_scheme_headers
setting in gunicorn.conf.py
should be
upper case, like X-FORWARDED-PROTO
, but the headers that your code can read
will be in mixed case, like X-Forwarded-Proto
.
Extending the runtime
The flexible environment Python runtime can be used to create a custom runtime. See Customizing the Python for more information.
Environment variables
The following environment variables are set by the runtime environment:
Environment Variable | Description |
---|---|
GAE_INSTANCE |
The name of the current instance. |
GAE_MEMORY_MB |
The amount of memory available to the application process. |
GAE_SERVICE |
The service name specified in your application's app.yaml
file, or if no service name is specified, it is set to default . |
GAE_VERSION |
The version label of the current application. |
GOOGLE_CLOUD_PROJECT |
The Project ID associated with your application, which is visible in the Google Cloud console |
PORT |
The port that will receive HTTP requests. |
You can set additional environment variables with app.yaml
.
Metadata server
Each instance of your application can use the Compute Engine metadata server to query information about the instance, including its host name, external IP address, instance ID, custom metadata, and service account information. App Engine does not allow you to set custom metadata for each instance, but you can set project-wide custom metadata and read it from your App Engine and Compute Engine instances.
This example function uses the metadata server to get the external IP address of the instance: