Google App Engine

How to Deploy a Flask App on Google App Engine

Deploy a Flask app to App Engine: write main.py and app.yaml, test locally, run gcloud app deploy, then check logs and avoid common mistakes.

On this page
  1. What you need
  2. Project layout
  3. Step 1: Test locally
  4. Step 2: Write main.py
  5. Step 3: Write requirements.txt
  6. Step 4: Configure app.yaml
  7. Step 5: Create the App Engine app
  8. Step 6: Deploy and open the app
  9. Step 7: Check the logs
  10. Troubleshooting
  11. Use a custom entrypoint
  12. Production notes
  13. Next steps

To deploy a Flask app on App Engine Standard, add a main.py file that exposes a WSGI object named app, list your packages in requirements.txt, describe the runtime in app.yaml, and run gcloud app deploy. App Engine installs your dependencies, runs the app with gunicorn, and serves it at an appspot.com URL.

What you need

  • A Google Cloud project with billing enabled.
  • The gcloud CLI installed, with gcloud init completed.
  • Python 3 on your computer, with a virtual environment for the project.
  • The Cloud Build API enabled. Deployment uses Cloud Build, and the command will prompt you to enable it if it is off.

Project layout

my-flask-app/
├── main.py
├── requirements.txt
├── app.yaml
├── .gcloudignore
└── static/
    └── style.css

The static folder is optional. It is included here to show how App Engine serves static files.

Step 1: Test locally

Create a virtual environment, install the requirements, and start the development server:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
flask --app main run

Open http://127.0.0.1:5000 to confirm the app works. Test locally before you deploy, because a deployment takes minutes and a local error takes seconds to find.

Step 2: Write main.py

App Engine looks for a WSGI object named app in main.py:

from flask import Flask

app = Flask(__name__)


@app.route("/")
def home():
    return "<h1>Hello from Flask on App Engine</h1>"


@app.route("/about")
def about():
    return "<p>This app runs on the App Engine Standard environment.</p>"


if __name__ == "__main__":
    # Local testing only. App Engine serves `app` with gunicorn and ignores this block.
    app.run(host="127.0.0.1", port=8080, debug=False)

Keep debug=False. Flask’s debugger can run code if anyone can reach it, so it should never be enabled on a public server.

Step 3: Write requirements.txt

List every package the app imports:

Flask

With the default entrypoint, App Engine runs gunicorn for you, so you don’t need to list it. In a real project, pin exact versions so the deployed app matches what you tested.

Step 4: Configure app.yaml

app.yaml sets the runtime, the instance size, the scaling limits, and how requests are routed:

runtime: python313
instance_class: F1

automatic_scaling:
  max_instances: 2

handlers:
  - url: /static
    static_dir: static
  - url: /.*
    script: auto

The /static handler serves files from the static folder directly, without running your Flask code or using your app’s instance time. Every other request goes to the Flask app.

Runtime names change over time, so check the supported runtimes list before you deploy. Do not put secrets in app.yaml. Values there are not secret, so store passwords and API keys in Secret Manager.

Step 5: Create the App Engine app

Run this once per project:

gcloud init
gcloud app create --region=us-central1

Choose a region close to your users. The region is permanent for the project’s App Engine app.

Step 6: Deploy and open the app

From the project folder, run:

gcloud app deploy
gcloud app browse

gcloud app deploy uploads the project, builds it with Cloud Build, and starts a new version. gcloud app browse opens the app in your browser.

Step 7: Check the logs

Watch the logs for errors while you test:

gcloud app logs tail -s default

Troubleshooting

  • ModuleNotFoundError in the logs. The package is missing from requirements.txt. Installing it locally is not enough, because App Engine installs only what the file lists.
  • The app fails to start. Check that main.py defines app and that the name matches. A different name is only allowed if you set a custom entrypoint.
  • Writes to files fail. Only /tmp is writable in the Standard environment, and it is held in memory. Store durable files in Cloud Storage.
  • Your app doesn’t listen on the expected port. App Engine sets the PORT environment variable to 8080. A custom entrypoint must bind to $PORT.
  • The upload is slow or huge. A venv folder was uploaded. Add it to .gcloudignore.

A .gcloudignore file excludes local files from the upload:

venv/
.git/
__pycache__/

Use a custom entrypoint

If you need control over gunicorn’s worker count or timeouts, set the entrypoint in app.yaml:

entrypoint: gunicorn -b :$PORT main:app

Then add gunicorn to requirements.txt, because a custom entrypoint is not installed for you.

Production notes

  • Keep debug off and never call app.run() in production.
  • Keep secrets out of app.yaml. Use Secret Manager.
  • Test a new version before you send it traffic. Run gcloud app deploy --no-promote to deploy a version without routing traffic to it, test it, then switch traffic with gcloud app services set-traffic.
  • Remove old versions. gcloud app deploy does not delete old versions, and a version that still receives traffic keeps costing money.

For the free quota, instance limits, and other cost controls, see the pricing guide.

Next steps

If you are new to App Engine, start with the App Engine tutorial, which covers project setup, Cloud Storage, and cleanup. To pick an environment for your app, read the Standard vs Flexible comparison. If you are considering Cloud Run for a containerized app, the App Engine vs Cloud Run guide explains the trade-offs. For how the platform routes requests, see the architecture guide.

The complete guide to google app engine

Google App Engine Tutorial for Beginners
Read the guide

Keep exploring

Guides from other topics

All topics →