Django 'conflicting migrations detected': fix it and prevent it
Short answer: Django's migrations form a chain in which each new migration depends on the previous one, so when two developers each create migration 0012 on separate branches, both depend on 0011, and after merging Django sees two "latest" migrations and refuses to migrate with "Conflicting migrations detected". If the two changes are independent, run python manage.py makemigrations --merge to create a small merge migration. If one branch hasn't been deployed anywhere yet, it's often cleaner to delete its migration, update the branch and regenerate it. Add makemigrations --check and a conflict check to CI so problems show up in pull requests, not on deploy day.
Why it happens
Django's documentation suggests thinking of migrations as version control for your database schema: makemigrations packages model changes into migration files, like commits, and migrate applies them. Each migration lists its dependencies, normally the previous migration in the same app.
Two branches created from the same point both build on the same parent. After merging, the app has two migrations with no successor: two "leaf nodes". Django can't know which order to apply them in, so it stops.
Option 1: create a merge migration
Django's command reference describes makemigrations --merge as enabling the fixing of migration conflicts. It creates a new migration that depends on both leaves, joining the chain back into one. The two original migrations stay as they are.
When it's right:
- both branches' migrations have already been applied somewhere, such as staging or a teammate's database
- the changes don't touch the same fields or tables in conflicting ways
After creating it, run the migrations on a fresh database and on a copy of production data to confirm they work together.
Option 2: regenerate one branch's migration
If one branch's migration hasn't been applied anywhere that matters, a tidier history is to:
- Delete that branch's new migration file.
- Merge or rebase the branch onto the latest main branch.
- Run
makemigrationsagain, producing0013that depends on the other0012. - Roll back the migration on your local database first if you'd applied it there.
This avoids merge migrations piling up, but only do it for migrations nobody else has applied.
When the two changes really conflict
If both migrations alter the same field differently, such as one renaming a column and the other changing its type, neither option fixes the logic for you. Decide what the final schema should be, adjust one branch's model changes, and regenerate. Data migrations (RunPython) also need care: check they still make sense after the other branch's changes.
Catch it in CI
Two checks prevent most surprises:
- Missing migrations. The reference describes
makemigrations --check, which exits with a non-zero status when model changes don't have migrations. Run it in CI so nobody merges model changes without migrations. - Conflicts. Run
makemigrations --checkagainst the merged result in CI, or a small script usingshowmigrationsto detect multiple leaves, on pull requests targeting your main branch. Many teams also simply runmigrateon a fresh database in CI, which fails on conflicts.
Requiring branches to be up to date with main before merging means the conflict appears in the pull request, where the author can fix it, instead of on main.
Team habits that help
- Pull before creating migrations. Update from main right before running
makemigrations. - Give migrations names. The
--nameoption makes files like0012_add_invoice_due_dateeasier to review than auto-generated names. - Keep migrations small and focused. Small changes rarely clash and are easier to merge.
- Review migration files in pull requests, not just models.
- Use
--updatefor in-progress work. The reference describesmakemigrations --update, which merges new model changes into the latest migration. Handy while a branch is still local, so one feature doesn't end up with five tiny migrations. Don't use it on migrations already shared.
Local databases
Developers switching between branches often end up with a local database that has migrations applied from a branch that no longer exists. If migrate complains about unknown or inconsistent history locally, the quickest fix is usually to recreate the development database from scratch and load seed data. Keeping a reliable seed script makes this a two-minute job rather than an afternoon of untangling, and stops people from "fixing" migration files to suit a broken local state.
Deploying merged migrations
Apply migrations as a deliberate step in your deploy, before the new code serves traffic. With merge migrations, check the order Django will use with showmigrations or migrate --plan on a staging copy, especially if one migration moves data the other depends on.
Squash occasionally
Django's documentation says you can make migrations freely; the migration system handles hundreds without much slowdown. Eventually, squashing reduces many migrations to a few that represent the same changes. Squash on a quiet period, after all environments have applied the old migrations.
A worked example
An illustrative Leeds recruitment platform's two developers both added fields to the Candidate model in the same week. After merging, the deploy failed with "Conflicting migrations detected". One migration was already on staging; the other only on a laptop. The second developer deleted their migration, rebased and regenerated it as 0013, and the deploy went through. The team then added makemigrations --check and a fresh-database migrate to CI, and turned on "require branches to be up to date" in their repository settings.
FAQ
Is a merge migration bad?
No. It's a normal, supported way to join branches. Lots of them just make history noisier.
Can I rename migration files to reorder them?
Not safely without updating dependencies, and never for migrations already applied.
What if production already has both?
Then a merge migration is the right fix; don't delete applied migrations.
Does this affect third-party apps?
Conflicts within your own apps are the usual case; third-party apps manage their own migrations.
If migrations regularly trip up your team's deploys, describe your workflow and we'll help you set up checks that catch conflicts early.