How to deploy a Flask app on Replit

Start a new Python project on Replit or ask Agent to create a Flask web application. Your project needs at minimum an app.py file, a requirements.txt listing Flask and gunicorn, and a .replit configuration file. Organize larger projects with a standard Flask structure using templates/, static/, and a dedicated config module. Install Flask and gunicorn from the Shell with pip install flask gunicorn, then freeze the dependencies to requirements.txt.

1# In the Shell terminal
2pip install flask gunicorn
3pip freeze > requirements.txt

Create your main Flask application file. The critical configuration for Replit is binding the server to 0.0.0.0 instead of the default 127.0.0.1 or localhost. Without this, Replit cannot detect the running server and the deployment fails with 'hostingpid1: an open port was not detected.' Also read the port from the PORT environment variable since Replit assigns it dynamically in production. Add a health check route at the root path that responds quickly, as the deployment health check must complete within 5 seconds.

1# app.py
2import os
3from flask import Flask, jsonify
4
5app = Flask(__name__)
6
7@app.route('/')
8def health_check():
9    return jsonify({
10        'status': 'ok',
11        'environment': 'production' if os.getenv('REPLIT_DEPLOYMENT') == '1' else 'development'
12    })
13
14@app.route('/api/hello')
15def hello():
16    return jsonify({'message': 'Hello from Flask on Replit!'})
17
18if __name__ == '__main__':
19    port = int(os.getenv('PORT', 5000))
20    debug = os.getenv('REPLIT_DEPLOYMENT') != '1'
21    app.run(host='0.0.0.0', port=port, debug=debug)

Flask's built-in server handles one request at a time and is not designed for production traffic. Gunicorn is a production-grade WSGI server that runs multiple worker processes to handle concurrent requests. Create a gunicorn configuration file to set the number of workers, bind address, and timeout. The number of workers should typically be 2 to 4 for Replit's resource constraints. Higher counts consume more RAM and may cause out-of-memory errors.

1# gunicorn.conf.py
2import os
3
4bind = f"0.0.0.0:{os.getenv('PORT', '5000')}"
5workers = 2
6threads = 2
7timeout = 120
8accesslog = '-'
9errorlog = '-'
10loglevel = 'info'

Open the .replit file and set up both development and deployment configurations. The run command starts Flask's development server for local testing. The [deployment] section uses gunicorn for production. The build command installs dependencies from requirements.txt. Set the deployment target to cloudrun for Autoscale deployments. Configure the port mapping with localPort matching your Flask port and externalPort set to 80.

1entrypoint = "app.py"
2run = "python app.py"
3
4modules = ["python-3.11:v18-20230807-322e88b"]
5
6[nix]
7channel = "stable-24_05"
8packages = ["python311", "python311Packages.pip"]
9
10[[ports]]
11localPort = 5000
12externalPort = 80
13
14[deployment]
15build = ["pip", "install", "-r", "requirements.txt"]
16run = ["gunicorn", "--config", "gunicorn.conf.py", "app:app"]
17deploymentTarget = "cloudrun"

Store all sensitive values like API keys, database credentials, and secret keys in Replit Secrets. Open Tools > Secrets and add each key-value pair. Flask apps commonly need a SECRET_KEY for session security and any external API keys. After adding workspace secrets, open the Deployments pane and add the same secrets there. This is the most common cause of Flask deployment failures: secrets that work in development return None in production because they were not added to the deployment configuration.

1# app.py - Reading secrets
2import os
3
4app.config['SECRET_KEY'] = os.getenv('FLASK_SECRET_KEY', 'dev-key-change-me')
5
6# Validate required secrets at startup
7required_secrets = ['FLASK_SECRET_KEY', 'DATABASE_URL']
8for secret in required_secrets:
9    if not os.getenv(secret):
10        if os.getenv('REPLIT_DEPLOYMENT') == '1':
11            raise RuntimeError(
12                f'{secret} is not set. Add it in Deployments > Secrets.'
13            )

Click the Deploy button in the Deployments pane and select Autoscale. Configure CPU and RAM settings, then click Deploy. Watch the deployment logs for errors. The most common errors are: 'hostingpid1: an open port was not detected' (server not bound to 0.0.0.0 or wrong port), health check timeout (root route takes more than 5 seconds), and 'ModuleNotFoundError' (dependency not in requirements.txt). If the deployment fails, check the Logs tab in the Deployments pane for the exact error message. For complex Flask deployments with multiple services, teams can consult RapidDev for architecture guidance.