Command Line Interface¶
Installing Flask installs the flask script, a Click command line interface, in your virtualenv. Executed from the terminal, this script gives access to built-in, extension, and application-defined commands. The —help option will give more information about any commands and options.
Application Discovery¶
The flask command is installed by Flask, not your application; it must be told where to find your application in order to use it. The —app option is used to specify how to load the application.
While —app supports a variety of options for specifying your application, most use cases should be simple. Here are the typical values:
The name “app” or “wsgi” is imported (as a “.py” file, or package), automatically detecting an app ( app or application ) or factory ( create_app or make_app ).
The given name is imported, automatically detecting an app ( app or application ) or factory ( create_app or make_app ).
—app has three parts: an optional path that sets the current working directory, a Python file or dotted import path, and an optional variable name of the instance or factory. If the name is a factory, it can optionally be followed by arguments in parentheses. The following values demonstrate these parts:
Sets the current working directory to src then imports hello .
Imports the path hello.web .
Uses the app2 Flask instance in hello .
The create_app factory in hello is called with the string ‘dev’ as the argument.
If —app is not set, the command will try to import “app” or “wsgi” (as a “.py” file, or package) and try to detect an application instance or factory.
Within the given import, the command looks for an application instance named app or application , then any application instance. If no instance is found, the command looks for a factory function named create_app or make_app that returns an instance.
If parentheses follow the factory name, their contents are parsed as Python literals and passed as arguments and keyword arguments to the function. This means that strings must still be in quotes.
Run the Development Server¶
The run command will start the development server. It replaces the Flask.run() method in most cases.
$ flask --app hello run * Serving Flask app "hello" * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
Do not use this command to run your application in production. Only use the development server during development. The development server is provided for convenience, but is not designed to be particularly secure, stable, or efficient. See Deploying to Production for how to run in production.
If another program is already using port 5000, you’ll see OSError: [Errno 98] or OSError: [WinError 10013] when the server tries to start. See Address already in use for how to handle that.
Debug Mode¶
In debug mode, the flask run command will enable the interactive debugger and the reloader by default, and make errors easier to see and debug. To enable debug mode, use the —debug option.
$ flask --app hello run --debug * Serving Flask app "hello" * Debug mode: on * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) * Restarting with inotify reloader * Debugger is active! * Debugger PIN: 223-456-919
Watch and Ignore Files with the Reloader¶
When using debug mode, the reloader will trigger whenever your Python code or imported modules change. The reloader can watch additional files with the —extra-files option. Multiple paths are separated with : , or ; on Windows.
$ flask run --extra-files file1:dirA/file2:dirB/ * Running on http://127.0.0.1:8000/ * Detected change in '/path/to/file1', reloading
The reloader can also ignore files using fnmatch patterns with the —exclude-patterns option. Multiple patterns are separated with : , or ; on Windows.
Open a Shell¶
To explore the data in your application, you can start an interactive Python shell with the shell command. An application context will be active, and the app instance will be imported.
$ flask shell Python 3.10.0 (default, Oct 27 2021, 06:59:51) [GCC 11.1.0] on linux App: example [production] Instance: /home/david/Projects/pallets/flask/instance >>>
Use shell_context_processor() to add other automatic imports.
Environment Variables From dotenv¶
The flask command supports setting any option for any command with environment variables. The variables are named like FLASK_OPTION or FLASK_COMMAND_OPTION , for example FLASK_APP or FLASK_RUN_PORT .
Rather than passing options every time you run a command, or environment variables every time you open a new terminal, you can use Flask’s dotenv support to set environment variables automatically.
If python-dotenv is installed, running the flask command will set environment variables defined in the files .env and .flaskenv . You can also specify an extra file to load with the —env-file option. Dotenv files can be used to avoid having to set —app or FLASK_APP manually, and to set configuration using environment variables similar to how some deployment services work.
Variables set on the command line are used over those set in .env , which are used over those set in .flaskenv . .flaskenv should be used for public variables, such as FLASK_APP , while .env should not be committed to your repository so that it can set private variables.
Directories are scanned upwards from the directory you call flask from to locate the files.
The files are only loaded by the flask command or calling run() . If you would like to load these files when running in production, you should call load_dotenv() manually.
Setting Command Options¶
Click is configured to load default values for command options from environment variables. The variables use the pattern FLASK_COMMAND_OPTION . For example, to set the port for the run command, instead of flask run —port 8000 :
$ export FLASK_RUN_PORT=8000 $ flask run * Running on http://127.0.0.1:8000/