Resolving alembic merge branch conflicts

May 23rd, 2016 in  by Michael Cho

How to fix alembic's "Multiple head revisions are present for given argument 'head'" error.

Alembic is a database migration tool for use with Python, letting you run migrations for schema updates - similar to `rake db:migrate` in Rails.

One common issue is when writing migrations in different git branches, you may get an error like:

FAILED: Multiple head revisions are present for given argument 'head'; please
specify a specific target revision, '@head' to narrow to a specific
head, or 'heads' for all heads

This basically means that you have more than one migration file which points to the same down_revision. That is, when you look at your migration file you should see some lines like the following, and there are multiple files with '4a4614932e00':

revision = '58f4a1203e80'
down_revision = '4a4614932e00'

Thankfully it's an easy enough fix.

To automatically merge all heads, just run:

$ alembic merge heads

If you would like more control to merge specific heads together, run:

$ alembic merge -m "merge ae1 and 27c" ae1027 27c6a

For more info, check out the alembic documentation.

Other articles you may like

Python command-line scripts with argparse
Feb 15th, 2018
SQLAlchemy commit(), flush(), expire(), refresh(), merge() - what's the difference?
Nov 2nd, 2017
Prioritized Code Review Checklist - what to look for first, second, and last
Sep 21st, 2017
Many to many relationships in SQLAlchemy models (Flask)
Jul 28th, 2017
Bash script to relink alembic migrations
Jun 12th, 2017