Django migration linter

Detect backward incompatible migrations for your Django project. It will save you time by making sure migrations will not break with a older codebase.

Travis PyPI PR_Welcome 3YD_Hiring GitHub_Stars

Quick installation

pip install django-migration-linter

And add the migration linter your INSTALLED_APPS:


Usage example

$ python lintmigrations

(app_add_not_null_column, 0001_create_table)... OK
(app_add_not_null_column, 0002_add_new_not_null_field)... ERR
        NOT NULL constraint on columns
(app_drop_table, 0001_initial)... OK
(app_drop_table, 0002_delete_a)... ERR
        DROPPING table
(app_ignore_migration, 0001_initial)... OK
(app_ignore_migration, 0002_ignore_migration)... IGNORE
(app_rename_table, 0001_initial)... OK
(app_rename_table, 0002_auto_20190414_1500)... ERR
        RENAMING tables

*** Summary ***
Valid migrations: 4/8
Erroneous migrations: 3/8
Migrations with warnings: 0/8
Ignored migrations: 1/8

The linter analysed all migrations from the Django project. It found 3 migrations that are doing backward incompatible operations and 1 that is explicitly ignored. The list of incompatibilities that the linter analyses can be found at docs/

More advanced usages of the linter and options can be found at docs/


One can either integrate the linter in the CI and the lintmigrations command, or detect incompatibilities during generation with

$ python makemigrations --lint

Migrations for 'app_correct':
    - Add field column to a
Linting for 'app_correct':
(app_correct, 0003_a_column)... ERR
        NOT NULL constraint on columns

The migration linter detected that this migration is not be backward compatible.
- If you keep the migration, you will want to fix the issue or ignore the migration.
- By default, the newly created migration file will be deleted.
Do you want to keep the migration? [y/N]
Deleted tests/test_project/app_correct/migrations/

The linter found that the newly created migration is not backward compatible and deletes the files. This behaviour can be the default of the makemigrations command through the MIGRATION_LINTER_OVERRIDE_MAKEMIGRATIONS Django settings. Find out more about the makemigrations command at docs/

More information

Please find more documentation generally in the docs/ folder.

Some implementation details can found in the ./docs/internals/ folder.

Blog post

Keeping Django database migrations backward compatible


django-migration-linter is released under the Apache 2.0 License.

Maintained by David Wobrock