How to Run a Flask App Successfully: Complete Guide from Development to Production

Set the FLASK_APP environment variable to your Python file or application factory function, then execute flask run to start the development server on http://127.0.0.1:5000.

Flask is a lightweight WSGI web framework maintained by the Pallets Projects that builds applications by instantiating the Flask class. Understanding how to run a Flask app successfully requires knowledge of the CLI discovery mechanism implemented in src/flask/cli.py and the core application structure defined in src/flask/app.py. This guide covers the exact steps to launch your application in both development and production environments using the official pallets/flask source code.

Creating Your Flask Application

Before running your app, you must create a valid Flask instance. The framework supports two primary patterns for application creation, both implemented in src/flask/app.py.

The Minimal Single-File Pattern

For simple projects, create a file named app.py:

# app.py

from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello, World!"

The Flask class constructor initializes the WSGI application, while the route decorator provides a thin wrapper around the add_url_rule method for registering endpoints.

The Application Factory Pattern

For larger projects, defer application creation using a factory function in myproject/__init__.py:

from flask import Flask

def create_app():
    app = Flask(__name__)
    app.config.from_mapping(SECRET_KEY="dev")
    
    @app.route("/")
    def index():
        return "Welcome to the factory app!"
    
    return app

This pattern allows lazy loading of extensions and simplifies testing with different configurations, as the Flask constructor in src/flask/app.py supports deferred initialization.

Starting the Development Server

Using the Flask CLI

The Flask command-line interface defined in src/flask/cli.py reads the FLASK_APP environment variable to locate and import your application object.

For the single-file pattern:

export FLASK_APP=app.py
export FLASK_ENV=development
flask run

For the factory pattern, use the colon syntax:

export FLASK_APP="myproject:create_app"
flask run

The CLI detects the colon separator, imports the module, calls the factory function, and serves the returned instance. By default, the development server binds to 127.0.0.1:5000.

Customizing Host and Port

Override default network settings using environment variables:

export FLASK_RUN_HOST=0.0.0.0
export FLASK_RUN_PORT=8080
flask run

Or pass arguments directly:

flask run --host 0.0.0.0 --port 8080 --no-debugger

The --no-debugger flag explicitly disables the interactive debugger, which is essential when exposing the server to external networks.

Understanding the Application Discovery Process

When you execute flask run, the CLI performs a specific initialization sequence:

1. Locate the application: Imports the module specified in FLASK_APP and searches for an instance named app or executes the factory function when using the module:factory syntax.
2. Initialize the environment: Sets FLASK_ENV=development automatically if undefined, which enables the interactive debugger and auto-reloader managed through flask.signals.
3. Load configuration: Processes settings from the app.config object (defined in src/flask/config.py) via methods like from_object or from_pyfile.
4. Prepare context: Initializes the AppContext and RequestContext classes from src/flask/ctx.py to manage thread-local variables like flask.g and flask.request.
5. Start the server: Invokes the Werkzeug development server through the internal app.run() method.

Running Flask in Production

Using Production WSGI Servers

Do not use flask run for production deployments. Instead, expose the wsgi_app attribute to a dedicated WSGI server:

gunicorn "myproject:create_app()"

The parentheses instruct Gunicorn to call the factory immediately. The production server then uses the app.wsgi_app callable defined in src/flask/app.py to handle requests, bypassing the development server's single-threaded limitations.

Configuration and Environment Variables

Flask's configuration system in src/flask/config.py recognizes several key environment variables:

• FLASK_APP: Path to the file or factory function (e.g., app.py or myproject:create_app).
• FLASK_ENV: Controls environment-specific behavior; set to development (default) or production.
• FLASK_DEBUG: Enables debug mode independently of the environment setting.
• FLASK_RUN_HOST and FLASK_RUN_PORT: Override the default 127.0.0.1:5000 binding.

When FLASK_ENV=development, Flask automatically enables the reloader and debugger through signal handlers defined in src/flask/signals.py.

Summary

• Set FLASK_APP to your Python file or factory function before executing flask run to start the development server.
• Use the application factory pattern (create_app) for complex projects to enable flexible configuration and testing.
• Core architecture relies on src/flask/app.py for the Flask class, src/flask/cli.py for command-line discovery, and src/flask/config.py for settings management.
• Never use flask run in production; deploy using Gunicorn or similar WSGI servers that consume app.wsgi_app.
• Default security binds to 127.0.0.1 with the debugger enabled only in development mode.

Frequently Asked Questions

What should I set FLASK_APP to if using an application factory?

Set FLASK_APP to the module path followed by a colon and the factory name, such as myproject:create_app. The Flask CLI in src/flask/cli.py parses this syntax, imports the module, calls the factory, and serves the returned Flask instance.

Why does Flask default to 127.0.0.1 instead of 0.0.0.0?

The default binding to 127.0.0.1 in src/flask/cli.py prevents accidental exposure of the development server to external networks, protecting against security risks since the interactive debugger allows arbitrary code execution. Use --host 0.0.0.0 only when explicitly required.

How do I disable the debugger but keep auto-reload?

Pass the --no-debugger flag to flask run or set FLASK_DEBUG=0. This prevents the interactive debugger from rendering tracebacks while maintaining the reloader functionality useful during development.

Can I use flask run for production deployments?

No. The server started by flask run is designed for development only and lacks the performance and security features required for production. Deploy using a production-grade WSGI server like Gunicorn, uWSGI, or mod_wsgi that imports your application from src/flask/app.py and utilizes the wsgi_app interface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}