Python 2 is no longer supported by the community. We recommend that you migrate Python 2 apps to Python 3.

Using the local development server

The Cloud SDK includes a local development server ( 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 Python 2 module imports, but not others, like request time-outs 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 command to run your app locally.

To start the local development server:

  1. Run the command as follows from the directory that contains your app's app.yaml configuration file:

    Specify the directory path to your app, for example: [PATH_TO_YOUR_APP]

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

    To change the port, you include the --port option: --port=9999 [PATH_TO_YOUR_APP]

    Is not working?

    To learn more about the 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, you press the following:

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

Specifying application IDs

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

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

if os.getenv('SERVER_SOFTWARE', '').startswith('Google App Engine/'):
  # Production
  # Local development server

Using the local Datastore

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: --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: --clear_datastore=yes app.yaml

Changing local Datastore location

To change the location used for the datastore file, use the --datastore_path option: --datastore_path=/tmp/myapp_datastore app.yaml

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. While running under the local development server, the users.create_login_url and users.create_logout_url functions return URLs for /_ah/login and /_ah/logout on the local server.

Using Mail

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 as follows:: --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 as follows: --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 URL Fetch

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 Interactive Console

The Interactive Console allows developers to enter arbitrary Python code into a web form and execute it inside their app's environment; it provides the same access to the application's environment and services as a .py file inside the application itself.

To use the Interactive Console:

  1. Start the development server.

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

  3. Enter any Python code you'd like to run in the text area, then submit the form to execute it. For example the following code will add a Datastore entity called Greeting with text content of Hello:

      from google.appengine.ext import ndb
      class Greeting(ndb.Model):
        content = ndb.TextProperty()
      e = Greeting(content="Hello")

Debugging with the Python debugger

To use the Python debugger (pdb):

  1. Add the following line into your code:

    import pdb; pdb.set_trace();

    dev_appserver will break at this point and drop into the pdb REPL (read–eval–print loop), allowing you to debug your code from the command line.

  2. If your application makes multiple simultaneous requests that invoke pdb.set_trace(), multiple debugging sessions will start concurrently, each of which sends output to STDOUT. To avoid this, serialize your requests by disabling the dev_appserver multi-threading and multi-processing support, as follows:

    1. Disable multi-threading for:

      • All services using the --threadsafe_override=false flag.
      • One service using the --threadsafe_override=<SERVICENAME>:false flag.
      • Multiple services using the --threadsafe_override=<SERVICE1NAME>:false,<SERVICE2NAME>:false flag.
    2. Disable multi-processing for:

      • All services using the --max_module_instances=1 flag.
      • One service using the --max_module_instances=<SERVICENAME>:1 flag.
      • Multiple services using the --max_module_instances=<SERVICE1NAME>:1,<SERVICE2NAME>:1 flag.