---
id: django-migration-linter
version: "6.0.0"
license: Apache-2.0
license_treatment: permissive
maintenance: aging
---

# django-migration-linter — Detect backward incompatible migrations for your django project

License: permissive · Maintenance: aging · Downloads: 1.4M/mo

## What it is and what it does

Django-migration-linter is a static analysis tool that scans your Django project's migrations and flags operations that would break backward compatibility—such as adding NOT NULL columns without defaults, dropping tables, or renaming tables. It runs as a Django management command and can be integrated into CI/CD pipelines or hooked into the makemigrations workflow to catch incompatibilities before they're committed.

The tool works by analyzing each migration file against a catalog of known incompatible patterns. When run, it reports a summary showing which migrations are valid, erroneous, ignored, or have warnings. It can optionally delete newly generated migrations that fail linting, with user confirmation, to prevent incompatible changes from entering the codebase. Configuration is optional via a Django setting, and the linter supports Django 3.2 through 6.0 on Python 3.9+.

Use it for:

- Catch breaking schema changes during development before they reach production or older deployed instances.
- Integrate into CI pipelines to reject pull requests that introduce backward-incompatible migrations.
- Automatically validate migrations during makemigrations to prompt developers to fix issues immediately.
- Audit existing migration history to identify past incompatibilities that may have caused deployment problems.
- Enforce migration best practices in teams by preventing common pitfalls like undefaulted NOT NULL columns.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Analyzes Django migrations to detect backward-incompatible operations that could break older codebases, running as a management command or integration point during migration generation.

Yes, if you maintain Django projects with rolling deployments or need to support multiple active versions. The low install friction, permissive license, and active support for modern Django versions make it a practical addition to development workflows. The aging maintenance status is not a blocker—the tool is stable and the last commit is recent—but verify that its incompatibility catalog covers your project's specific patterns.

## Install

pip install django-migration-linter
uv add django-migration-linter
poetry add django-migration-linter

## Installing django-migration-linter

Before you install: Low friction install with three lightweight runtime dependencies (django, appdirs, toml). Last commit on 2026-01-04 and marked aging, but the project remains active and supports current Django versions through 6.0.

License in practice: Apache-2.0 permissive license allows use in commercial and private projects with minimal restrictions; you must include a copy of the license and note material changes.

Quickstart:

pip install django-migration-linter

# Add to Django INSTALLED_APPS:
INSTALLED_APPS = [
    ...,
    "django_migration_linter",
]

# Run linter:
python manage.py lintmigrations

Requires Django 3.2 or later and Python 3.9 or later; must be added to INSTALLED_APPS to function.

Verify before relying:

- Whether the linter detects all common backward-incompatible patterns or only a subset of known operations.
- Performance impact when linting large migration histories or complex projects.
- How the linter handles custom migration operations or third-party migration tools.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 1.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

django migration compatibility checker, detect breaking database migrations, django backward compatibility linter, migration incompatibility detector, django schema change validator, prevent breaking migrations django, database migration safety check, django-tooling, migration-validation, ci-integration

[View on SkillFed](https://skillfed.io/packages/django-migration-linter) · [View on PyPI](https://pypi.org/project/django-migration-linter/)