django-stubs

This package contains type stubs and a custom mypy plugin to provide more precise static types and type inference for Django framework. Django uses some Python “magic” that makes having precise types for some code patterns problematic. This is why we need this project. The final goal is to be able to get precise types for most common patterns.

Supported type checkers

• mypy: full and complete support with multiple advanced features with our custom mypy plugin
• pyright: basic support, checked in CI
• pyrefly: basic support, checked in CI
• ty: basic support, checked in CI

Installation

pip install 'django-stubs[compatible-mypy]'

To make mypy aware of the plugin, you need to add

[mypy]
plugins =
    mypy_django_plugin.main

[mypy.plugins.django-stubs]
django_settings_module = "myproject.settings"

in your mypy.ini or setup.cfg file.

pyproject.toml configurations are also supported:

[tool.mypy]
plugins = ["mypy_django_plugin.main"]

[tool.django-stubs]
django_settings_module = "myproject.settings"

Two things happening here:

1. We need to explicitly list our plugin to be loaded by mypy
2. You can either specify django_settings_module as seen above, or let django_stubs use the DJANGO_SETTINGS_MODULE variable from your environment.

This fully working typed boilerplate can serve you as an example.

Version compatibility

We rely on different django and mypy versions:

django-stubs	Mypy version	Django version	Django partial support	Python version
unreleased	1.16 - 2.4	6.1	6.0, 5.2	3.11 - 3.15
6.1.2	1.13 - 2.4	6.1	6.0, 5.2	3.11 - 3.14
6.1.1	1.13 - 2.3	6.1	6.0, 5.2	3.11 - 3.14
6.1.0	1.13 - 2.3	6.1	6.0, 5.2	3.11 - 3.14
6.0.9	1.13 - 2.3	6.0	5.2, 5.1, 5.0	3.10 - 3.14
6.0.8	1.13 - 2.3	6.0	5.2, 5.1, 5.0	3.10 - 3.14
6.0.7	1.13 - 2.3	6.0	5.2, 5.1, 5.0	3.10 - 3.14
6.0.6	1.13 - 2.1	6.0	5.2, 5.1, 5.0	3.10 - 3.14
6.0.5	1.13 - 2.1	6.0	5.2, 5.1, 5.0	3.10 - 3.14
6.0.4	1.13 - 2.0	6.0	5.2, 5.1, 5.0	3.10 - 3.14
6.0.3	1.13 - 1.20	6.0	5.2, 5.1, 5.0	3.10 - 3.14
6.0.2	1.13 - 1.20	6.0	5.2, 5.1, 5.0	3.10 - 3.14
6.0.1	1.13 - 1.19	6.0	5.2, 5.1, 5.0	3.10 - 3.14
6.0.0	1.13 - 1.19	6.0	5.2, 5.1, 5.0	3.10 - 3.14
5.2.9	1.13 - 1.19	5.2	5.1, 5.0	3.10 - 3.13
5.2.8	1.13 - 1.19	5.2	5.1, 5.0	3.10 - 3.13
5.2.7	1.13 - 1.18	5.2	5.1, 5.0	3.10 - 3.13
5.2.6	1.13 - 1.18	5.2	5.1, 5.0	3.10 - 3.13
5.2.5	1.13 - 1.18	5.2	5.1, 5.0	3.10 - 3.13
5.2.4	1.13 - 1.18	5.2	5.1, 5.0	3.10 - 3.13
5.2.3	1.13 - 1.18	5.2	5.1, 5.0	3.10 - 3.13
5.2.2	1.13 - 1.17	5.2	5.1, 5.0	3.10 - 3.13
5.2.1	1.13 - 1.16	5.2	5.1, 5.0	3.10 - 3.13
5.2.0	1.13+	5.2	5.1, 5.0	3.10 - 3.13

What “partial” support means, and why we don’t pin to the exact Django/mypy version, is explained in https://github.com/typeddjango/django-stubs/discussions/2101#discussioncomment-9276632.

Features

Type checking of Model Meta attributes

[!NOTE] If you are using the mypy plugin and have django_stub_ext installed, your model Meta classes will be automatically type-checked without further changes.

By inheriting from the TypedModelMeta class, you can ensure you’re using correct types for attributes:

from django.db import models
from django_stubs_ext.db.models import TypedModelMeta


class MyModel(models.Model):
    example = models.CharField(max_length=100)

    class Meta(TypedModelMeta):
        ordering = ["example"]
        constraints = [
            models.UniqueConstraint(fields=["example"], name="unique_example"),
        ]

Other typed base classes

• django_stubs_ext.db.router.TypedDatabaseRouter can be used as base when implementing custom database routers.

Settings

django-stubs has a few settings, which you can list in:

• pyproject.toml, under the table [tool.django-stubs]
• mypy.ini under the table [mypy.plugins.django-stubs]

The supported settings are:

• django_settings_module, a string, default to os.getenv(DJANGO_SETTINGS_MODULE).

  Specify the import path of your settings module, the same as Django’s DJANGO_SETTINGS_MODULE environment variable.

• strict_settings, a boolean, default true.

  Set to false if using dynamic settings, as described below.

• strict_model_abstract_attrs, a boolean, default true.

  Set to false if you want to keep .objects, .DoesNotExist, .NotUpdated, and .MultipleObjectsReturned attributes on models.Model type. See here why this is dangerous to do by default.

FAQ

Is this an official Django project?

No, it is not. We are independent from Django at the moment. There’s a proposal to merge our project into the Django itself. You can show your support by liking the PR.

Is it safe to use this in production?

Yes, it is! This project does not affect your runtime at all. It only affects mypy type checking process.

But, it does not make any sense to use this project without mypy.

mypy crashes when I run it with this plugin installed

The current implementation uses Django’s runtime to extract information about models, so it might crash if your installed apps or models.py are broken.

In other words, if your manage.py runserver crashes, mypy will crash too. You can also run mypy with --tb option to get extra information about the error.

I cannot use QuerySet or Manager with type annotations

You can get a TypeError: 'type' object is not subscriptable when you will try to use QuerySet[MyModel], Manager[MyModel, MyQuerySet] or some other Django-based Generic types.

This happens because these Django classes do not support __class_getitem__ magic method in runtime.

1. You can go with our django_stubs_ext helper, that patches all the types we use as Generic in django.

   Install it:

   pip install django-stubs-ext  # as a production dependency
   

   And then place in your top-level settings:

   import django_stubs_ext
   
   django_stubs_ext.monkeypatch()
   

   You can add extra types to patch with django_stubs_ext.monkeypatch(extra_classes=[YourDesiredType])

   If you use generic symbols in django.contrib.auth.forms, you will have to do the monkeypatching manually in your first AppConfig.ready. This is currently required because django.contrib.auth.forms cannot be imported until django is initialized.

   import django_stubs_ext
   from django.apps import AppConfig
   
   
   class ClientsConfig(AppConfig):
       name = "clients"
   
       def ready(self) -> None:
           from django.contrib.auth.forms import SetPasswordMixin, SetUnusablePasswordMixin
   
           # For Django version prior to 5.1, use `extra_classes=[SetPasswordForm, AdminPasswordChangeForm]` instead.
           django_stubs_ext.monkeypatch(extra_classes=[SetPasswordMixin, SetUnusablePasswordMixin])
   

2. You can use strings instead: 'QuerySet[MyModel]' and 'Manager[MyModel, MyQuerySet]', this way it will work as a type for mypy and as a regular str in runtime.

How can I create a HttpRequest that’s guaranteed to have an authenticated user?

Django’s built in HttpRequest has the attribute user that resolves to the type User | AnonymousUser where User is the user model specified by the AUTH_USER_MODEL setting.

If you want a HttpRequest that you can type-annotate with where you know that the user is authenticated you can subclass the normal HttpRequest class like so:

from django.http import HttpRequest
from my_user_app.models import MyUser


class AuthenticatedHttpRequest(HttpRequest):
    user: MyUser

And then use AuthenticatedHttpRequest instead of the standard HttpRequest for when you know that the user is authenticated. For example in views using the @login_required decorator.

Why am I getting incompatible return type errors on my custom managers?

If you declare your custom managers without generics and override built-in methods you might see an error message about incompatible error messages, something like this:

from django.db import models


class MyManager(models.Manager):
    def create(self, **kwargs) -> "MyModel":
        pass

will cause this error message:

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

This is happening because the Manager class is generic, but without specifying generics the built-in manager methods are expected to return the generic type of the base manager, which is any model. To fix this issue you should declare your manager with your model as the type variable:

class MyManager(models.Manager["MyModel"]): ...

The same applies to a manager that overrides get_queryset with a custom queryset, which is also generic. Declared without generics:

class MyQuerySet(models.QuerySet): ...


class MyManager(models.Manager):
    def get_queryset(self) -> MyQuerySet:
        return MyQuerySet(self.model, using=self._db)

you get a similar error:

error: Return type “MyQuerySet[Any, Any]” of “get_queryset” incompatible with return type “_QS” in supertype “django.db.models.manager.BaseManager”

To fix this issue, pass the model to both the queryset and the manager, and the queryset to the manager:

class MyQuerySet(models.QuerySet["MyModel"]): ...


class MyManager(models.Manager["MyModel", MyQuerySet]):
    def get_queryset(self) -> MyQuerySet:
        return MyQuerySet(self.model, using=self._db)

If one manager is shared by several models, keep the model as a type variable and bind it in a per-model subclass, which every type checker understands without the plugin:

from typing import TypeVar

_M = TypeVar("_M", bound=models.Model)


class MyQuerySet(models.QuerySet[_M]): ...


class MyManager(models.Manager[_M, MyQuerySet[_M]]):
    def get_queryset(self) -> MyQuerySet[_M]:
        return MyQuerySet(self.model, using=self._db)


class BookManager(MyManager["Book"]): ...


class Book(models.Model):
    objects = BookManager()  # Book.objects.filter() is MyQuerySet[Book]

[!NOTE] More generally, specifying generics is required to get proper type-checking around django’s ORM. Once your managers are parametrized, chains such as Book.objects.filter(...) become precisely typed, so code that used to go through Any (for instance attributes added by annotate inside a queryset method) may now report errors that were previously hidden.

How do I annotate cases where I called QuerySet.annotate?

Django-stubs provides a special type, django_stubs_ext.WithAnnotations[Model, <Annotations>], which indicates that the Model has been annotated, meaning it requires extra attributes on the model instance.

You should provide a TypedDict of these attributes, e.g. WithAnnotations[MyModel, MyTypedDict], to specify which annotated attributes are present.

Currently, the mypy plugin can recognize that specific names were passed to QuerySet.annotate and include them in the type, but does not record the types of these attributes.

The knowledge of the specific annotated fields is not yet used in creating more specific types for QuerySet’s values, values_list, or filter methods, however knowledge that the model was annotated is used to create a broader type result type for values/values_list, and to allow filtering on any field.

from typing import TypedDict
from django_stubs_ext import WithAnnotations
from django.db import models
from django.db.models.expressions import Value


class MyModel(models.Model):
    username = models.CharField(max_length=100)


class MyTypedDict(TypedDict):
    foo: str


def func(m: WithAnnotations[MyModel, MyTypedDict]) -> str:
    print(m.bar)  # Error, since field "bar" is not in MyModel or MyTypedDict.
    return m.foo  # OK, since we said field "foo" was allowed


func(MyModel.objects.annotate(foo=Value("")).get(id=1))  # OK
func(MyModel.objects.annotate(bar=Value("")).get(id=1))  # Error

You can also use WithAnnotations in custom QuerySet methods by making the queryset generic over a model TypeVar. This way the return type stays accurate through chained calls and manager access:

[!NOTE] This example relies on the mypy plugin, which types Manager.from_queryset and WithAnnotations. pyright, pyrefly and ty see Product.objects as an unparametrized Manager here.

from typing import TypeVar, TypedDict
from django.db import models
from django.db.models import Manager
from django_stubs_ext import WithAnnotations


class SalesDict(TypedDict):
    total_sales: int


_Model = TypeVar("_Model", bound=models.Model, covariant=True)


class ProductQuerySet(models.QuerySet[_Model]):
    def with_sales(self) -> "ProductQuerySet[WithAnnotations[_Model, SalesDict]]":
        return self.annotate(total_sales=models.Sum("order__amount"))


ProductManager = Manager.from_queryset(ProductQuerySet)


class Product(models.Model):
    name = models.CharField(max_length=100)
    objects = ProductManager()


product = Product.objects.with_sales().get(id=1)
product.total_sales  # OK, int
product.name  # OK, str

Why am I getting incompatible argument type mentioning _StrPromise?

The lazy translation functions of Django (such as gettext_lazy) return a Promise instead of str. These two types cannot be used interchangeably. The return type of these functions was therefore changed to reflect that.

If you encounter this error in your own code, you can either cast the Promise to str (causing the translation to be evaluated), or use the StrPromise or StrOrPromise types from django-stubs-ext in type hints. Which solution to choose depends depends on the particular case. See working with lazy translation objects in the Django documentation for more information.

If this is reported on Django code, please report an issue or open a pull request to fix the type hints.

How to use a custom library to handle Django settings?

Using something like django-split-settings or django-configurations will make it hard for mypy to infer your settings.

This might also be the case when using something like:

try:
    from .local_settings import *
except Exception:
    pass

So, mypy would not like this code:

from django.conf import settings

settings.CUSTOM_VALUE  # E: 'Settings' object has no attribute 'CUSTOM_VALUE'

To handle this corner case we have a special setting strict_settings (True by default), you can switch it to False to always return Any and not raise any errors if runtime settings module has the given value, for example pyproject.toml:

[tool.django-stubs]
strict_settings = false

or mypy.ini:

[mypy.plugins.django-stubs]
strict_settings = false

And then:

from typing import reveal_type

# Works:
reveal_type(settings.EXISTS_AT_RUNTIME)  # N: Any

# Errors:
reveal_type(settings.MISSING)  # E: 'Settings' object has no attribute 'MISSING'

How to use type[Model] annotation with .objects attribute?

Let’s say you have a function similar to this one, which accepts a model type and accesses its .object attribute:

from django.db import models


def assert_zero_count(model_type: type[models.Model]) -> None:
    assert model_type.objects.count() == 0

This code will raise an error from mypy:

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

It is a common problem: some type[models.Model] types won’t have .objects available. Notable example: abstract models. See the reasoning here.

So, instead for the general case you should write:

def assert_zero_count(model_type: type[models.Model]) -> None:
    assert model_type._default_manager.count() == 0

Configurable with strict_model_abstract_attrs = false to skip removing .objects, .DoesNotExist, .NotUpdated, and .MultipleObjectsReturned attributes from model.Model if you are using our mypy plugin.

Use this setting on your own risk, because it can hide valid errors.

Do I need to annotate reverse relations?

Not if you use our mypy plugin. It reads your app registry and declares every reverse accessor for you, as RelatedManager[Model], or ManyRelatedManager[Model, Through] for a ManyToManyField.

pyright, pyrefly and ty do not run the plugin, so under those you declare them yourself. Reach for RelatedManager rather than Manager: a reverse accessor is read from a model instance, whereas a regular manager such as objects only exists on the model class.

from django.db import models
from django_stubs_ext.db.models.manager import ManyRelatedManager, RelatedManager


class Article(models.Model):
    category_set: RelatedManager[Category]
    tags: ManyRelatedManager[Tag, ArticleTag]

Make sure to import symbols from django_stubs_ext.db.models.manager. Django dynamically create these so they cannot be imported directly

If the related model’s default manager uses a custom queryset, pass it as the second argument so that article.category_set.filter() returns it rather than a plain QuerySet. The mypy plugin does this for you.

class CategoryQuerySet(models.QuerySet["Category"]): ...


class Article(models.Model):
    category_set: RelatedManager[Category, CategoryQuerySet]

ManyRelatedManager does not take a queryset argument: a ManyToManyField accessor always returns a plain QuerySet.

How to type a custom models.Field?

Django models.Field (and subclasses) are generic types with two parameters:

• _ST: type that can be used when setting a value
• _GT: type that will be returned when getting a value

When you create a subclass, you have two options depending on how strict you want the type to be for consumers of your custom field.

1. Generic subclass:

from typing import TypeVar, reveal_type
from django.db import models

_ST = TypeVar("_ST", contravariant=True)
_GT = TypeVar("_GT", covariant=True)


class MyIntegerField(models.IntegerField[_ST, _GT]): ...


class User(models.Model):
    my_field = MyIntegerField()


reveal_type(User().my_field)  # N: Revealed type is "int"
User().my_field = "12"  # OK (because Django IntegerField allows str and will try to coerce it)

2. Non-generic subclass (more strict):

from typing import reveal_type
from django.db import models


# This is a non-generic subclass being very explicit
# that it expects only int when setting values.
class MyStrictIntegerField(models.IntegerField[int, int]): ...


class User(models.Model):
    my_field = MyStrictIntegerField()


reveal_type(User().my_field)  # N: Revealed type is "int"
User().my_field = "12"  # E: Incompatible types in assignment (expression has type "str", variable has type "int")

See mypy section on generic classes subclasses.

Related projects

• awesome-python-typing - Awesome list of all typing-related things in Python.
• djangorestframework-stubs - Stubs for Django REST Framework.
• pytest-mypy-plugins - pytest plugin that we use for testing mypy stubs and plugins.
• wemake-django-template - Create new typed Django projects in seconds.
• django-modern-rest - Modern REST framework for Django with everything properly typed.

Contributing

This project is open source and community driven. As such we encourage contributions big and small. You can contribute by doing any of the following:

1. Contribute code (e.g. improve stubs, add plugin capabilities, write tests etc) - to do so please follow the contribution guide.
2. Assist in code reviews and discussions in issues.
3. Identify bugs and issues and report these
4. Ask and answer questions on StackOverflow

You can always also reach out in gitter to discuss your contributions!