Install & Compatibility
Where this runs
tested against v0.30.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.000s · 77.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.8s · import 0.000s · 78MB
78MB installed
● package 78MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SpectacularAPIView
✓ from drf_spectacular.views import SpectacularAPIView
✗ from drf_spectacular.views import SpectacularAPIView
To integrate DRF Spectacular, add `drf_spectacular` to your `INSTALLED_APPS` and define `SPECTACULAR_SETTINGS` in your `settings.py`. Then, include the schema and UI views in your `urls.py`. The `SpectacularAPIView` serves the raw OpenAPI schema, while `SpectacularSwaggerView` and `SpectacularRedocView` provide interactive documentation UIs.
import os
from django.urls import path, include
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView
# --- In your Django settings.py ---
# INSTALLED_APPS = [
# # ...
# 'rest_framework',
# 'drf_spectacular',
# # ...
# ]
#
# SPECTACULAR_SETTINGS = {
# 'TITLE': os.environ.get('DRF_SPECTACULAR_TITLE', 'Your Project API'),
# 'DESCRIPTION': os.environ.get('DRF_SPECTACULAR_DESCRIPTION', 'Your project description'),
# 'VERSION': os.environ.get('DRF_SPECTACULAR_VERSION', '1.0.0'),
# 'SERVE_INCLUDE_SCHEMA': False, # Keep off for production, serve via SpectacularAPIView
# 'SWAGGER_UI_SETTINGS': {
# 'deepLinking': True,
# 'displayRequestDuration': True,
# },
# }
# --- In your Django urls.py ---
urlpatterns = [
path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
# Optional UI: path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
# Optional UI: path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
# path('api/', include('your_app.urls')), # Example for your API endpoints
]
# To run a minimal example (requires Django setup)
# from django.conf import settings
# if not settings.configured:
# settings.configure(
# INSTALLED_APPS=['django.contrib.auth', 'django.contrib.contenttypes', 'rest_framework', 'drf_spectacular'],
# SPECTACULAR_SETTINGS={'TITLE': 'Test API'},
# ROOT_URLCONF=__name__,
# DEBUG=True
# )
# This is a runnable snippet illustrating the `urls.py` config for drf-spectacular.
Debug
Known issues
breakingPydantic users might see a slightly different schema output due to changes in the serialization method. Review generated schemas carefully after upgrading.fixAfter upgrading to 0.28.0+, thoroughly test your API schema generation if you use Pydantic models. Adjust any client-side code that relies on specific Pydantic-derived schema structures.
affects: 0.28.0 and later
breakingWith the official support for OpenAPI 3.1 and Pydantic>=2, if you use a custom `postprocess_schema_enums` function, you might need to manually add `postprocess_schema_enum_id_removal` to remove temporary IDs.fixIf you have a custom `postprocess_schema_enums` function, ensure it also calls or manually implements the logic of `postprocess_schema_enum_id_removal` to clean up temporary enum IDs introduced for OpenAPI 3.1 compatibility.
affects: 0.27.0 and later
gotchaPython 3.6 support has been officially removed due to upstream library breakage. Attempts to use drf-spectacular on Python 3.6 will likely fail.fixEnsure your project is running on Python 3.7 or newer. Upgrade your Python environment if necessary.
affects: 0.27.2 and later
gotchaVersions prior to 0.29.0 contained a memory leak during schema generation, particularly noticeable with large or complex APIs.fixUpgrade to `drf-spectacular` version `0.29.0` or newer to benefit from the memory leak fix. Regular schema regeneration might be needed to mitigate effects in older versions.
affects: Before 0.29.0
gotchaFor API endpoints that are serializers marked `many=False` but are incorrectly inferred as lists in the OpenAPI schema, the `forced_singular_serializer` helper function is available.fixApply the `@extend_schema_serializer(many=False)` decorator or use the `drf_spectacular.utils.forced_singular_serializer` helper around your serializer if it's being misinterpreted as a list endpoint.
affects: 0.26.5 and later
gotchaAttempting to import `drf-spectacular` components that rely on Django Rest Framework settings without properly configuring Django (e.g., `DJANGO_SETTINGS_MODULE` environment variable not set, or `settings.configure()` not called) will raise a `django.core.exceptions.ImproperlyConfigured` exception.fixEnsure Django settings are properly configured before running `drf-spectacular` related code. For tests or scripts, this typically means setting the `DJANGO_SETTINGS_MODULE` environment variable to point to your project's settings file, or explicitly calling `django.conf.settings.configure()` with minimal required settings.
affects: All versions
breakingdrf-spectacular requires a properly configured Django environment. Attempting to import or use `drf-spectacular` components without Django settings loaded will result in a `django.core.exceptions.ImproperlyConfigured` exception.fixEnsure your Django project is correctly set up. For scripts or tests outside of a standard Django `manage.py` command, set the `DJANGO_SETTINGS_MODULE` environment variable (e.g., `export DJANGO_SETTINGS_MODULE=myproject.settings`) or explicitly call `django.conf.settings.configure()` with appropriate settings before importing any `drf-spectacular` or `djangorestframework` modules.
affects: All versions
Upgrade
Version history
0.30.0latest on PyPI · released Jul 6, 2026
Audit
Dependencies
DjangorequiredRequired for any Django project.
djangorestframeworkrequiredRequired as it extends Django REST Framework.
PyYAMLoptionalUsed for YAML schema generation; C version provides performance benefits.
PydanticoptionalRequired if Pydantic models are used in DRF serializers.