Skip to main content

Mypy stubs for Django

Project description

mypy logo

Typesafe Django Framework

Build Status Checked with mypy Gitter

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.


pip install django-stubs

See Configuration section to get started.


To make mypy happy, you will need to add:

plugins =

django_settings_module = "myproject.settings"

in your mypy.ini or setup.cfg file.

Two things happeining here:

  1. We need to explicitly list our plugin to be loaded by mypy
  2. Our plugin also requires django settings module (what you put into DJANGO_SETTINGS_MODULE variable) to be specified

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 python version
1.3.0 0.750 2.2.x ^3.6
1.2.0 0.730 2.2.x ^3.6
1.1.0 0.720 2.2.x ^3.6
0.12.x old semantic analyzer (<0.711), dmypy support 2.1.x ^3.6


Is this an official Django project?

No, it is not. We are indendepent from Django at the moment. There's a proposal to merge our project into the Django itself. You show your support by linking 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

Current implementation uses Django runtime to extract models information, so it will crash, if your installed apps or is not correct. For this same reason, you cannot use reveal_type inside global scope of any Python file that will be executed for django.setup().

In other words, if your 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] or Manager[MyModel].

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

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

Currently we are working on providing __class_getitem__ to the classes where we need them.

How can I use HttpRequest with custom user model?

You can subclass standard request like so:

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

class MyRequest(HttpRequest):
    user: MyUser

And then use MyRequest instead of standard HttpRequest inside your project.

Related projects

To get help

We have Gitter here:

If you think you have more generic typing issue, please refer to and their Gitter.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-stubs, version 1.5.0
Filename, size File type Python version Upload date Hashes
Filename, size django_stubs-1.5.0-py3-none-any.whl (300.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-stubs-1.5.0.tar.gz (162.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page