Install & Compatibility
Where this runs
tested against v2.5 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 140.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.4s · import 0.000s · 141MB
144MB installed
● package 144MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinxcontrib_django
✓ extensions = ['sphinx.ext.autodoc', 'sphinxcontrib_django']
This library is a Sphinx extension, not typically imported directly in Python code. It is added to the `extensions` list in `conf.py`.
To quickly set up `sphinxcontrib-django`, first install it via pip. Then, create your Sphinx documentation project using `sphinx-quickstart`. Edit your `conf.py` file to include `sphinxcontrib_django` in the `extensions` list, configure the path to your Django project, set the `DJANGO_SETTINGS_MODULE` environment variable, and call `django.setup()`. This ensures Sphinx can properly load and inspect your Django models and forms. Remember to adjust `sys.path.insert` and `django_settings` to match your project structure. For Sphinx versions 9 and above, you might need to enable `autodoc_use_legacy_class_based`.
import os
import sys
import django
# Adjust this path to your Django project's root directory
sys.path.insert(0, os.path.abspath('../src'))
# Configure Django settings module
os.environ['DJANGO_SETTINGS_MODULE'] = 'myproject.settings'
# Initialize Django
django.setup()
# -- Project information -----------------------------------------------------
project = 'My Django Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1'
# -- General configuration ---------------------------------------------------
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinxcontrib_django',
]
intersphinx_mapping = {
'django': ('https://docs.djangoproject.com/en/stable/', 'https://docs.djangoproject.com/en/stable/_objects'),
'python': ('http://docs.python.org/', None),
}
# sphinxcontrib-django specific configuration
django_settings = 'myproject.settings'
# Required for Sphinx >= 9 with autodoc
# autodoc_use_legacy_class_based = True
# Optional: show database table names
django_show_db_tables = True
Debug
Known issues
breakingWhen using Sphinx 9.x or later, the `autodoc_use_legacy_class_based = True` setting might be required in `conf.py` to ensure proper autodoc functionality with Django classes. Failure to do so can result in incomplete or incorrect documentation.fixAdd `autodoc_use_legacy_class_based = True` to your `conf.py` file.
affects: Sphinx >= 9.0
gotchaFailure to correctly configure Django settings can lead to `ImproperlyConfigured` exceptions during the Sphinx build process, preventing documentation generation. This typically happens when Django's environment is not properly set up before autodoc attempts to import models or forms.fixEnsure `os.environ['DJANGO_SETTINGS_MODULE']` is set to your project's settings file and `django.setup()` is called in your `conf.py` before any Django-dependent imports. Also, add your Django project's root to `sys.path`.
affects: All versions
deprecatedPrevious versions of `sphinxcontrib-django` (and underlying Django/Python versions) have dropped support for older Python and Django releases. Ensure your environment matches the library's requirements to avoid compatibility issues.fixCheck the `CHANGES.rst` or release notes for your specific `sphinxcontrib-django` version to confirm compatibility with your Python and Django versions. Upgrade `sphinxcontrib-django`, Python, or Django as necessary.
affects: < 2.0 (e.g., versions prior to 2.2 dropped Python 2.7/3.5 and Django < 2.2 support)
Upgrade
Version history
2.5latest on PyPI · released Sep 26, 2023
Audit
Dependencies
SphinxrequiredCore documentation generation engine, required by the extension.
DjangorequiredThe framework whose applications are being documented.