django-stubs

library6.0.2pypypiunverified

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.

type-stubs web-framework database

pip install django-stubs

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · DJANGO-STUBS

django-stubs

type-stubspythonv6.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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 .

Debug

Known issues

breakingMajor 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.*`.

affects: All versions

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.

affects: All versions

gotchaSpecific `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`.

affects: All versions

gotchaVersion `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`.

affects: 6.0.0

gotchaThe Mypy configuration file (e.g., `mypy.ini` or `pyproject.toml` with `[tool.mypy]` section) contains directives like `[mypy]` which are not valid Python syntax. This error occurs when a configuration file is mistakenly executed directly as a Python script instead of being passed to the `mypy` command-line tool or being automatically detected by it. Mypy configuration files are declarative and parsed by the `mypy` program itself.

fix

Ensure that your Mypy configuration file is correctly placed (e.g., `mypy.ini` in the project root) and that you are invoking the `mypy` command-line tool to perform type checking. For example: `mypy your_project_path/` or `python -m mypy your_project_path/`. Do not try to execute the configuration file directly with the Python interpreter.

affects: All versions

gotchaExecuting a Mypy configuration file (e.g., one containing `[mypy]`) directly as a Python script will result in a `NameError` because configuration section headers are not valid Python syntax. Mypy configuration should be provided to the `mypy` command-line tool, not executed.

fix

Ensure your Mypy configuration is stored in a `mypy.ini` or `pyproject.toml` file and is invoked correctly by the `mypy` command (e.g., `mypy --config-file mypy.ini` or by placing it in a default location), rather than attempting to execute the configuration file directly as a Python script.

affects: All versions

Errors

Common errors & fixes

error: "Type[Model]" has no attribute "objects" [attr-defined]

Mypy, without the `django-stubs` plugin, doesn't recognize the `objects` manager which Django dynamically adds to models at runtime.

fix

Ensure the `mypy_django_plugin.main` is correctly configured in your `mypy.ini` or `pyproject.toml`. For generic model parameters, you might also need to explicitly hint the manager, e.g., `objects: models.Manager["MyModel"]` on the model class itself.

TypeError: 'type' object is not subscriptable

This error occurs at runtime when using generic type annotations like `QuerySet[MyModel]` or `Manager[MyModel]` directly, because Django's `QuerySet` and `Manager` classes do not natively support the `__class_getitem__` magic method required for such generics.

fix

Use `django_stubs_ext.monkeypatch()` at an early stage of your application (e.g., in an `AppConfig.ready` method) to enable generic support for Django types, or use string literal type annotations like `'QuerySet[MyModel]'` and `'Manager[MyModel]'`.

error: Return type "MyModel" of "create" incompatible with return type "_T" in supertype "BaseManager"

When defining custom managers that override built-in methods, Mypy reports this error if the manager is not declared with generics, leading to a mismatch between the custom method's return type and the generic return type of the base `Manager`.

fix

Declare your custom manager with your specific model as the type variable, for example: `class MyManager(models.Manager["MyModel"]):`.

Upgrade

Version history

6.0.2latest on PyPI · released Apr 1, 2026

Audit

Dependencies

mypyrequiredRequired to use the type stubs for static analysis.

DjangorequiredProvides type hints for this library. Must be installed separately as django-stubs only provides the type definitions.

Agent activity

35 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sponsors/typeddjango ↗

packagehttps://pypi.org/project/django-stubs/ ↗

changeloghttps://github.com/typeddjango/django-stubs/releases ↗