Install & Compatibility
Where this runs
tested against v0.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.746s · 25.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.5s · import 0.692s · 27MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FlatPages
✓ from flask_flatpages import FlatPages
Page
✓ from flask_flatpages import Page
This quickstart initializes a Flask application with Flask-FlatPages, serving flat markdown pages. It demonstrates how to configure the extension, list all available pages, and retrieve a specific page based on its path. It also includes boilerplate to create dummy files, allowing the example to run out-of-the-box.
import os
from flask import Flask, render_template
from flask_flatpages import FlatPages
# Configuration
DEBUG = True
FLATPAGES_AUTO_RELOAD = DEBUG
FLATPAGES_EXTENSION = '.md'
FLATPAGES_ROOT = 'pages'
FLATPAGES_ENCODING = 'utf-8'
app = Flask(__name__)
app.config.from_object(__name__)
flatpages = FlatPages(app)
# Routes
@app.route('/')
def index():
# All pages are available via flatpages iterable
return render_template('index.html', pages=flatpages)
@app.route('/<path:path>/')
def page(path):
# Get a specific page, or 404
page = flatpages.get_or_404(path)
return render_template('page.html', page=page)
if __name__ == '__main__':
# Create dummy content and templates for runnable quickstart
if not os.path.exists(FLATPAGES_ROOT):
os.makedirs(FLATPAGES_ROOT)
with open(os.path.join(FLATPAGES_ROOT, 'about.md'), 'w') as f:
f.write('---\ntitle: About Us\ndate: 2024-05-15\n---\n\n# Welcome to our About Page\n\nThis is an example flat page managed by Flask-FlatPages.')
if not os.path.exists('templates'):
os.makedirs('templates')
with open('templates/index.html', 'w') as f:
f.write('<!doctype html>\n<html>\n<head><title>FlatPages Index</title></head>\n<body>\n <h1>FlatPages Example</h1>\n <ul>\n {% for page in pages %}\n <li><a href="{{ url_for("page", path=page.path) }}">{{ page.meta.get("title", page.path) }}</a></li>\n {% endfor %}\n </ul>\n</body>\n</html>')
with open('templates/page.html', 'w') as f:
f.write('<!doctype html>\n<html>\n<head><title>{{ page.meta.get("title", "Page") }}</title></head>\n<body>\n <h1>{{ page.meta.get("title", "") }}</h1>\n {{ page.html|safe }}\n</body>\n</html>')
# Run the Flask app
app.run(port=5000, debug=DEBUG)
Debug
Known issues
deprecatedDirectly accessing the `FlatPages.app` attribute is deprecated. In versions 0.9 and up, it now wraps `flask.current_app`, and attempting to access it outside of an active Flask application context will raise a `RuntimeError`.fixMigrate to using `flask.current_app` directly where possible, or ensure an application context is always pushed when `FlatPages.app` is accessed.
affects: 0.8.3+
breakingSupport for older Python versions has been progressively dropped. Python 2.7 support was removed in v0.8.2. Python 3.7 and earlier are no longer supported as of v0.9.0, requiring Python 3.8+.fixEnsure your Python development and deployment environments are running Python 3.8 or newer to use current versions of Flask-FlatPages.
affects: 0.8.2+, 0.9.0+
gotchaMetadata parsing was improved in v0.8.0 to be more consistent with other 'FlatPage' style libraries and less strict for pages without explicit metadata. While generally an enhancement, review your existing flat page metadata to ensure it's parsed as expected, especially if you relied on previous implicit behaviors.fixNo direct code changes are typically required. Test existing pages with v0.8.0+ to confirm metadata extraction remains correct.
affects: 0.8.0+
breakingMultiple releases have included updates to underlying dependencies or dropped support for older Python versions to address security vulnerabilities. Running outdated versions can expose your application to known security risks.fixAlways update Flask-FlatPages and its dependencies (e.g., Flask, Markdown) to the latest stable versions. Regularly review your project's dependencies for security alerts.
affects: All versions prior to 0.9.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flask.ext.flatpages'
The `flask.ext` namespace was deprecated in Flask 0.9. Flask extensions are now imported directly from their package names (e.g., `flask_flatpages` instead of `flask.ext.flatpages`).
fixUpdate your import statement to `from flask_flatpages import FlatPages`.
jinja2.exceptions.TemplateNotFound: page.html
This error occurs when Flask's Jinja2 templating engine cannot find the HTML template file specified in your `render_template` call, which is commonly `page.html` or a similar wrapper template used to display the content of a `flask-flatpages` page. The template file is either missing, located in an incorrect directory, or has a typo in its name. By default, Flask looks for templates in a folder named `templates` in your application's root directory.
fixEnsure that your `page.html` (or equivalent) template file exists inside a `templates` directory at the root of your Flask application. Also, verify that the `render_template` call correctly references this file, e.g., `render_template('page.html', page=page)`. AttributeError: 'FlatPages' object has no attribute 'get'
This error indicates that you are attempting to call a method or access an attribute named 'get' on an object that is not an instance of `FlatPages` or an object that has been incorrectly initialized or overwritten. In `flask-flatpages`, the `FlatPages` instance itself usually doesn't have a `.get()` method; rather, you might be trying to access a page using `pages.get(path)` where `pages` is expected to be an instance of `FlatPages` and `get` is a method on it. The documentation shows `FlatPages.get('foo')` as a way to force loading, but the more common usage is iterating over `pages` and then accessing attributes of individual `Page` objects. Or, if 'get' is called on a `Page` object, `Page` objects do not have a `.get()` method.
fixEnsure that the variable you are calling `.get()` on is the `FlatPages` instance itself and that you are using it to retrieve a `Page` object, for example: `page = pages.get(path)` or `page = pages.get_or_404(path)`. If you are iterating over pages, ensure you are accessing properties like `page.html` or `page.meta` correctly on the individual `Page` objects.
Jinja2 expressions in flatpages (e.g., {{ 1 + 1 }}) are not rendered, showing literally.
By default, when `flask-flatpages` renders a page's content, it often passes the processed HTML directly into a Jinja2 template using `{{ page.html | safe }}`. The `| safe` filter tells Jinja2 to treat the content as safe HTML, preventing it from re-evaluating any Jinja2 expressions present within the flatpage's body. Thus, Jinja2 expressions within the flatpage's Markdown or HTML will be displayed as literal text rather than being processed.
fixIf you intend to use Jinja2 expressions inside your flatpages, you need a custom HTML renderer that pre-renders the Jinja2 in the flatpage body *before* Markdown processing, or a custom approach that allows for a second pass of Jinja2 rendering. A common workaround is to use a custom `FLATPAGES_HTML_RENDERER` that explicitly calls Jinja2's `render_template_string` on the flatpage's body before or after Markdown conversion.
Upgrade
Version history
0.9.0latest on PyPI · released Dec 31, 2025
Audit
Dependencies
FlaskrequiredCore web framework dependency.
MarkdownoptionalRequired for Markdown content rendering, common but can be replaced with custom renderers.
PygmentsoptionalOptional for code highlighting within Markdown pages.