Django Stubs

6.0.2 · active · verified Thu Apr 09

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.

Warnings

breaking 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.
Fix: Ensure your `django-stubs` version matches your `Django` version. For example, use `django-stubs==6.*` with `Django==6.*`.
gotcha `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.
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.
gotcha 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.
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`.
gotcha 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.
Fix: Upgrade to `django-stubs` version `6.0.1` or newer. This issue was resolved in version `6.0.1`.

Install

pip install django-stubs Install core package

Quickstart

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.

[mypy]
plugins = mypy_django_plugin.main

[mypy.plugins.django]
django_settings_module = "my_project.settings"

# Example of a Django model file (e.g., my_app/models.py)
# from django.db import models
#
# class MyModel(models.Model):
#     name = models.CharField(max_length=100)
#     value = models.IntegerField(default=0)
#
# # Example of using type hints
# def get_model_by_name(name: str) -> MyModel | None:
#     return MyModel.objects.filter(name=name).first()
#
# # Run mypy from your project root:
# # mypy .

view raw JSON →