{"id":1459,"library":"django-stubs","title":"Django Stubs","description":"Django Stubs provides Mypy type stubs for the Django framework, enabling static type checking for Django projects. It includes a Mypy plugin that understands Django's ORM, models, and settings to provide accurate type inference. The library is actively maintained with frequent updates, often aligning its major versions with Django's release cycle, ensuring compatibility and comprehensive coverage for new Django features.","status":"active","version":"6.0.2","language":"en","source_language":"en","source_url":"https://github.com/typeddjango/django-stubs","tags":["django","mypy","typing","stubs","type-checking","static-analysis"],"install":[{"cmd":"pip install django-stubs","lang":"bash","label":"Install core package"}],"dependencies":[{"reason":"Required to use the type stubs for static analysis.","package":"mypy","optional":false},{"reason":"Provides type hints for this library. Must be installed separately as django-stubs only provides the type definitions.","package":"Django","optional":false}],"imports":[],"quickstart":{"code":"[mypy]\nplugins = mypy_django_plugin.main\n\n[mypy.plugins.django]\ndjango_settings_module = \"my_project.settings\"\n\n# Example of a Django model file (e.g., my_app/models.py)\n# from django.db import models\n#\n# class MyModel(models.Model):\n#     name = models.CharField(max_length=100)\n#     value = models.IntegerField(default=0)\n#\n# # Example of using type hints\n# def get_model_by_name(name: str) -> MyModel | None:\n#     return MyModel.objects.filter(name=name).first()\n#\n# # Run mypy from your project root:\n# # mypy .","lang":"python","description":"To use django-stubs, you need to configure Mypy to use its plugin. Create or update your `mypy.ini` or `pyproject.toml` file as shown. Replace `my_project.settings` with the actual path to your Django settings module. This configuration allows Mypy to understand Django's dynamic nature, especially with models and querysets."},"warnings":[{"fix":"Ensure your `django-stubs` version matches your `Django` version. For example, use `django-stubs==6.*` with `Django==6.*`.","message":"Major versions of `django-stubs` are tightly coupled with major versions of `Django`. Upgrading `django-stubs` (e.g., from 5.x to 6.x) typically requires upgrading your `Django` version to match (e.g., from Django 5.x to Django 6.x). Incompatible versions can lead to incorrect type checking or Mypy plugin errors.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure you have `plugins = mypy_django_plugin.main` configured in your `mypy.ini` or `pyproject.toml` file, and point `django_settings_module` to your project's settings. No `import django_stubs` is necessary or correct.","message":"`django-stubs` does not expose symbols for direct import. Its functionality is exclusively provided through Mypy's plugin system. Users commonly misunderstand that it's a library to be imported rather than a Mypy extension.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Check `django-stubs` release notes or documentation for the officially supported `mypy` versions. For example, `django-stubs 6.0.2` officially supports `mypy@1.20`.","message":"Specific `mypy` versions are required for full compatibility. While `django-stubs` generally aims for broad `mypy` support, new features or critical bug fixes often necessitate upgrading `mypy` itself.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `django-stubs` version `6.0.1` or newer. This issue was resolved in version `6.0.1`.","message":"Version `6.0.0` of `django-stubs` contained a crash bug in the Mypy plugin when checking code that used `QuerySet.order_by()` with abstract models. This caused Mypy to fail unexpectedly.","severity":"gotcha","affected_versions":"6.0.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}