appengine-web.xml Reference

In addition to the web.xml deployment descriptor, an App Engine Java application uses a configuration file, named appengine-web.xml, to specify the app's registered application ID and the version identifier of the latest code, and to identify which files in the app's WAR are static files (like images) and which are resource files used by the application. The appcfg command uses this information when you upload the app.


The following example is a minimal file that specifies the application ID, a version identifier, and no static files or resource files:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">


An App Engine Java app must have a file named appengine-web.xml in its WAR, in the directory WEB-INF/. This is an XML file whose root element is <appengine-web-app>.

You can find the DTD and schema specifications for this file in the SDK's docs/ directory.

Element Description

Not required if you deploy your app using the gcloud app deploy command. gcloud and gcloud tooling (Intellij, Gradle, and the new maven plug-ins) ignore this element and get the project ID from the gcloud config project property. The <application> element contains the application's project ID. This is the project ID you register when you create your project in the Google Cloud Platform Console. When you upload your app, appcfg gets the project ID from this file.


Optional. It's possible to reduce request latency by configuring your application to asynchronously write HTTP session data to the datastore:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">
  <!-- ... -->
  <async-session-persistence enabled="true" />
  <!-- ... -->

With async session persistence turned on, App Engine will submit a Task Queue task to write session data to the datastore before writing the data to memcache. By default the task will be submitted to the `default` queue. If you'd like to use a different queue, add the `queue-name` attribute:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">
  <!-- ... -->
  <async-session-persistence enabled="true" queue-name="myqueue"/>
  <!-- ... -->

Session data is always written synchronously to memcache. If a request tries to read the session data when memcache is not available (or the session data has been flushed), it will fail over to the datastore, which might not yet have the most recent session data. This means that asynchronous session persistence can cause your application to see stale session data. However, for most applications the latency benefit far outweighs the risk.

<auto-id-policy> Optional. If you are setting entity identifiers automatically, you can change the method employed by setting the auto ID policy. The following are valid options:
Default. Uses scattered auto IDs that are large well-distributed integeres that are small enough to be reperesented by 64-bit floats.
The legacy option will be deprecated in a future release and will eventually be removed. For more information, see the blog post announcing this change.

Optional. For a full explanation, see the automatic scaling section.


Optional. For a full explanation, see the basic scaling section.


Optional. The appengine-web.xml file can define environment variables that are set when the application is running.

  <env-var name="DEFAULT_ENCODING" value="UTF-8" />

To avoid conflicts with your local environment, the development server does not set environment variables based on this file, and requires that the local environment have these variables already set to matching values.

dev_appserver war

When deployed to App Engine, the environment is created with these variables already set.


Optional. Before an application can receive email or XMPP messages, the application must be configured to enable the service. You enable the service for a Java app by including an <inbound-services> section in the appengine-web.xml file.

The following inbound services are available:

Registers your application for notifications when a client connects or disconnects from a channel.
Allows your application to receive mail.
Allows your application to receive instant messages.
Allows your application to receive a user's chat presence.
Allows your application to receive user subscription POSTs.
Enables warmup requests.

Optional. The instance class size for this module.

The following instance classes are available when specifying different scaling options:

When using automatic scaling, the F1, F2, F4, and F4_1G instance classes are available.
Default: F1 is assigned if you do not specify an instance class along with the automatic_scaling element.
When using basic scaling, the B1, B2, B4, B4_1G, and B8 instance classes are available.
Default: B2 is assigned if you do not specify a instance class along with the basic_scaling element.
When using basic scaling, the B1, B2, B4, B4_1G, and B8 instance classes are available.
Default: B2 is assigned if you do not specify a instance class along with the manual_scaling element.

Optional. For a full explanation, see the manual scaling section.


Optional. App Engine uses a "precompilation" process with the Java bytecode of an app to enhance the performance of the app in the Java runtime environment. Precompiled code functions identically to the original bytecode.

If for some reason you prefer that your app not use precompilation, you can turn it off by adding the following to your appengine-web.xml file:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">
  <!-- ... -->
  <!-- ... -->

Note: Modules are now named Services and services are still declared in appengine-web.xml files as modules, for example: <module>service_name</module>.

Required if creating a service. Optional for the default service. Each service and each version must have a name. A name can contain numbers, letters, and hyphens. It cannot be longer than 63 characters and cannot start or end with a hyphen. Choose a unique name for each service and each version. Don't reuse names between services and versions.

Also see service.


Optional. The <public-root> is a directory in your application that contains the static files for your application. When a request for a static file is made, the <public-root> for your application is prepended to the request path. This gives the path of an application file containing the content that is being requested.

The default <public-root> is /.

For example, the following would map the URL path /index.html to the application file path /static/index.html:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">
  <!-- ... -->
  <!-- ... -->

Optional. The files that listed in the <resource-files> element are accessible by the application code using the filesystem. These files are stored on the application servers with the app as opposed to how static files are stored and served.

The <resource-files> element can contain the following elements:

An <include> element designates the files as resource files and available to your application code. These files are only available to your code on a read-only basis and not for traffic serving. Including and excluding files.

Files and directories matching <exclude> patterns will not be uploaded or available to your application code. However, these files and directories will still be accessible to your application when running on the local Development Server. For more information, see Including and excluding files.

  <include path="/**.xml" />
  <exclude path="/feeds/**.xml" />

This example demonstrates how to designate all .xml files as resource files except those in t