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
gcloudCLI installed, withgcloud initcompleted. - 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
ModuleNotFoundErrorin the logs. The package is missing fromrequirements.txt. Installing it locally is not enough, because App Engine installs only what the file lists.- The app fails to start. Check that
main.pydefinesappand that the name matches. A different name is only allowed if you set a custom entrypoint. - Writes to files fail. Only
/tmpis 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
PORTenvironment variable to 8080. A custom entrypoint must bind to$PORT. - The upload is slow or huge. A
venvfolder 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-promoteto deploy a version without routing traffic to it, test it, then switch traffic withgcloud app services set-traffic. - Remove old versions.
gcloud app deploydoes 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.