alembic

library1.19.1pypypi✓ verified 26d ago

Database migration tool for SQLAlchemy. Manages schema versioning via migration scripts. Current version: 1.18.4 (Mar 2026). Tightly coupled to SQLAlchemy — version mismatch causes silent failures. SQLAlchemy 1.3 dropped in Alembic 1.15. Python 3.8 dropped in Alembic 1.15. The #1 footgun: autogenerate generates empty migrations when target_metadata is not correctly set in env.py.

database workflow

pip install alembic

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · ALEMBIC

alembic

databasepythonv1.19.1

Install

3.9s avg

Import

—

Disk

45MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.19.1 · 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 0.000s · 46.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.9s · import 0.000s · 44MB

45MB installed

● package 45MB

Code

Verified usage

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

env.py target_metadata

✓ # In alembic/env.py — MUST import your models for autogenerate to work from myapp.models import Base # import all models so metadata is populated target_metadata = Base.metadata # If models are in multiple files, import them all: from myapp.models.user import User from myapp.models.post import Post # then: target_metadata = Base.metadata

✗ # In alembic/env.py target_metadata = None # default — autogenerate generates EMPTY migrations

The single most common Alembic mistake. If target_metadata = None in env.py, autogenerate produces empty migration files. Must import your models and set target_metadata = Base.metadata.

alembic init + upgrade

✓ # CLI commands — run from project root alembic init alembic # create alembic directory alembic revision --autogenerate -m 'initial' # generate migration alembic upgrade head # apply all pending migrations alembic downgrade -1 # roll back one migration alembic history # show migration history alembic current # show current DB version

✗ # Wrong: running autogenerate before DB is up to date alembic revision --autogenerate -m 'add column' # fails if DB not at head

Must run 'alembic upgrade head' before running --autogenerate again. Error: 'Target database is not up to date' means DB is behind the migration chain.

Alembic setup and first migration workflow.

# 1. Install and init # pip install alembic sqlalchemy # alembic init alembic # 2. Edit alembic/env.py — add your models: # from myapp.models import Base # target_metadata = Base.metadata # 3. Edit alembic.ini — set database URL: # sqlalchemy.url = postgresql://user:pass@localhost/mydb # 4. Generate first migration # alembic revision --autogenerate -m 'initial schema' # 5. Apply migration # alembic upgrade head # Migration file (alembic/versions/xxx_initial_schema.py): from alembic import op import sqlalchemy as sa def upgrade(): op.create_table( 'users', sa.Column('id', sa.Integer, primary_key=True), sa.Column('username', sa.String(50), nullable=False), sa.Column('email', sa.String(120), nullable=False), ) def downgrade(): op.drop_table('users')

alembic --version

Debug

Known issues

breakingtarget_metadata = None in env.py causes autogenerate to produce completely empty migration files. This is the default after 'alembic init'. Must be changed to Base.metadata.

fix

In env.py: import your models then set target_metadata = Base.metadata

affects: all

breaking'Target database is not up to date' error when running --autogenerate. DB must be at head before generating new migrations.

fix

Run 'alembic upgrade head' first, then run --autogenerate.

affects: all

breakingSQLAlchemy 1.3 support dropped in Alembic 1.15. Python 3.8 support dropped in Alembic 1.15.

fix

Use SQLAlchemy >= 1.4 and Python >= 3.9 with Alembic 1.15+

affects: >= 1.15

gotchaAutogenerate cannot detect everything. It misses: stored procedures, views, partial indexes (pre-1.12), CHECK constraints, column defaults (in some cases). Always manually review generated migrations.

fix

Always run 'alembic check' and manually review generated migration files before applying.

affects: all

gotchaMultiple heads error: 'Multiple head revisions are present' when two migrations both point to the same parent. Happens when multiple developers generate migrations from the same base.

fix

Run 'alembic merge heads -m merge' to create a merge migration. Then 'alembic upgrade head'.

affects: all

gotchaAutogenerate generates 'create table' for all tables instead of 'add column' when models are not imported before autogenerate runs. Models must be imported in env.py so SQLAlchemy metadata is populated.

fix

Import all model files in env.py before target_metadata = Base.metadata.

affects: all

gotchaalembic.ini sqlalchemy.url hardcodes the database URL. For production, override it in env.py using environment variables.

fix

In env.py: config.set_main_option('sqlalchemy.url', os.environ['DATABASE_URL'])

affects: all

gotchaRunning pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead.

fix

Always use a virtual environment (e.g., `python -m venv .venv`) to install Python packages to avoid permission issues and system package manager conflicts. Avoid running pip commands with `sudo` unless absolutely necessary for system-wide tools, which is generally not recommended for application dependencies.

affects: all

gotchaRunning pip as root can lead to broken permissions and conflicts with the system package manager, potentially rendering the system unusable.

fix

It is recommended to use a virtual environment or run pip as a non-root user. If running as root is intentional, use the `--root-user-action` option to suppress this warning.

affects: all

Upgrade

Version history

1.19.1latest on PyPI · released Aug 8, 2026

Audit

Dependencies

sqlalchemyrequiredRequired. Alembic 1.15+ requires SQLAlchemy >= 1.4. SQLAlchemy 2.0 fully supported.

MakorequiredRequired for migration script templates. Installed automatically.

Agent activity

79 hits · last 30 days

node

Resources

githubhttps://github.com/sqlalchemy/alembic ↗

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

homepagehttps://alembic.sqlalchemy.org ↗

docshttps://alembic.sqlalchemy.org/en/latest/ ↗

changeloghttps://alembic.sqlalchemy.org/en/latest/changelog.html ↗