English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Python Application Configuration

A Python App Engine application must have a configuration file named `app.yaml` that specifies how URL paths correspond to request handlers and static files. It also contains information about the application code, such as the application ID and the latest version identifier.

- About app.yaml
- Required Elements
- Script Handlers
- Static File Handlers
- Static Directory Handlers
- Static File Pattern Handlers
- Builtin Handlers
- Includes
- Secure URLs
- User and Administrator Login
- Skipping Files
- Referring to the Python Library Directory
- Reserved URLs
- Inbound Services
- Python Precompilation
- Administration Console Custom Pages
- Custom Error Responses
- Using Concurrent Requests

## About app.yaml

A Python app specifies runtime configuration, including versions and URLs, in a file named `app.yaml`. The following is an example of an `app.yaml` file:

    application: myapp
    version: 1
    runtime: python
    api_version: 1

    handlers:
    - url: /
      script: home.py

    - url: /index\.html
      script: home.py

    - url: /stylesheets
      static_dir: stylesheets

    - url: /(.*\.(gif|png|jpg))
      static_files: static/\1
      upload: static/(.*\.(gif|png|jpg))

    - url: /admin/.*
      script: admin.py
      login: admin

    - url: /.*
      script: not_found.py

The syntax of `app.yaml` is the YAML format. For more information about this syntax, see the YAML website.

Tip: The YAML format supports comments. A line that begins with a pound (`#`) character is ignored:
`# This is a comment.`

URL and file path patterns use POSIX extended regular expression syntax, excluding collating elements and collation classes. Back-references to grouped matches (e.g. `\1`) are supported, as are these Perl extensions: `\w \W \s \S \d \D` (This is similar to Codesite search, plus back-reference support.)

## Required Elements

An `app.yaml` file must include one of each of the following elements:

`application`
  The application identifier. This is the identifier you selected when you created the application in the Administration Console.

      application: myapp

`version`
  A version specifier for the application code. App Engine retains a copy of your application for each version used. An administrator can change which major version of the application is default using Administration Console, and can test non-default versions before making them default. The version specifier can contain letters, digits, and hyphens.

  Each version of an application retains its own copy of `app.yaml`. When an application is uploaded, the version mentioned in the `app.yaml` file being uploaded is the version that gets created or replaced by the upload.

      version: 2-0-test

`runtime`
  The name of the App Engine runtime environment used by this application. To specify Python, use python. Other runtimes are available; please refer to the runtime's documentation for more info. Other JVM languages can customize `app.yaml` based on the specified runtime.

      runtime: java

`handlers`

  A list of URL patterns and descriptions of how they should be handled. App Engine can handle URLs by executing application code, or by serving static files uploaded with the code, such as images, CSS or JavaScript.

  Patterns are evaluated in the order they appear in the `app.yaml`, from top to bottom. The first mapping whose pattern matches the URL is the one used to handle the request.

  There are two kinds of handlers: script handlers, and static file handlers. A script handler runs a Python script in your application to determine the response for the given URL. A static file handler returns the contents of a file, such as an image, as the response.

  See Script Handlers and Handlers for Static Files below for more information on this value.

      handlers:
      - url: /images
        static_dir: static/images

      - url: /.*
        script: myapp.py

`api_version`

  The version of the API in the given runtime environment used by this application. When Google releases a new version of a runtime environment's API, your application will continue to use the one for which it was written. To upgrade your application to the new API, you change this value and upload the upgraded code.

  At this time, App Engine has one version of the `python` runtime environment: `1`

      api_version: 1

threadsafe

  Configures your application to use concurrent requests.

      threadsafe: [true | false]

  Note: The `threadsafe` directive is required for Python 2.7 applications.

## Script Handlers

A script handler executes a Python script to handle the request that matches the URL pattern. The mapping defines a URL pattern to match, and the script to be executed. In Python 2.5, CGI is the preferred method of defining script handlers. In Python 2.7, WSGI is the preferred method. CGI works in Python 2.7, but some features of the runtime, such as concurrent requests, are available only if your app uses WSGI.

`url`

  The URL pattern, as a regular expression. The expression can contain groupings that can be referred to in the file path to the script with regular expression back-references. For example, `/profile/(.*?)/(.*)` would match the URL `/profile/edit/manager` and use `edit` and `manager` as the first and second groupings.

`script`

  If CGI, specifies the path to the script from the application root directory (if CGI):

      ...
      handlers:
      - url: /profile/(.*?)/(.*)
        script: /employee/\2/\1.py   # CGI apps specify a script

  As in the previous example, with the groupings `edit` and `manager`, the script path `/employee/\2/\1.py` uses the full path `/employee/manager/edit.py`.

  If WSGI, specifies the WSGI application (Python 2.7 only):

      ...
      handlers:
      - url: /profile/(.*?)/(.*)
        script: employee.\2.\1.app
      ...

  You also must move your WSGI application object to the global scope:

      import webapp2

      class MainPage(webapp2.RequestHandler):
          def get(self):
              self.response.headers['Content-Type'] = 'text/plain'
              self.response.out.write('Hello, webapp World!')

      app = webapp2.WSGIApplication([('/', MainPage)])

The following examples map URLs to scripts:

    handlers:

    # The root URL (/) is handled by the index.py script. No other URLs match this pattern.
    - url: /
      script: index.py   # or myapp.app

    # The URL /index.html is also handled by the index.py script.
    - url: /index\.html
      script: index.py   # or myapp.app

    # A regular expression can map parts of the URL to the file path of the script.
    - url: /browse/(books|videos|tools)
      script: \1/catalog.py

    # All other URLs use the not_found.py script.
    - url: /.*
      script: not_found.py   # or myapp.app

## Static File Handlers

Static files are files to be served directly to the user for a given URL, such as images, CSS stylesheets, or JavaScript source files. Static file handlers describe which files in the application directory are static files, and which URLs serve them.

For efficiency, App Engine stores and serves static files separately from application files. Static files are not available in the application's file system. If you have data files that need to be read by the application code, the data files must be application files, and must not be matched by a static file pattern.

Unless told otherwise, web browsers retain files they load from a website for a limited period of time. You can define a global default cache period for all static file handlers for an application by including the `default_expiration` element, a top-level element. You can also configure a cache duration for specific static file handler. (Script handlers can set cache durations by returning the appropriate HTTP headers to the browser.)

`default_expiration`

  The length of time a static file served by a static file handler ought to be cached in the user's browser, if the handler does not specify its own `expiration`. The value is a string of numbers and units, separated by spaces, where units can be `d` for days, `h` for hours, `m` for minutes, and `s` for seconds. For example, `"4d 5h"` sets cache expiration to 4 days and 5 hours after the file is first loaded by the browser.

  `default_expiration` is optional. If omitted, the production server sets the expiration to 10 minutes.

For example:

    application: myapp
    version: 1
    runtime: python
    api_version: 1

    default_expiration: "4d 5h"

    handlers:
      # ...

Static file handlers can be defined in two ways: as a directory structure of static files that maps to a URL path, or as a pattern that maps URLs to specific files.

## Static Directory Handlers

A static directory handler makes it easy to serve the entire contents of a directory as static files. Each file is served using the MIME type that corresponds with its filename extension unless overridden by the directory's `mime_type` setting. All of the files in the given directory are uploaded as static files, and none of them can be run as scripts.

`url`

  A URL prefix. This value uses regular expression syntax (and so regexp special characters must be escaped), but it should not contain groupings. All URLs that begin with this prefix are handled by this handler, using the portion of the URL after the prefix as part of the file path.

`static_dir`

  The path to the directory containing the static files, from the application root directory. Everything after the end of the matched `url` pattern is appended to `static_dir` to form the full path to the requested file.

  All files in this directory are uploaded with the application as static files.

`mime_type`

  Optional. If specified, all files served by this handler will be served using the specified MIME type. If not specified, the MIME type for a file will be derived from the file's filename extension.

  For more information about the possible MIME media types, see the IANA MIME Media Types website.

`expiration`

  The length of time a static file served by this handler ought to be cached in the user's browser. The value is a string of numbers and units, separated by spaces, where units can be `d` for days, `h` for hours, `m` for minutes, and `s` for seconds. For example, `"4d 5h"` sets cache expiration to 4 days and 5 hours after the file is first loaded by the browser.

  `expiration` is optional. If omitted, the application's `default_expiration` is used.

For example:

    handlers:

    # All URLs beginning with /stylesheets are treated as paths to static files in
    # the stylesheets/ directory. Note that static_dir handlers do not use a
    # regular expression for the URL pattern, only a prefix.
    - url: /stylesheets
      static_dir: stylesheets

## Static File Pattern Handlers

A static file handler associates a URL pattern with paths to static files uploaded with the application. The URL pattern regular expression can define regular expression groupings to be used in the construction of the file path. You can use this instead of `static_dir` to map to specific files in a directory structure without mapping the entire directory.

Static files cannot be the same as application code files. If a static file path matches a path to a script used in a dynamic handler, the script will not be available to the dynamic handler.

The following `static_dir` and `static_files` handlers are equivalent:

    - url: /images
      static_dir: static/images

    - url: /images/(.*)
      static_files: static/images/\1
      upload: static/images/(.*)

`url`

  The URL pattern, as a regular expression. The expression can contain groupings that can be referred to in the file path to the script with regular expression back-references.

  For example, `/item-(.*?)/category-(.*)` would match the URL `/item-127/category-fruit`, and use `127` and `fruit` as the first and second groupings.

      handlers:
      - url: /item-(.*?)/category-(.*)
        static_files: archives/\2/items/\1

`static_files`

  The path to the static files matched by the URL pattern, from the application root directory. The path can refer to text matched in groupings in the URL pattern.

  As in the previous example, `archives/\2/items/\1` inserts the second and first groupings matched in place of `\2` and `\1`, respectively. With the pattern in the example above, the file path would be `archives/fruit/items/127`.

`upload`

  A regular expression that matches the file paths for all files that will be referenced by this handler. This is necessary because the handler cannot determine which files in your application directory correspond with the given `url` and `static_files` patterns. Static files are uploaded and handled separately from application files.

  The example above might use the following `upload` pattern: `archives/(.*?)/items/(.*)`

`mime_type`

  Optional. If specified, all files served by this handler will be served using the specified MIME type. If not specified, the MIME type for a file will be derived from the file's filename extension.

  For more information about the possible MIME media types, see the IANA MIME Media Types website.

`expiration`

  The length of time a static file served by this handler ought to be cached in the user's browser. The value is a string of numbers and units, separated by spaces, where units can be `d` for days, `h` for hours, `m` for minutes, and `s` for seconds. For example, `"4d 5h"` sets cache expiration to 4 days and 5 hours after the file is first loaded by the browser.

  `expiration` is optional. If omitted, the application's `default_expiration` is used.

For example:

    handlers:

    # All URLs ending in .gif .png or .jpg are treated as paths to static files in
    # the static/ directory. The URL pattern is a regexp, with a grouping that is
    # inserted into the path to the file.
    - url: /(.*\.(gif|png|jpg))
      static_files: static/\1
      upload: static/(.*\.(gif|png|jpg))

## Builtin Handlers

The Python SDK includes a number of builtin handlers for common application functions. The `builtins` directive allows you to include specific handlers in `app.yaml`. You can declare this directive as follows:

    builtins:
    - datastore_admin: on
    - appstats: on

The following builtin handlers are available:

- `admin_redirect` – Redirects calls to `/_ah/admin` from the development console of the development web server to the Admin Console dashboard page.
- `appstats` – Enables Appstats at `/_ah/stats/`, which you can use to measure your application's performance. In order to use App Stats, you also need to install the event recorder.
- `datastore_admin` – Enables datastore admin at `/_ah/datastore_admin/`. This builtin enables the Datastore Admin page in the Admin Console, where you can delete all entities of a given kind, or of all kinds, in the default namespace.
- `deferred` – Enables the deferred handler at `/_ah/queue/deferred`. This builtin allows developers to use `deferred.defer()` to simplify the creation of Task Queue tasks. Also see Background work with the deferred library.
- `remote_api` – Enables the remote_api builtin at `/_ah/remote_api/`. This builtin allows remote applications with the proper credentials to access the datastore remotely.

## Includes

While the `builtins` directive allows you to include modules built into the Python SDK, the `includes` directive allows you to include any library or module throughout your application. For example, you might include a user administration library as follows:

    includes:
    - lib/user_admin.yaml

App Engine resolves the included path in the following order:

- Absolute or relative path to the working directory. The specified path resolves to a file.
- Relative to the application's directory (also known as the basepath). The basepath and path resolve to a file.
- Relative to the file that included the current file. The location of the referring file and the include path resolve to the included file.

If the `include` directive specifies a directory, then App Engine looks in that directory for a file called `include.yaml`. If the include directive is a file, then that specific file is included. Using `includes` retrieves only the following types of directives from the destination file (if present):

- builtins
- includes
- handlers
- admin_console

The builtins directive is a special instance of the `includes` directive. Each `builtin` directive is equivalent, in Python, to an `includes` directive with an expanded path. For example:

    builtins:
      name: on

Is equivalent to:

    includes:
      $PYTHON_LIB/google/appengine/ext/builtins/name/

## Secure URLs

Google App Engine supports secure connections via HTTPS for URLs using the `*.appspot.com` domain. When a request accesses a URL using HTTPS, and that URL is configured to use HTTPS in the `app.yaml` file, both the request data and the response data are encrypted by the sender before they are transmitted, and decrypted by the recipient after they are received. Secure connections are useful for protecting customer data, such as contact information, passwords, and private messages.

Note: Google Apps domains do not currently support HTTPS. HTTPS support is limited to apps accessed via `*.appspot.com` domains. Accessing an HTTPS URL on a Google Apps domain will return a "host not found" error, and accessing a URL whose handler only accepts HTTPS (see below) using HTTP will return an HTTP 403 "Forbidden" error. You can link to an HTTPS URL with the `*.appspot.com` domain for secure features, and use the Apps domain and HTTP for the rest of the site.

To configure a URL to accept secure connections, provide a `secure` parameter for the handler:

    handlers:

    - url: /youraccount/.*
      script: accounts.py
      login: required
      secure: always

`secure` has 3 possible values:

- `optional`. Both HTTP and HTTPS requests with URLs that match the handler succeed without redirects. The application can examine the request to determine which protocol was used, and respond accordingly. This is the default when `secure` is not provided for a handler.
- `never`. Requests for a URL that match this handler that use HTTPS are automatically redirected to the HTTP equivalent URL.
- `always`. Requests for a URL that match this handler that do not use HTTPS are automatically redirected to the HTTPS URL with the same path. Query parameters are preserved for the redirect.

When a user's HTTPS query is redirected to be an HTTP query, the query parameters are removed from the request. This prevents a user from accidentally submitting query data over a non-secure connection that was intended for a secure connection.

Any URL handler can use the `secure` setting, including script handlers and static file handlers.

The development web server does not support HTTPS connections. It ignores the `secure` parameter, so paths intended for use with HTTPS can be tested using regular HTTP connections to the development web server.

When you test your app's HTTPS handlers using the versioned appspot.com URL, such as `https://1.latest.your_app_id.appspot.com/`, your browser warns you that the HTTPS certificate was not signed for that specific domain path. If you accept the certificate for that domain, pages will load successfully. Users will not see the certificate warning when accessing `https://your_app_id.appspot.com/`.

You can also use an alternate form of the versioned appspot.com URL designed to avoid this problem by replacing the periods separating the subdomain components with the string "`-dot-`". For instance, the previous example could be accessed without a certificate warning at `https://1-dot-latest-dot-your_app_id.appspot.com/`.

Google Accounts sign-in and sign-out are always performed using a secure connection, unrelated to how the application's URLs are configured.

## User and Administrator Login

Any URL handler can have a `login` setting to restrict visitors to only those users who have signed in, or just those users who are administrators for the application. When a URL handler with a `login` setting matches a URL, the handler first checks whether the user has signed in to the application using its authentication option. If not, by default, the user is redirected to the Google sign-in page, or `/_ah/login_required` if OpenID authentication is used. The user is redirected back to the application URL after signing in or creating an account. You can also configure the app to simply reject requests for a handler from users who are not properly authenticated, instead of redirecting the user to the sign-in page.

If not, by default, the user is redirected to the Google sign-in page, or /_ah/login_required if the application is set to federated login.

If the setting is `login: required`, once the user has signed in, the handler proceeds normally.

If the setting is `login: admin`, once the user has signed in, the handler checks whether the user is an administrator for the application. If not, the user is given an error message. If the user is an administrator, the handler proceeds.

If an application needs different behavior, the application can implement the user handling itself. See the Users API for more information.

An example:

    handlers:

    - url: /profile/.*
      script: user_profile.py
      login: required

    - url: /admin/.*
      script: admin.py
      login: admin

    - url: /.*
      script: welcome.py

You can configure a handler to refuse access to protected URLs when the user is not signed in, instead of redirecting the user to the sign-in page. A rejected user gets an HTTP status code of 401. To configure an app to reject users who are not signed in, add `auth_fail_action: unauthorized` to the handler's configuration:

    handlers:
    - url: /secure_api/.*
      script: api_handler.py
      login: required
      auth_fail_action: unauthorized

The default `auth_fail_action` is `redirect`.

## Skipping Files

Files in your application directory whose paths match a `static_dir` path or a `static_files` `upload` path are considered to be static files. All other files in the application directory are considered to be application program and data files.

The `skip_files` element specifies which files in the application directory are not to be uploaded to App Engine. The value is either a regular expression, or a list of regular expressions. Any filename that matches any of the regular expression is omitted from the list of files to upload when the application is uploaded.

`skip_files` has the following default value:

    skip_files: |
     ^(.*/)?(
     (app\.yaml)|
     (app\.yml)|
     (index\.yaml)|
     (index\.yml)|
     (#.*#)|
     (.*~)|
     (.*\.py[co])|
     (.*/RCS/.*)|
     (\..*)|
     )$

The default pattern excludes the configuration files `app.yaml`, `app.yml`, `index.yaml`, `index.yml` (configuration is sent to the server separately), Emacs backup files with names of the form `#...#` and `...~`, `.pyc` and `.pyo` files, files in an `RCS` revision control directory, and Unix hidden files with names beginning with a dot (`.`).

If a new value is specified in `app.yaml`, it overrides this value. To extend this pattern, copy and paste it into your configuration with your extensions. For example, to skip files whose names end in `.bak` in addition to the default patterns, you can use the following list value for `skip_files`:

    skip_files:
    - ^(.*/)?app\.yaml
    - ^(.*/)?app\.yml
    - ^(.*/)?index\.yaml
    - ^(.*/)?index\.yml
    - ^(.*/)?#.*#
    - ^(.*/)?.*~
    - ^(.*/)?.*\.py[co]
    - ^(.*/)?.*/RCS/.*
    - ^(.*/)?\..*
    - ^(.*/)?.*\.bak$

## Referring to the Python Library Directory

You can refer to the Python library directory in an `app.yaml` script path using `$PYTHON_LIB`. This is only useful for setting up handlers whose scripts are included in the App Engine libraries.

For example, `$PYTHON_LIB/google/appengine/ext/admin` is an administrative application similar to the developer console feature of the development web server that can run as part of your application on App Engine itself. To set it up, include configuration for a script handler using its path:

    handlers:

    - url: /admin/.*
      script: $PYTHON_LIB/google/appengine/ext/admin
      login: admin

## Reserved URLs

Several URL paths are reserved by App Engine for features or administrative purposes. Script handler and static file handler paths will never match these paths.

The following URL paths are reserved:

- `/_ah/`
- `/form`

## Inbound Services

Before an application can receive email or XMPP messages, the application must be configured to enable the service. You enable the service for a Python app by including an `inbound_services` section in the `app.yaml` file. The following inbound services are available:

- `channel_presence` – registers your application for notifications when a client connects or disconnects from a channel.
- `mail` – allows your application to receive mail
- `xmpp_message` – allows your application to receive instant messages
- `xmpp_presence` – allows your application to receive a user's chat presence
- `xmpp_subscribe` – allows your application to receive user subscription POSTs.
- `warmup` – enables warmup requests

For example, you can enable mail and warmup by specifying the following in `app.yaml`:

    inbound_services:
    - mail
    - warmup

### Warmup Requests

App Engine frequently needs to load application code into a fresh instance. This happens when you redeploy the application, when the load pattern has increased beyond the capacity of the current instances, or simply due to maintenance or repairs of the underlying infrastructure or physical hardware.

Loading new application code on a fresh instance can result in loading requests. Loading requests can result in increased request latency for your users, but you can avoid this latency using warmup requests. Warmup requests load application code into a new instance before any live requests reach that instance.

App Engine attempts to detect when your application needs a new instance, and (assuming that warmup requests are enabled for your application) initiates a warmup request to initialize the new instance. However, these detection attempts do not work in every case. As a result, you may encounter loading requests, even if warmup requests are enabled in your app. For example, if your app is serving no traffic, the first request to the app will always be a loading request, not a warmup request.

Warmup requests use instance hours like any other request to your App Engine application. In most cases, you won't notice an increase in instance hours, since your application is simply initializing in a warmup request instead of a loading request. Your instance hour usage will likely increase if you decide to do more work (such as precaching) during a warmup request. If you set a minimum number of idle instance, you may encounter warmup requests when those instances first start, but they will remain available after that time.

In Python, warmup requests are disabled by default. To enable them, add `-warmup` to the `inbound_services` directive in `app.yaml`:

    inbound_services:
    - warmup

This causes the App Engine infrastructure to issue `GET` requests to `/_ah/warmup`. You can implement handlers in this directory to perform application-specific tasks, such as pre-caching application data.

## Python Precompilation

By default, App Engine uses a "precompilation" process with the Python source code of an app to enhance the performance of the app in the Python runtime environment. Precompilation reduces the time it takes to import a Python module or file, and can substantially increase the speed of the first request handled by an app instance. Precompiled code functions identically to the original source code.

You can disable precompilation for your app using `appcfg.py` with the `--no_precompilation` option.

## Administration Console Custom Pages

If you have administrator-only pages in your application that are used to administer the app, you can have those pages appear in the Administration Console. The Administration Console includes the name of the page in its sidebar, and displays the page in an HTML iframe. To add a page to the Administration Console, add an `admin_console:` section in your app's `app.yaml` file, like so:

    admin_console:
      pages:
      - name: Blog Comment Admin
        url: /blog/admin/comments
      - name: Create a Blog Post
        url: /blog/admin/newentry

Note: Only custom pages defined by the default version will be shown in the Admin Console.

This has an inner `pages:` section, with an entry for each page. The `name` appears in the Administration Console navigation, and the `url` is the URL path to the page.

At this time, page names must contain only characters in the ASCII character set.

You can use configuration to restrict access to custom administration pages to only users that are administrators of the app. See Requiring Login or Administrator Status.

## Custom Error Responses

When certain errors occur, App Engine serves a generic error page. You can configure your app to serve a custom static file instead of these generic error pages. You can set up different static files to be served for each supported error code by specifying the files in your app's `app.yaml` file.

To serve custom error pages, add an `error_handlers` section to your `app.yaml`, as in this example:

    error_handlers:
      - file: default_error.html

      - error_code: over_quota
        file: over_quota.html

Warning!: Make sure that the path to the error response file does not overlap with static file handler paths.

Each `file` entry indicates a static file that should be served in place of the generic error response. The `error_code` indicates which error code should cause the associated file to be served. Supported error codes are as follows:

- `over_quota`, which indicates the app has exceeded a resource quota;
- `dos_api_denial`, which is served to any client blocked by your app's DoS Protection configuration;
- `timeout`, served if a deadline is reached before there is a response from your app.

The `error_code` is optional; if it's not specified, the given file is the default error response for your app.

You can optionally specify a `mime_type` to use when serving the custom error. See http://www.iana.org/assignments/media-types/ for a complete list of MIME types.

## Using Concurrent Requests (Python 2.7 only)

By default, App Engine sends requests serially to a given web server. If you are using the Python 2.7 runtime, you can configure App Engine to send multiple, parallel requests by adding the `threadsafe: true` element to the header of `app.yaml`. All handlers in the app must be WSGI handlers, and the `threadsafe` element is required.

    threadsafe: true