Install & Compatibility
Where this runs
tested against v3.2.2 · 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.000s · 67.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.000s · 68MB
58MB installed
● package 58MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
django_coverage_plugin
✓ # In .coveragerc
[run]
plugins = django_coverage_plugin
# Or in pyproject.toml
[tool.coverage.run]
plugins = [
'django_coverage_plugin',
]
The plugin is activated via configuration in .coveragerc or pyproject.toml, not through direct Python import of a class or function.
To quickly get started, install the plugin, configure your `coverage.py` settings (either in `.coveragerc` or `pyproject.toml`) to include `django_coverage_plugin` in the `plugins` list, and ensure Django's template debugging is enabled (`TEMPLATES.OPTIONS.debug: True`). You might also need to set the `DJANGO_SETTINGS_MODULE` environment variable. Then, run your Django tests using the `coverage run` command, followed by `coverage html` to generate an interactive HTML report that includes template coverage.
import os
# Assume a Django project structure like:
# myproject/
# manage.py
# myproject/
# settings.py
# ...
# myapp/
# templates/
# myapp/my_template.html
# 1. Ensure Django settings are configured for template debugging
# In myproject/settings.py:
# TEMPLATES = [
# {
# 'BACKEND': 'django.template.backends.django.DjangoTemplates',
# 'DIRS': [],
# 'APP_DIRS': True,
# 'OPTIONS': {
# 'context_processors': [
# 'django.template.context_processors.debug',
# # ... other context processors
# ],
# 'debug': True, # THIS IS CRUCIAL!
# },
# },
# ]
# 2. Create or modify your .coveragerc or pyproject.toml
# For .coveragerc:
# [run]
# plugins = django_coverage_plugin
# source = .
#
# For pyproject.toml:
# [tool.coverage.run]
# plugins = [
# 'django_coverage_plugin',
# ]
# source = ['.']
# 3. Set DJANGO_SETTINGS_MODULE environment variable (if not already set)
# This is typically handled by manage.py, but explicit setting can avoid ImproperlyConfigured errors.
os.environ['DJANGO_SETTINGS_MODULE'] = os.environ.get('DJANGO_SETTINGS_MODULE', 'myproject.settings')
# 4. Run tests with coverage
# Execute this command in your project's root directory (where manage.py is):
# coverage run manage.py test
#
# 5. Generate a report (e.g., HTML)
# coverage html
# (This will create an 'htmlcov' directory with the report, including template coverage.)
print("Setup complete. Run 'coverage run manage.py test' then 'coverage html' from your project root.")
print(f"DJANGO_SETTINGS_MODULE is set to: {os.environ['DJANGO_SETTINGS_MODULE']}")
# Example of running tests with coverage (conceptually):
# import subprocess
# try:
# subprocess.run(['coverage', 'run', 'manage.py', 'test'], check=True)
# subprocess.run(['coverage', 'html'], check=True)
# print("Coverage report generated in htmlcov/")
# except subprocess.CalledProcessError as e:
# print(f"Error running coverage: {e}")
Debug
Known issues
breakingVersion 3.2.2 dropped support for Django 3.x and 4.x. Version 3.2.0 dropped support for Python 3.9 and Django 2.2. Version 3.1.1 dropped Python 3.8. Version 3.1.0 dropped Python 3.7 and Django 1.x. Version 3.0.0 dropped Python 2.7, 3.6, and Django 1.8. Ensure your Python and Django versions are compatible with the installed plugin version.fixUpgrade your Python and Django environments to currently supported versions (Python 3.10-3.14, Django 5.2-6.0 for v3.2.2) or use an older plugin version compatible with your environment.
affects: 3.0.0, 3.1.0, 3.1.1, 3.2.0, 3.2.2
gotchaDjango's template debugging must be enabled (`TEMPLATES.OPTIONS.debug = True`) in your settings file for the plugin to work correctly. If not enabled, template coverage will not be measured, or the plugin may raise a `DjangoTemplatePluginException`.fixSet `TEMPLATES[0]['OPTIONS']['debug'] = True` in your Django settings.py.
affects: All versions
gotchaThe `DJANGO_SETTINGS_MODULE` environment variable must be set correctly, especially when running `coverage run` directly without `manage.py` properly bootstrapping the environment. Failure to set this can lead to `django.core.exceptions.ImproperlyConfigured` errors.fixEnsure `DJANGO_SETTINGS_MODULE` is set, e.g., `os.environ['DJANGO_SETTINGS_MODULE'] = 'your_project.settings'` or by running via `manage.py test` as `coverage run manage.py test`.
affects: All versions
gotchaIn versions prior to 3.2.2, `{% endblock %}` lines (and similar tags) could be falsely reported as unexecuted if they appeared on their own indented line.fixUpgrade to version 3.2.2 or newer to resolve this false reporting.
affects: <3.2.2
gotchaFiles included by Django's `{% ssi %}` tag are not included in the coverage measurements by this plugin.fixBe aware of this limitation; these files will not appear in your template coverage report.
affects: All versions
Upgrade
Version history
3.2.2latest on PyPI · released Apr 4, 2026
Audit
Dependencies
coveragerequiredCore dependency for code coverage measurement; requires coverage.py 6.x or higher.
DjangorequiredFramework for which the plugin provides template coverage; supports Django 5.2 through 6.0.
pythonrequiredRuntime environment; requires Python 3.10 through 3.14.