{"id":4511,"library":"django-migration-linter","title":"Django Migration Linter","description":"django-migration-linter is a tool for Django projects designed to detect backward incompatible database migrations. It analyzes new migrations against a baseline (e.g., a Git branch) to prevent accidental breaking changes to your database schema. The current version is 6.0.0, and it maintains an active release cadence, frequently adding support for new Python and Django versions.","status":"active","version":"6.0.0","language":"en","source_language":"en","source_url":"https://github.com/3YOURMIND/django-migration-linter","tags":["django","migrations","linter","database","ci","schema","orm"],"install":[{"cmd":"pip install django-migration-linter","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Core functionality is built upon Django's ORM and migration system.","package":"Django","optional":false},{"reason":"Used for comparing migrations against a Git commit or branch. It is an optional dependency if not using git-based comparisons.","package":"GitPython","optional":true}],"imports":[],"quickstart":{"code":"# 1. Add 'django_migration_linter' to your INSTALLED_APPS in settings.py:\n#    INSTALLED_APPS = [\n#        ...,\n#        'django_migration_linter',\n#    ]\n\n# 2. Run the linter as a Django management command.\n#    This example compares new migrations against the 'main' Git branch\n#    and treats any linter warnings as errors (failing the check).\nimport subprocess\nimport os\n\n# Ensure your Django settings are configured for manage.py\n# (e.g., DJANGO_SETTINGS_MODULE environment variable)\n\ntry:\n    print(\"Running django-migration-linter...\")\n    subprocess.check_call([\n        \"python\", \"manage.py\", \"lintmigrations\",\n        \"--git-commit-id\", \"main\",\n        \"--warnings-as-errors\"\n    ])\n    print(\"\\nMigrations linted successfully with no backward incompatible changes detected.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"\\nMigration linter failed with exit code {e.returncode}:\")\n    print(\"Please review the output for backward incompatible changes and fix them.\")\nexcept FileNotFoundError:\n    print(\"Error: 'python' command not found. Ensure Python is in your PATH and manage.py exists.\")\n","lang":"python","description":"To quickly use `django-migration-linter`, add it to your `INSTALLED_APPS` and then execute the `lintmigrations` management command. The example demonstrates how to run the linter to compare migrations in your current branch against the 'main' branch, ensuring that any detected warnings will cause the command to fail. This is typically run in CI/CD pipelines."},"warnings":[{"fix":"No direct code change is typically needed unless your specific setup or scripts relied on the old behavior for custom-labeled apps. Ensure your `django_migration_linter` configuration and expectations align with app labels.","message":"As of v6.0.0, `django-migration-linter` now correctly handles custom Django app labels when determining migrations from a Git reference. Previously, it might have relied on folder names. If your project uses custom app labels, the linter will now reference apps by their Django label, which might change detection behavior if you were implicitly relying on folder names.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure your environment (e.g., CI/CD) provides a correctly configured and accessible database for `sqlmigrate` to run successfully. Address any underlying issues causing `sqlmigrate` errors. If an error is truly ignorable (rare), you can use the `--ignore-sqlmigrate-errors` option (available from v5.1.0 and later).","message":"Beginning with v5.0.0, the linter no longer silently ignores failures that occur during its internal calls to Django's `sqlmigrate` command. Instead, it will now crash and raise the `sqlmigrate` error. This change prevents problematic migrations from passing the linter unnoticed, especially if SQL generation requires specific database conditions.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update any scripts or CI/CD configurations that invoke `manage.py lintmigrations` to use the new argument syntax, for example: `manage.py lintmigrations --git-commit-id <commit_id>`.","message":"In v3.0.0, the command-line interface for `lintmigrations` underwent a breaking change. The `GIT_COMMIT_ID` positional argument became an optional named argument (`--git-commit-id [GIT_COMMIT_ID]`), and the command now accepts `[app_label]` and `[migration_name]` as new positional arguments.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your environment where `lintmigrations` is run (e.g., local development, CI/CD pipeline) has a valid database connection configured in Django settings. You can use a lightweight database like SQLite for testing purposes if full database functionality isn't strictly needed for the SQL analysis.","message":"The linter's deep analysis often depends on Django's `sqlmigrate` command, which typically requires an active database connection to generate and inspect the SQL for migration files. Running the linter in an environment without a configured or accessible database can lead to `sqlmigrate` failures, which will crash the linter (since v5.0.0).","severity":"gotcha","affected_versions":"all"},{"fix":"Always consult the specific release notes for the `django-migration-linter` version you intend to use to confirm compatibility with your project's Python and Django versions. Upgrade your Python/Django stack if it falls outside the supported range for the desired linter version.","message":"Numerous releases have dropped support for older Python and Django versions. For instance, Python 3.7 and 3.8 were dropped in v5.2.0. Django 1.11, 2.0, 2.1, 3.0, and 3.1 were dropped in v4.0.0, alongside Python 2.7, 3.5, and 3.6.","severity":"breaking","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}