Install & Compatibility
Where this runs
tested against v0.24.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.696s · 134.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.8s · import 0.620s · 132MB
133MB installed
● package 133MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Model
✓ from django.db.models import Model
✗ from django_types.db.models import Model
django-types provides type stubs for standard Django imports. You should import directly from `django.*` as usual; mypy will automatically pick up the stub information from django-types.
HttpRequest
✓ from django.http import HttpRequest
Similar to models, you import standard Django components, and django-types adds type information.
This quickstart demonstrates how to set up a minimal Django project, define a typed model, and configure `mypy` with `django-types` for static analysis. It generates dummy files and provides the `mypy` command to run. Key steps are: installing `django-types` alongside `mypy` and Django, creating `mypy.ini` with the `mypy_django_plugin`, and specifying the Django settings module.
import os
import sys
from pathlib import Path
# Simulate a minimal Django project structure for type checking
project_dir = Path('./myproject_for_typechecking')
project_dir.mkdir(exist_ok=True)
(project_dir / '__init__.py').touch(exist_ok=True)
# Simulate app creation
app_dir = project_dir / 'myapp'
app_dir.mkdir(exist_ok=True)
(app_dir / '__init__.py').touch(exist_ok=True)
# Create a dummy settings.py
settings_content = '''
INSTALLED_APPS = ['myapp']
SECRET_KEY = 'insecure-key-for-testing'
DATABASES = {'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}}
'''
(project_dir / 'settings.py').write_text(settings_content)
# Create a typed model in myapp/models.py
models_content = '''
from django.db import models
class MyTypedModel(models.Model):
name = models.CharField(max_length=255)
value = models.IntegerField(default=0)
class Meta:
app_label = 'myapp'
def get_model_instance() -> MyTypedModel:
# This function is just to demonstrate type hints
return MyTypedModel(name='Test', value=10)
'''
(app_dir / 'models.py').write_text(models_content)
# Create a mypy configuration file
mypy_config_content = '''
[mypy]
plugins = mypy_django_plugin.main
[mypy.plugins.django_settings]
module = myproject_for_typechecking.settings
'''
(Path('.') / 'mypy.ini').write_text(mypy_config_content)
print("Generated project structure and mypy.ini. Now run:")
print(" PYTHONPATH=. mypy myproject_for_typechecking")
# Clean up (optional, for actual runtime) - commented out for user to inspect files
# import shutil
# shutil.rmtree(project_dir)
# (Path('.') / 'mypy.ini').unlink()
Debug
Known issues
breakingdjango-types provides type stubs for specific Django versions. Using a version of `django-types` that is incompatible with your installed `Django` version can lead to incorrect type checking results or errors.fixAlways check the `django-types` documentation (or PyPI project page) for supported Django versions. Ensure your `django-types` version matches or falls within the supported range for your `Django` installation. Upgrade both in tandem if necessary.
affects: <0.23.0 (and future versions)
gotchaFor `django-types` to function correctly, you *must* enable the `mypy_django_plugin` in your `mypy` configuration (e.g., `mypy.ini`, `pyproject.toml`). Without it, `mypy` will not apply the Django-specific type logic.fixAdd `plugins = mypy_django_plugin.main` to the `[mypy]` section of your `mypy.ini` or equivalent configuration file. Additionally, specify your Django settings module using `[mypy.plugins.django_settings]
module = your_project.settings`.
affects: All versions
gotchaWhen running `mypy`, it needs to be able to locate your Django settings module. This often requires setting `PYTHONPATH` correctly or explicitly passing the settings module via a `mypy.ini` configuration or command-line argument.fixEnsure `mypy.plugins.django_settings.module` is correctly configured in your `mypy.ini` (e.g., `module = your_project.settings`). If running `mypy` from your project root, you might need to add `PYTHONPATH=.` or ensure `your_project` is discoverable on the Python path.
affects: All versions
Upgrade
Version history
0.24.0latest on PyPI · released Apr 22, 2026
Audit
Dependencies
DjangorequiredProvides type stubs for Django; requires Django itself to be installed for usage.
mypyrequiredThe primary static type checker django-types integrates with.