Learn how to run your application locally, deploy it, and test onApp Engine.

Run locally

To test your application before deploying, run your applicationin your local environment with the development tools that you usually use.We recommend that you use standard Python tools, such asvirtualenv to createisolated environments andpytest to run unit tests and integration tests, ratherthan depending ondev_appserver, the local development server provided with theGoogle Cloud SDK.

For example, you can usually run a Flask application with theFlask development server using:

pythonmain.py

Start Django applications using:

pythonmanage.pyrunserver

To simulate a production App Engine environment, run the fullWeb Server Gateway Interface (WSGI) server locally. Use the samecommand specified as entrypoint in yourapp.yaml file, for example:

gunicorn-b:$PORTmain:app

Before deploying your application

Before deploying your application:

• TheOwner ofthe Google Cloud project mustset up your Google Cloud project for App Engine.
• Ensure that your user accountincludes therequired privileges.

Deploy your application

Deploy your application to App Engine using thegcloud app deploy command. Duringdeployment, theCloud Build service builds a containerimage of your application to run in the standard environment.Each build is run in the same region as your Google Cloud project. For moreinformation, seeManage build images.

To programmatically deploy your apps, use theAdmin API.

Deploy a service

You deploy your application to App Engine by deploying versions ofyour application's services and each of their configuration files.

To deploy a version of your application's service, run the following commandfrom the directory where theapp.yaml file of your service is located:

gcloudappdeploy

Specifying no files with the command deploys only theapp.yaml file in yourcurrent directory. By default, thedeploy command generates a unique ID forthe version that you deploy, deploys the version to theGoogle Cloud project you configured the Google Cloud CLI to use,and routes all traffic to the new version.

You can change the default behavior of the command by targeting specific filesor including additional parameters:

• To deploy the other configuration files of your service, you must target anddeploy each file separately. For example:

  gcloudappdeploycron.yamlgcloudappdeploydispatch.yamlgcloudappdeployindex.yaml

• To specify a custom version ID, use the--version flag.
• To prevent traffic from being automatically routed to the new version, usethe--no-promote flag.
• To deploy to a specific Google Cloud project, use the--project flag.

For example, to deploy the service defined by theapp.yaml file to a specificGoogle Cloud project, assign it a custom version ID, and prevent trafficfrom being routed to the new version:

gcloudappdeploy--projectPROJECT_ID--versionVERSION_ID--no-promote

For more information about this command, see thegcloud app deployreference.

When you deploy a new version with the same name as an existing version,App Engine immediately migrates traffic to the new version. There is a latencyspike when App Engine loads requests to the new version. The new versionoverwrites the previous one, and you won't be able to migrate the traffic to theprevious version. All instances of the previous version are immediately shutdown. For more information, seeMigrating traffic.

Deploy multiple services

You use the same deployment command for deploying or updating the multipleservices that make up your application.

Before you begin:

• You must initially deploy a version of your application to thedefaultservice before you can create and deploy subsequent services.
• The ID of each of your services must be specified in their correspondingapp.yaml configuration files. To specify the service ID, include theservice element definition in each configuration file. By default, excludingthis element definition from your configuration file deploys the version tothedefault service.

To deploy multiple services, separately deploy each service'sapp.yamlfile. You can specify multiple files with a singlegcloud app deploy command:

gcloudappdeployservice1/app.yamlservice2/app.yaml

View build logs

Cloud Build streams build and deploy logs that are viewable in the Cloud BuildBuild history section ofthe Google Cloud console. To view builds in the app's region, use theRegion menu to filter by the region.

Manage build images

Caution: Container Registry is deprecated. Effective March 18, 2025, Container Registry is shut down, and writing images to Container Registry is unavailable. For details on the deprecation and how to migrate to Artifact Registry, seeContainer Registry deprecation.

Each time you deploy a new version:

1. App Engine creates a container imageusing theCloud Build service.

2. Cloud Build buildsthe container image in the app's region, and runs in the App Engine standard environment.

3. App Engine stores built container images inArtifact Registry.You can download these images tokeep or run elsewhere.

After deployment is complete, App Engine nolonger needs the container images. The container images aren't automatically deleted.To avoid reaching your storage quota, you can safely delete any images youdon't need. However, if you might need the images in the future or want to keepa copy of the images, you need to export a copy prior to deletion. For moreinformation about managing images in Artifact Registry, seeManage images.

Ignore files

You can use a.gcloudignore file to specify files and directories that won'tbe uploaded to App Engine when you deploy your services. This isuseful for ignoring build artifacts and other files that don't need to beuploaded with your deployment.

After you deploy your application to App Engine, you can run thefollowing command to launch your browser and view it athttps://PROJECT_ID.REGION_ID.r.appspot.com:

gcloudappbrowse

Test on App Engine before shifting traffic

Before configuring a new version to receive traffic, you can test it onApp Engine. For example, to test a new version of yourdefault service:

1. Deploy your new version, but prevent traffic from being automatically routedto the new version:

   gcloudappdeploy--no-promote

2. Access your new version by navigating to the following URL:

   https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

   Note: You can find the version ID in theGoogle Cloud console or specify one when you deploy with the--version flag. TheGoogle Cloud CLI also outputs the version ID when you deploy.

   Now you can test your new version in the App Engine runtimeenvironment. You can debug your application by viewing its logs. For moreinformation, seeWriting Application Logs.

   App Engine routes requests sent tohttps://PROJECT_ID.REGION_ID.r.appspot.com to theversion previously configured to receive traffic.

3. When you want to send traffic to the new version, use theGoogle Cloud console to migrate traffic:

   Manage versions

   Select the version you just deployed and clickMigrate traffic.

You can use the same process to test new versions of other services by replacingdefault in the URL with your service's name:

https://VERSION-dot-SERVICE-dot-PROJECT_ID.REGION_ID.r.appspot.com

For more information about targeting specific services and versions, seeHow requests are routed.

Use build environment variables

You can set build environment variables for runtimes that supportbuildpacks.

Build environment variables are key-value pairs that you can specify toconfigure the buildpack you use to deploy your app. For example, you mightwant to specify compiler options.

Before you begin:

• Keys must start with an uppercase ASCII letter, and can includeuppercase ASCII letters, digits, and underscores.
• You should avoid creating any variables with aGOOGLE_* keyprefix.
• The following keys are reserved for Google's use:
  • GOOGLE_RUNTIME
  • GOOGLE_RUNTIME_VERSION
  • GOOGLE_ENTRYPOINT
  • GOOGLE_DEVMODE
• You can use any key that is supported bybuildpacks.

To use environment variables with buildpacks, specify thebuild_env_variablesfield in yourapp.yaml file.

Learn more about buildpacks.

Use the local development server

TheGoogle Cloud CLI includes a local development server nameddev_appserver that you can run locally to simulate your application running inproduction App Engine. This development server partially simulates theenvironment in which your application runs, allowing you to test apps written forany of the standard environment runtimes.

Run the local development server

After you create theapp.yamlconfiguration file for your app, you can start the local development serverwith thedev_appserver.py command to run your app locally.

1. To obtain access credentials for your user account, run:

   gcloudauthlogin

2. Allow your local application to temporarily use your user credentials for APIaccess:

   gcloudauthapplication-defaultlogin

3. To start the local development server:

   In the directory that contains yourapp.yaml configuration file, run thedev_appserver.py command and specify your project ID and path to yourapp.yaml file:

   python3CLOUD_SDK_ROOT/bin/dev_appserver.py--application=PROJECT_IDapp.yaml

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

   python3CLOUD_SDK_ROOT/bin/dev_appserver.py--application=PROJECT_IDapp.yaml--port=9999

   To test a Python 3 app, rundev_appserver.py with a Python 3interpreter, you must specify the Python 3 binary in the--runtime_python_path flag, for example:

   python3CLOUD_SDK_ROOT/bin/dev_appserver.py--runtime_python_path=/usr/bin/python3--application=PROJECT_IDapp.yaml--port=9999

   To learn more about thedev_appserver.py command options, seeLocal development server options.

4. As the local development server starts, it sets up a development environmentthat pre-installs the dependencies found in yourrequirements.txt file.

5. The local development server is now running and listening for requests. Visithttp://localhost:8080/ in your web browser to seethe app in action.

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

6. To stop the local server from the command line, pressControl-Con your keyboard.

Detect application runtime environment

To determine whether your code is running in production or in the localdevelopment server, you can check theGAE_ENV environment variable:

if os.getenv('GAE_ENV', '').startswith('standard'):  # Production in the standard environmentelse:  # Local execution.

Use the local development server with Google Cloud services

You can integratedev_appserver with other Google Cloud components.

Cloud client libraries

Many Google Cloud client libraries depend on the presence of theGOOGLE_CLOUD_PROJECT environment variable, which should be yourGoogle Cloud project ID. You can find its value by running thegcloud config list project command or looking at your project page in theGoogle Cloud console.

To ensure that this environment variable is set correctly during localdevelopment, initializedev_appserver using the--application=PROJECT_ID parameter as shown in theexample above.

Cloud emulators

You can test your application with emulators forCloud Datastore,Cloud Bigtable andCloud Pub/Sub.

Auto-reloadrequirements.txt andapp.yaml changes

The local development server automatically installs dependencies found in yourrequirements.txt file.dev_appserver also allows you to test functionalitythat is configured viaapp.yaml. For example, you can test your app's abilitytoserve staticfiles. Whendev_appserver is running, any changes torequirements.txt andapp.yamlautomatically restarts your app to reflect these changes. This may result in atemporary delay as dependencies are downloaded and installed.

Instance management and routing in the development server

Discover instance addresses

The local development server creates all manual scaling instances at startup.Instances for automatic and basic scaling services are managed dynamically. Theserver assigns a port to each service, and clients can depend on the server toload-balance and select an instance automatically. The port assignments foraddressing each service appear in the server's log message stream.

Here are the ports for an app that defines three services:

INFOStartingmodule"default"runningat:http://localhost:8084INFOStartingmodule"service1"runningat:http://localhost:8082INFOStartingmodule"service2"runningat:http://localhost:8083

When you use a service's address, for examplehttp://localhost:8082/, theserver creates or selects an instance of the service and sends the request tothat instance.

The server assigns unique ports to each instance of a service. You can use theadmin server to discover these ports. There is a unique port for the adminserver, which appears in the message log:

INFOStartingadminserverat:http://localhost:8000

This address takes you to the admin server console. Click onInstancesto see the dynamic state of your app's instances

A separate entry appears for each manual and basic instance. The instancenumbers are links with unique port addresses for each instance. Click on thelink to send a request directly to that instance.

Dispatch files

If your app includes adispatch.yaml file, the log messages stream includes adispatcher port:

INFOStartingdispatcherrunningat:http://localhost:8080

Requests to this port are routed according to the rules in the dispatch file.The server doesnot supportdispatch.yaml file rules that includehostnames, for example,url: "customer1.myapp.com/*". Rules with relativepath patterns (url: "*/fun"),do work, so you can use URLs likehttp://localhost/fun/mobile to reach instances. The server reports an error inthe log stream if you try to start an application with adispatch.yaml filethat contains host-based rules.

Use Cloud Trace

Cloud Trace is useful for understanding how requests propagate through yourapplication. You can inspect detailed latency information for a single requestor view aggregate latency for your entire application.

To view trace details in Cloud Trace, you can followFind and explore traces.In theTrace explorer, you can use the filters tofilter by your specific App Engine service and version.