Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 72 ยท Getting Started

Project Layout and the flask Command

Organize a Flask project from a single file to a package with an app factory. Learn the flask command, --debug, .flaskenv, custom CLI commands and the instance folder.

A Flask project can start as one file and grow into a package with dozens of modules. Flask does not force a structure on you, which is a strength, but it also means you need to choose one. In this lesson you see the common layouts, meet the flask command-line tool and learn where configuration and secrets belong.

Most of what follows is about files on disk, so the layouts are shown as read-only listings. The code that matters, such as the factory function, custom commands and configuration, runs live.

Layout 1: a single file

For experiments, small tools and the first chapters of this course, one file is enough:

TEXT
hello-flask/
โ”œโ”€โ”€ app.py
โ”œโ”€โ”€ requirements.txt
โ””โ”€โ”€ .venv/            (not committed)

Everything lives in app.py: the Flask object, the views and any helper functions. It is quick to write and easy to read, but once you add templates, a database and tests it gets crowded.

Layout 2: templates and static files

The next step adds two folders that Flask looks for next to your app file by default:

TEXT
hello-flask/
โ”œโ”€โ”€ app.py
โ”œโ”€โ”€ templates/        (Jinja HTML templates)
โ”‚   โ””โ”€โ”€ index.html
โ”œโ”€โ”€ static/           (CSS, JavaScript, images)
โ”‚   โ””โ”€โ”€ style.css
โ””โ”€โ”€ requirements.txt

You will use templates/ in the Jinja lessons and static/ in Static Files and Assets. Flask finds them because of the argument you pass to Flask(__name__): the name tells Flask which module your app lives in, and from that it works out the folder to search.

Layout 3: a package with an application factory

Larger apps become a package: a folder with an __init__.py that builds the application inside a function, called an application factory.

TEXT
bookshop/
โ”œโ”€โ”€ pyproject.toml
โ”œโ”€โ”€ .flaskenv
โ”œโ”€โ”€ .gitignore
โ”œโ”€โ”€ instance/                 (not committed: local config, SQLite files)
โ”œโ”€โ”€ bookshop/
โ”‚   โ”œโ”€โ”€ __init__.py           (create_app)
โ”‚   โ”œโ”€โ”€ models.py
โ”‚   โ”œโ”€โ”€ auth.py               (a blueprint)
โ”‚   โ”œโ”€โ”€ catalog.py            (another blueprint)
โ”‚   โ”œโ”€โ”€ templates/
โ”‚   โ””โ”€โ”€ static/
โ””โ”€โ”€ tests/
    โ”œโ”€โ”€ conftest.py
    โ””โ”€โ”€ test_catalog.py
flowchart TD
    CMD["flask --app bookshop run"] --> F["bookshop/__init__.py<br/>create_app()"]
    F --> C["load configuration"]
    F --> E["set up extensions"]
    F --> B["register blueprints:<br/>auth, catalog"]
    B --> V["views, templates, static"]

The factory builds a complete application on demand, so tests and the server can each get their own instance.

The key idea is that no app object exists at import time. Instead, create_app() makes one when asked. The Application Factory lesson covers it fully; here is a small preview that you can run:

Python An application factory

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Two completely separate applications come from the same code, each with its own configuration. That is what makes the pattern useful for testing: every test can build a fresh app.

The flask command

Installing Flask also installs a command-line program called flask. It needs to know where your app is, which you give it with --app:

Terminal
flask --app app run                 # file app.py, variable app or create_app()
flask --app bookshop run --debug    # package bookshop, factory create_app()
flask --app "bookshop:create_app('dev')" run
flask --app app routes              # list every URL rule
flask --app app shell               # Python shell with app context

Useful points:

  • run starts the development server on 127.0.0.1:5000 by default. Add --port 8000 to change the port.
  • --debug enables the reloader and the interactive debugger. It is a development tool: anyone who can reach a debug server can run code on your machine.
  • routes prints the URL map, a handy way to check what you registered.
  • shell opens a Python session with the application context already pushed.

You can add your own commands to the flask tool with @app.cli.command(). Because the commands are built on the Click library, they accept arguments and options. The test runner lets you try them without a terminal:

Python A custom flask command

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

On your machine you would run flask --app app greet Ada --shout. Custom commands are the standard place for tasks like creating database tables or loading sample data.

.flaskenv and .env

Typing --app and --debug on every command gets tedious. If the python-dotenv package is installed, the flask command reads two files from the current folder before it starts:

  • .flaskenv: public settings for the flask command, committed to Git.
  • .env: private values such as secrets and passwords, never committed.
TEXT
# .flaskenv
FLASK_APP=bookshop
FLASK_DEBUG=1

With that file in place, a plain flask run is enough. The following stand-in shows what the tool does with such a file: it turns each KEY=value line into an environment variable, skipping blank lines and comments. This is plain Python, not Flask's own loader, but the idea is the same:

Python What .flaskenv does (a stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Real environment variables always win over the files, so a server can override a setting without editing anything.

The instance folder

Some files belong to one particular installation, not to your code: a SQLite database, uploaded files, a config file holding secrets. Flask reserves the instance folder for them. By default it is a folder called instance next to your package (or next to app.py), and it should be listed in .gitignore.

You switch on instance-relative configuration with one argument:

Python The instance folder and instance config

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In a real project you would put production settings in instance/config.py and leave defaults in code. The Configuration lesson goes further and shows environment variables as well. Note that the browser has no real project folder, so nothing is read here; the call returns False because the file does not exist.

Warning: Never commit secrets (SECRET_KEY, passwords, API tokens) to Git. Keep them in the instance folder or in environment variables, and add instance/ and .env to .gitignore.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where does Flask look for the templates folder by default?

    Flask uses the name you pass to Flask(name) to find your module, then looks for a templates folder beside it.
  2. 2. What is an application factory?

    A factory such as create_app() builds an application on demand, which allows separate configurations for development, testing and production.
  3. 3. Which command starts the dev server for the package bookshop with the debugger?

    The --app option names the application and the run command accepts --debug for the reloader and debugger.
  4. 4. What belongs in the .env file but not in .flaskenv?

    .flaskenv holds public settings for the flask command and is committed; .env holds private values and stays out of version control.
  5. 5. What is the instance folder for?

    The instance folder keeps data that varies per deployment and should not be committed, such as secrets and local databases.

Summary

  • Start with one file, add templates/ and static/, and move to a package with an application factory as the project grows.
  • create_app() builds an app on demand, so tests and servers each get a fresh, separately configured instance.
  • The flask command needs --app; run --debug, routes and shell are the everyday subcommands.
  • Add your own commands with @app.cli.command() and try them with app.test_cli_runner().
  • .flaskenv holds public settings, .env and the instance folder hold secrets, and neither of the latter belongs in Git.

Next: Routes and HTTP Methods, where the Routing and Views chapter begins.