flask-alembic

library3.2.0pypypi✓ verified 87d ago

Integrates Alembic database migrations with Flask applications. Current stable version 3.2.0, released 2025-10-15. Supports Flask-SQLAlchemy, Flask-SQLAlchemy-Lite, and plain SQLAlchemy. Python >=3.10 required.

database web-framework

pip install flask-alembic

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · FLASK-ALEMBIC

flask-alembic

databasepythonv3.2.0

Install

4.3s avg

Import

1299ms

Disk

50MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.2.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.346s · 50.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.3s · import 1.252s · 49MB

50MB installed

● package 50MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Alembic

✓ from flask_alembic import Alembic

✗ from flask_alembic import FlaskAlembic

Old wrapper name before 3.0, now removed

Initialize Alembic, create first migration, and apply it.

from flask import Flask from flask_sqlalchemy import SQLAlchemy from flask_alembic import Alembic app = Flask(__name__) app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db' db = SQLAlchemy(app) alembic = Alembic(app) with app.app_context(): alembic.init() alembic.revision('Initial migration') alembic.upgrade()

Debug

Known issues

breakingFlask-Alembic 3.0 dropped support for Python 2 and Python <3.8. Upgrade to Python 3.8+.

fix

Update Python to 3.8+ and pip install flask-alembic>=3.0

affects: <3.0.0

breakingThe `FlaskAlembic` class was removed in 3.0. Use `Alembic` instead.

fix

Change import to `from flask_alembic import Alembic` and instantiate `Alembic(app)`

affects: <3.0.0

gotchaWhen using multiple databases, you must specify which metadata to associate with each database in the `Alembic` constructor.

fix

Pass `metadatas` dict to `Alembic(app, metadatas={'db1': metadata1})`

affects: >=3.1.0

gotchaThe Flask application context must be active for most `alembic` CLI commands (e.g., `flask db upgrade`).

fix

Use `flask db` commands only after configuring the Flask app (e.g., via `FLASK_APP` env var).

affects: all

deprecatedIn 3.1.0, the `command_name` constructor argument was deprecated. Use the default command name or override via config.

fix

Remove `command_name` from Alembic() call.

affects: 3.1.0

Errors

Common errors & fixes

ImportError: cannot import name 'FlaskAlembic' from 'flask_alembic'

FlaskAlembic was removed in 3.0; use Alembic instead.

fix

Replace `from flask_alembic import FlaskAlembic` with `from flask_alembic import Alembic`.

flask db init fails with 'This environment only supports SQLite'

Alembic checks are overly strict for non-SQLite databases when using custom env.py.

fix

Ensure your custom env.py imports your SQLAlchemy models and sets `target_metadata` correctly.

RuntimeError: Working outside of application context.

Alembic or Flask commands executed without Flask app context.

fix

Wrap code in `with app.app_context():` or use `flask shell` to run commands interactively.

Upgrade

Version history

3.2.0latest on PyPI · released Nov 17, 2025

Audit

Dependencies

FlaskrequiredRequired: core Flask integration

Flask-SQLAlchemyoptionalCommon but optional: if using Flask-SQLAlchemy extension

Flask-SQLAlchemy-LiteoptionalAlternative to Flask-SQLAlchemy

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/pallets-eco/flask-alembic ↗

packagehttps://pypi.org/project/flask-alembic/ ↗

docshttps://flask-alembic.readthedocs.io ↗

changeloghttps://flask-alembic.readthedocs.io/page/changes/ ↗