Flask framework

The Flask extension streamlines the process of building Flask application rocks.

It facilitates the installation of Flask application dependencies, including Gunicorn, inside the rock. Additionally, it transfers your project files to /flask/app within the rock (/app on Ubuntu 26.04 LTS). By default, the system foundation, or base, is set as bare to generate a lightweight image.

Note

The Flask extension is compatible with the bare, ubuntu@22.04, ubuntu@24.04 and ubuntu@26.04 bases. Support for Ubuntu 26.04 LTS is experimental.

Part names added by the extension vary by Ubuntu version. On Ubuntu 22.04 LTS and Ubuntu 24.04 LTS, write extension/part. On Ubuntu 26.04 LTS, write extension.part. For rocks with base: bare, follow the convention for the configured build-base.

The Flask extension supports both synchronous and asynchronous Gunicorn workers.

Use the extension

Declare the extension in rockcraft.yaml:

rockcraft.yaml
extensions:
  - flask-framework

You can generate this project file by running rockcraft init --profile flask-framework in the application’s directory. To inspect the parts, services, and other configuration contributed by the extension, run rockcraft expand-extensions in the same directory as the rockcraft.yaml file.

Project requirements

There are 2 requirements to be able to use the flask-framework extension:

  1. There must be a requirements.txt or pyproject.toml file in the root of the project with Flask declared as a dependency. On Ubuntu 26.04 LTS, you can use a uv project instead, in which case the extension doesn’t check for this dependency.

  2. The project must include a Web Server Gateway Interface (WSGI) app. The extension looks for a global variable named app or application in these files, in this order:

    • app.py, then main.py, at the root of the project.

    • __init__.py, then app.py, then main.py in each of the app and src directories, and in the directory named like the name in the project file, with any - replaced by _.

    If no such variable exists, the extension looks for an application factory function named create_app or make_app in the same files and calls it at startup.

For the project to make use of asynchronous Gunicorn workers:

  • The requirements.txt or pyproject.toml file must include gevent as a dependency.

uv projects

The extension doesn’t support uv projects on these bases. It builds the application with the Python plugin and installs dependencies from requirements.txt or pyproject.toml.

If both a uv.lock and a pyproject.toml file are present in the project root, the extension builds the application with the uv plugin instead of the Python plugin. It installs dependencies from the lockfile with uv sync. Gunicorn is injected after the build step regardless of the lockfile contents. In this case, a requirements.txt file is not required.

The uv plugin requires both files, meaning the application will fail to pack if uv.lock is present but pyproject.toml is missing. If only pyproject.toml is present, the extension falls back to the Python plugin.

App dependencies

The stage-packages key specifies all additional dependencies. If the Flask app has its own special dependencies, this key must declare them.

The following example specifies the libpq-dev package. For rocks built on the bare base, list slices instead. Instead of libpq-dev, for example, you’d list libpq5_libs.

rockcraft.yaml
parts:
  flask-framework/dependencies:
    stage-packages:
      # list required packages or slices for your Flask app below.
      - libpq-dev
rockcraft.yaml
parts:
  flask-framework.dependencies:
    stage-packages:
      # list required packages or slices for your Flask app below.
      - libpq-dev

StatsD exporter

A StatsD exporter is installed alongside the Gunicorn server to record server metrics. Some of the Gunicorn-provided metrics are mapped to new names:

Gunicorn metric

StatsD metric

gunicorn.request.status.*

flask_response_code

gunicorn.requests

flask_requests

gunicorn.request.duration

flask_request_duration

The exporter listens on localhost at port 9125. You can push your own metrics to the exporter using any StatsD client. This snippet from an example Flask app uses pystatsd as a client:

import statsd
c = statsd.StatsClient('localhost', 9125)
c.incr('my_counter')

See the StatsD exporter documentation for more information.

Gunicorn worker selection

If gevent is listed as a dependency in either the requirements.txt or pyproject.toml file, Rockcraft sets the Gunicorn worker to gevent in the Pebble plan. Otherwise, it uses sync.

When the project instead needs synchronous workers, you can override the worker type by adding --args flask sync to the Docker command that launches the rock:

docker run --name flask-container -d -p 8000:8000 flask-image:1.0 \
--args flask sync

Included or excluded files

Some files, if they exist, are included by default in the rock. These include: app, app.py, main.py, src, migrate, migrate.sh, migrate.py, static, templates. Any other file or directory, such as an additional Python module that your app imports, isn’t included unless you list it in prime. If none of these exist and prime isn’t set, the whole project is included, except node_modules, .git, .yarn and *.rock.

The prime key specifies the files to be included or excluded from the rock upon rockcraft pack. Prefix each entry with flask/app/ (Ubuntu 22.04 LTS and Ubuntu 24.04 LTS) or app/ (Ubuntu 26.04 LTS), followed by the path relative to the project root. For example:

rockcraft.yaml
parts:
  flask-framework/install-app:
    prime:
      - flask/app/.env
      - flask/app/app.py
      - flask/app/webapp
      - flask/app/templates
      - flask/app/static
rockcraft.yaml
parts:
  flask-framework.install-app:
    prime:
      - app/.env
      - app/app.py
      - app/webapp
      - app/templates
      - app/static

The prime key supports glob patterns to define the list of files. See Filesets for the various ways you can specify files in your rock.

Adding the prime key to the project file overrides the default files to be included. Files are excluded from the rock by defining prime and omitting the file to be excluded.