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. If you have feedback or questions as you navigate the site, click Send Feedback.

Using the local development server

Stay organized with collections Save and categorize content based on your preferences.

The Google Cloud CLI includes a local development server (dev_appserver.py). You can use the local development server to simulate running your application in production App Engine as well as use it to access App Engine bundled services.

The simulated environment enforces some sandbox restrictions, such as restricted system functions and runtime language module imports, but not others, like request timeouts or quotas.

The local development server also simulates the services provided by the libraries in the SDK for App Engine, including Datastore, Memcache, and Task Queues, by performing their tasks locally. When your application is running in the development server, you can still make remote API calls to the production infrastructure using Google APIs HTTP endpoints.

Running the local development server

After you create the app.yaml configuration file for your app, you can start the local development server with the dev_appserver.py command to run your app locally.

To start the local development server:

  1. In the directory that contains your app.yaml configuration file, run the dev_appserver.py command. If Python 2 is not the default interpreter on your system, you need to run python2 dev_appserver.py to ensure the Python 2 interpreter is used.

    Go

    dev_appserver.py

    Specify the directory path to your app, for example:

    dev_appserver.py [PATH_TO_YOUR_APP]
    
    

    Alternatively, you can specify the configuration file of a specific service, for example:

      dev_appserver.py app.yaml
    
    

    To change the port, you include the --port option:

      dev_appserver.py --port=9999 [PATH_TO_YOUR_APP]
    
    

    goapp serve

    The goapp serve command is included with the original App Engine SDK for Go and wraps the underlying dev_appserver.py Python tool. To start the local development server, you run:

    goapp serve
    

    PHP

    Windows / macOS

    Specify the directory path to your app, for example:

    dev_appserver.py [PATH_TO_YOUR_APP]
    
    

    Alternatively, you can specify the configuration file of a specific service, for example:

      dev_appserver.py app.yaml
    
    

    To change the port, you include the --port option:

      dev_appserver.py --port=9999 [PATH_TO_YOUR_APP]
    
    

    Note: The SDKs for macOS and Windows already include binaries for the PHP 7+ runtime so there is no need to separately install PHP.

    Linux / cust. php-cgi

    If you're on Linux or if you want to use a custom version of php-cgi, you need to specify the directory path to the php-cgi:

    1. Build your own version of App Engine PHP Extension on your local machine.

    2. Start the local development server with both the --php_executable_path and --php_gae_extension_path options:

      dev_appserver.py --php_executable_path=[PATH_TO_PHP_7_EXECUTABLE] --php_gae_extension_path=[PATH_TO_APPENGINE_EXTENSION] app.yaml
      

      where --php_executable_path is the location of the PHP interpreter you are using, and where --php_gae_extension_path is the location of the gae_runtime_module.so file that you built in the previous step.

    Python

    Specify the directory path to your app, for example:

       dev_appserver.py --runtime_python_path=/usr/bin/python3 [PATH_TO_YOUR_APP]
    
    

    You can also set the argument to a comma-separated key-value list like this:

       dev_appserver.py --runtime_python_path="python27=/usr/bin/python2.7,python3=/usr/bin/python3" [PATH_TO_YOUR_APP]
    

    Alternatively, you can specify the configuration file of a specific service, for example:

       dev_appserver.py --runtime_python_path=/usr/bin/python3 app.yaml
    
    

    To change the port, you include the --port option:

       dev_appserver.py  --runtime_python_path=/usr/bin/python3 --port=9999 [PATH_TO_YOUR_APP]
    
    

    Is dev_appserver.py not working?

    To learn more about the dev_appserver.py command options, see Local Development Server Options.

  2. The local development server is now running and listening for requests. You can visit http://localhost:8080/ in your web browser to see the app in action.

    If you specified a custom port with the --port option, remember to open your browser to that port.

To stop the local server from the command line, press the following:

  • macOS or Linux: Control+C
  • Windows: Control+Break

Specifying application IDs

Go

To access your App ID in the local server, for example to spoof an email address, use the appengine.AppID function.

To get the hostname of the running app, use the appengine.DefaultVersionHostname function.

PHP

To access your App ID in the local server, for example to spoof an email address, use the AppIdentityService::getApplicationId function.

To get the hostname of the running app, use the AppIdentityService::getDefaultVersionHostname function.

Python

To access your App ID in the local server, for example to spoof an email address, use the get_application_id() function.

To get the hostname of the running app, use the get_default_version_hostname() function.

Detecting application runtime environment

Go

To determine whether your code is running in production or in the local development server, you can call the IsDevAppServer() method. When this is true, your code is running in the local development environment; otherwise, you're running in production.


package devserver

import (
	"fmt"
	"net/http"

	"google.golang.org/appengine"
)

func init() {
	http.HandleFunc("/", handler)
}

func handler(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "IsDevAppServer: %v", appengine.IsDevAppServer())
}

PHP

To determine whether your code is running in production or in the local development server, you can check the value of the SERVER_SOFTWARE environment variable:

if (strpos(getenv('SERVER_SOFTWARE'), 'Development') === 0){
  echo 'Local development server';
} else {
  echo 'Production';
}

Debugging locally with XDebug

For PHP 7+, if you have a debugger that is compatible with the XDebug debugger, and you have the xdebug module installed, you can use XDebug with the local development server.

To enable XDebug on the Development Server on Linux or macOS:

  1. Export the XDEBUG_CONFIG environment variable with an idekey for your IDE to connect to

    export XDEBUG_CONFIG="idekey=netbeans-xdebug remote_host=localhost"
    
  2. Invoke the Development Server with --php_remote_debugging=yes

Python

To determine whether your code is running in production or in the local development server, you can check the value of the GAE_ENV environment variable:

if os.getenv('GAE_ENV', '').startswith('standard'):
  # Production in the standard environment
else:
  # Local development server

Using the local Datastore service

Go

The local development server simulates the App Engine datastore using a local file that persists between invocations of the local server.

For more information on indexes and index.yaml, see the Datastore Indexes and Datastore Index Configuration pages.

Browsing the local Datastore

If your app has written data to your local Datastore using the local development server, you can browse it in the local development console.

To browse local Datastore:

  1. Start the development server.

  2. Access the Datastore Viewer in the local development console. The URL is http://localhost:8000/datastore.

  3. View your local Datastore contents.

Specifying the ID allocation policy

For production App Engine, you can set the Datastore to automatically generate entity IDs.

Although the auto ID assignment policies for the production server are completely different than those used by the development server, you can also set the automatic ID allocation policy for the local server.

To specify the automatic ID assignment policy, use the --auto_id_policy option:

  dev_appserver.py --auto_id_policy=sequential

where --auto_id_policy can be one of the following:

  • scattered: (default) IDs are assigned from a non-repeating sequence of approximately uniformly distributed integers.
  • sequential: IDs are assigned from the sequence of consecutive integers.

Clearing the local Datastore

To clear the local datastore for an application, invoke the local development server as follows:

dev_appserver.py --clear_datastore=yes app.yaml

Changing local Datastore location

To change the location used for the datastore file, use the --datastore_path option:

dev_appserver.py --datastore_path=/tmp/myapp_datastore app.yaml

PHP

Storing data

App Engine for PHP supports reading and writing to Cloud Storage via PHP's streams API. You can read and write to Cloud Storage by specifying a Cloud Storage URI (gs://) when using any PHP function that supports PHP Streams implementation such as fopen, fwrite or file_get_contents.

The local development server emulates this functionality by reading and writing to temporary local files that are preserved between requests.

Browsing the local Datastore

If your app has written data to your local Datastore using the local development server, you can browse it in the local development console.

To browse local Datastore:

  1. Start the development server.

  2. Access the Datastore Viewer in the local development console. (The URL is http://localhost:8000/datastore.)

  3. View your local Datastore contents.

Python

Not applicable to this runtime.

Using the Mail service

The local development server can send email for calls to the App Engine mail service using either an SMTP server or a local installation of Sendmail.

Using SMTP

To enable mail support with an SMTP server, invoke dev_appserver.py as follows::

dev_appserver.py --smtp_host=smtp.example.com --smtp_port=25 \
    --smtp_user=ajohnson --smtp_password=k1tt3ns [PATH_TO_YOUR_APP]

where you set the --smtp_host, --smtp_port, --smtp_user and --smtp_password options with your own values.

Using Sendmail

To enable mail support with Sendmail, invoke dev_appserver.py as follows:

dev_appserver.py --enable_sendmail=yes [PATH_TO_YOUR_APP]

The local server will use the sendmail command to send email messages with your installation's default configuration.

Using the URL Fetch service

When your application uses the URL fetch API to make an HTTP request, the local development server makes the request directly from your computer. The URL Fetch behavior on the local server may differ from production App Engine if you use a proxy server for accessing websites.

Using the Users service

App Engine provides a Users Service to simplify authentication and authorization for your application. The local development server simulates the behavior of Google Accounts with its own sign-in and sign-out pages.

Go

While running under the local development server, the LoginURL and LogoutURL functions return URLs for /_ah/login and /_ah/logout on the local server.

PHP

While running under the local development server, the createLoginURL and createLogoutURL functions return URLs for /_ah/login and /_ah/logout on the local server.

Python

While running under the local development server, the functions return URLs for /_ah/login and /_ah/logout on the local server.

Command-Line Arguments

For the local development server command options see here.