Migrating an Existing App Engine App

Google supplies a Python runtime for the flexible environment that works with applications that were originally written for the App Engine standard environment and use the standard environment's APIs. Because this runtime is backwards-compatible, it is called a "compat" runtime. If you would like to deploy your application on the flexible environment and continue to use the standard environment APIs, select the compat runtime by changing runtime: python27 to runtime: python-compat and adding the setting vm: true to the application's app.yaml configuration file:

runtime: python-compat
vm: true

With this configuration, your application uses a Python 2.7 runtime that has a certain number of App Engine standard environment's APIs included in the image:

Notably, the following APIs are not supported:

Runtime comparison

The table below summarizes the differences between the two runtimes.

  Python Compat Runtime Python Runtime
Python Version 2.7 2.7 or 3.4
WSGI Server Managed by the runtime Defined and configured by the user
App Engine APIs Available Not available. Use Google Cloud Client Libraries instead.
Google Cloud Client Libraries Available Available
Third-party libraries Yes, runtime installs requirements.txt if present Yes, runtime requires requirements.txt.
OS-level packages for common
third-party python libraries
Yes Yes

Configuration changes

Because of the differences in the infrastructure and the runtime in the flexible environment, you might need to further modify your application's app.yaml configuration file.

  • The flexible runtime supports manual and automatic scaling. If your app uses basic scaling, you'll need to change that in your configuration file.
  • Apps in the flexible environment are not assigned instance classes. Instead, you specify resources in the app.yaml file.
  • The libraries section of app.yaml is no longer supported. You will need to declare dependencies in requirements.txt.
  • Script and static file handlers defined in app.yaml will continue to work with the compatible runtime. The compat runtime handles running the WSGI server and routing requests. However, if you switch to the non-compat runtime, you will need to remove those handlers from app.yaml and use your own WSGI server such as gunicorn. For more information on configuring your own WSGI server, see the Python runtime page.
  • Script handlers defined in app.yaml that require login with will continue to work with the compat runtime. However, for flexible runtimes, it is recommended that you use the Identity Toolkit for user identification. Script handlers that are configured as login: admin will continue to work the same for both runtimes.
  • Handlers defined in the app.yaml file as secure: always will continue to work in the compat runtime. However, if you switch to the non-compat runtime, you will need to use a web framework-level library like flask-sslify or django-sslify to force connections to HTTPS.

Behavioral differences

The flexible environment has less restrictions than the standard environment on application code. Because of this, some of the runtime behavior is different between the standard environment's runtime and the compat runtime.

  • flexible allows you to write to disk and open sockets to any IP address.
  • flexible allows you to use binary third-party Python packages.
  • In the standard environment, vendoring was necessary to install third-party libraries. This task is not needed in the flexible environment as the runtime will automatically install dependencies declared in requirements.txt, including dependencies that require native extensions.
  • In the standard environment, some system APIs like time.tzset do not work because the runtime does not allow applications to modify certain system properties. However, in the flexible environment these restrictions have been lifted. This change means that third-party libraries can make changes to system properties. Notably, Django will change your time zone to the value in your Django settings module, which is set to "America/Chicago" in new projects. This can cause some unexpected behavior when migrating Django applications.

Moving from runtime: python-compat to runtime: python

The compat runtime can be used to gradually migrate your application to the new Python runtime. As you become more familiar with flexible and the Python runtime you should consider using native features and Google Cloud Client Libraries instead of the App Engine APIs provided by compat runtime. The articles in the Guides section explain many of these techniques.

Running locally

To run an application using the compat runtime locally use the App Engine SDK's dev_appserver.py and specify the --runtime flag.

dev_appserver.py --runtime python-compat .

You must install any dependencies declared in requirements.txt before running dev_appserver.py.


To deploy to the flexible environment, use the Cloud SDK instead of using the appcfg.py command from the App Engine SDK:

gcloud app deploy
gcloud app deploy index.yaml queue.yaml

Running in the flexible environment

The App Engine standard environment runs your application in instances rather than Virtual Machines. The standard environment imposes certain restrictions such as inability to write to disk.

In contrast, the flexible environment is based on running Docker containers in Google Compute Engine virtual machines. The flexible environment provides more CPU and memory options as well as full customizability of the runtime.

You can choose the App Engine environment (standard or flexible) separately for each service in your application. This means an application can contain a mix of services that use different environments. For example, you might use the standard environment for your client-facing frontend, and use a service running in a flexible environment for backend processing.

The following table summarizes the differences between the two App Engine hosting enviroments:

Feature App Engine standard environment App Engine flexible environment
Instance startup time Milliseconds Minutes
Maximum request timeout 60 seconds 60 minutes
Background threads Yes, with restrictions Yes
Background processes No Yes
SSH debugging No Yes
Scaling Manual, Basic, Automatic Manual, Automatic
Writing to local disk No Yes, ephemeral (disk initialized on each VM startup)
Customizable serving stack No Yes (built by customizing a Dockerfile)
Automatic in-place security patches Yes Yes
Network access Only via App Engine services (includes outbound sockets) Yes
Supports installing third party binaries No Yes
Location United States or European Union While in Beta, United States only.
Pricing Based on Instance hours While in Beta, based on Compute Engine Pricing for each VM. Pricing may change in the future.

Also, note that flexible environment differ from Compute Engine VMs in the following ways:

  • The VMs in the flexible environment are restarted on a weekly basis. During restarts Google’s management services will apply any necessary OS and security updates. (Weekly restarts are disabled if you switch a VM to debug mode.)
  • Users always have root access to Compute Engine VMs. SSH access to the VMs is disabled by default. If you choose, you can enable root access to the VMs; see Connecting to an Instance with SSH.
  • The VMs in the flexible environment are automatically located by geographical region according to the settings in your project. Google's management services will ensure that all the VMs for a project are co-located for optimal performance.

Customizing the compat runtime

Custom runtimes allows you to create your own runtime environment using Docker containers. You can create a custom runtime using the compat runtime as the base image in order to add additional components such as os-level packages.

To create the base Dockerfile for the compat runtime, run:

gcloud beta app gen-config --custom

You can customize the generated Dockerfile as needed. When you deploy this Dockerfile will be used to build the container that is used to run your application.

Send feedback about...

App Engine flexible environment for Python docs