The App Engine Python SDK includes a web server application you can run on your computer that simulates your application running in the App Engine Python runtime environment. The simulated environment enforces some sandbox restrictions, such as restricted system functions and Python module imports, but not others, like request time-outs or quotas.
The development server also simulates the services provided by App Engine Python SDK libraries (e.g. Datastore, Memcache, Task Queue) by performing their tasks locally. Note that 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 development web server
- Application IDs in the development web server
- Using the Datastore
- The Users service in the development web server
- Using Mail
- Using URL Fetch
- The Development Console
- The Interactive Console
- Debugging with PDB
- Command-line arguments
Running the development web server
Once you have a directory for your application and an app.yaml configuration file, you can start the development web server with the
The web server listens on port 8080 by default. You can visit the application at this URL: http://localhost:8080/.
To change which port the web server uses, use the
dev_appserver.py --port=9999 myapp
To stop the web server: with Mac OS X or Unix, press Control-C or with Windows, press Control-Break in your command prompt window.
dev_appserver.py only runs Python 2.7 apps. For help migrating, see Migrating to Python 2.7.
Application IDs in the development web server
If you need to access your App ID, for example to spoof an email address, use the
get_application_id() function. To get the hostname of the running app, use the
Using the Datastore
The development web server simulates the App Engine datastore using a SQLite-backed local datastore on your computer. This datastore persists between invocations of the web server, so data you store will still be available the next time you run the web server.
To clear the local datastore for an application, use the
--clear_datastore=yes option when you start the web server:
dev_appserver.py --clear_datastore=yes myapp
To change the location used for the datastore file, use the
dev_appserver.py --datastore_path=/tmp/myapp_datastore myapp
When your application performs a query on the datastore, the development web server checks that the query is supported by the application's
index.yaml file. If the query requires that its index be mentioned in the file, the server generates one and adds it to the file. You may want to edit this file if your application may attempt queries that are not exercised by your tests.
index.yaml is generated from every query made since the datastore file was created or last cleared. The query history is stored in a separate file.
Browsing the local Datastore
To browse your local Datastore using the development web server:
Start the development server as described previously.
Go to the Development Console.
Click Datastore Viewer in the left navigation pane to view your local Datastore contents.
Specifying the automatic ID allocation policy
You can configure how the local datastore assigns automatic entity IDs. The following automatic ID allocation policies are supported in the development server:
sequential: IDs are assigned from the sequence of consecutive integers.
scattered: IDs are assigned from a non-repeating sequence of approximately uniformly distributed integers.
In the file-backed local datastore, the automatic IDs of all entities are drawn from a single ID sequence. In the SQLite-backed local datastore and the production datastore, a separate ID sequence is maintained for each entity group.
The default policy in the local datastore is
To specify the automatic ID assignment policy, use the
The Users service in the development web server
App Engine provides a Users Service to simplify authentication and authorization for your application. The development web server simulates the behavior of Google Accounts with its own sign-in and sign-out pages. While running under the development web server, the
users.create_logout_url functions return URLs for
/_ah/logout on the local server.
The development web server can send email for calls to the App Engine mail service. To enable email support, the web server must be given options that specify a mail server to use. The web server can use an SMTP server, or it can use a local installation of Sendmail.
To enable mail support with an SMTP server, use the
--smtp_password options with the appropriate values.
dev_appserver.py --smtp_host=smtp.example.com --smtp_port=25 \ --smtp_user=ajohnson --smtp_password=k1tt3ns myapp
To enable mail support with Sendmail, use the
--enable_sendmail option with a value of
yes. The web server will use the
sendmail command to send email messages with your installation's default configuration.
If mail is not enabled with either SMTP or Sendmail, then attempts to send email from the application will do nothing, and appear successful in the application.
Using URL Fetch
When your application uses the URL fetch API to make an HTTP request, the development web server makes the request directly from your computer. The behavior may differ from when your application runs on App Engine if you use a proxy server for accessing websites.
The Development Console
The development web server includes a console web application. With the console, you can browse the local datastore, and interact with the application by submitting Python code to a web form.
To access the console, visit the URL
http://localhost:8000 on your server.
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.
To access the Interactive Console, go to the Development Console for your application, then click the Interactive Console link on the left navigation. A form with a single text area will display. Enter any arbitrary Python code you like in the text area, then submit the form to execute it.
Debugging with PDB
To use PDB, add a line such as:
import pdb; pdb.set_trace();
into your code, and
dev_appserver will break at this point, and drop into the PDB REPL, allowing you to debug your code from the command line.
Warning: If you make multiple simultaneous requests that invoke
pdb.set_trace(), then multiple debugging sessions will start concurrently and both will send output to STDOUT. This can lead to unpredictable debugging experiences.
To help prevent this, you can also disable some of the
dev_appserver's multi-threading and multi-processing support.
- Multi-threading can be disabled for a module using the
--threadsafe_override=<MODULENAME>:falseflag; it can be disabled for multiple modules using the
--threadsafe_override=<MODULE1NAME>:false,<MODULE2NAME>:falseflag; it can be disabled for all modules using the
- Multi-processing can be disabled for a module using the
--max_module_instances=<MODULENAME>:1flag; it can be disabled for multiple modules using the
--max_module_instances=<MODULE1NAME>:1,<MODULE2NAME>:1flag; it can be disabled for all modules using the
Using these techniques you can serialize your requests. Note that, if you are using App Engine modules in your application, the
dev_appserver will still serve multiple requests simultaneously for different modules.
dev_appserver.py command supports the following command-line arguments:
- Host name to which the local Development Console should bind (default: localhost).
- Port to which the local Development Console should bind (default: 8000).
- Uses the local computer's Sendmail installation for sending email messages.
- Prints a helpful message then quits.
- The host address to use for the server. You may need to set this to be able to access the development server from another computer on your network. An address of
0.0.0.0allows both localhost access and hostname access. Default is
- The lowest logging level at which logging messages will be written to the console; messages of the specified logging level or higher will be output. Possible values are
- The port number to use for the server. Default is
8080. If multiple servers are launched, they will be assigned subsequent ports (e.g.
By default, development server logs are stored in memory only. This option turns on disk storage of logs at the location specified by LOGS_FILE, making the logs available across server restarts. For example,
dev_appserver.py --logs_path=/home/logs/boglogs bog
- Disables automatic generation of entries in the
index.yamlfile. Instead, when the application makes a query that requires that its index be defined in the file and the index definition is not found, an exception will be raised, similar to what would happen when running on App Engine. The default value is
- The hostname of the SMTP server to use for sending email messages.
- The port number of the SMTP server to use for sending email messages.
- The username to use with the SMTP server for sending email messages.
- The password to use with the SMTP server for sending email messages.
- Path at which all local files (such as the Datastore, Blobstore files, Google Cloud Storage Files, logs, etc) will be stored, unless overridden by