flask-alembic

3.2.0 verified Mon Apr 27 auth: no python

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.

pip install flask-alembic

Common errors

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

cause FlaskAlembic was removed in 3.0; use Alembic instead.

fix

Replace from flask_alembic import FlaskAlembic with from flask_alembic import Alembic.

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

cause 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.

error RuntimeError: Working outside of application context. ↓

cause 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.

Warnings

breaking Flask-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

breaking The `FlaskAlembic` class was removed in 3.0. Use `Alembic` instead. ↓

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

gotcha When 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})`

gotcha The 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).

deprecated In 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.

Imports

Alembic

wrong

from flask_alembic import FlaskAlembic

correct

from flask_alembic import Alembic

Old wrapper name before 3.0, now removed

Quickstart

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()