Registry /
web-framework / drf-spectacular-sidecar
Install & Compatibility
Where this runs
tested against v2026.8.1 · 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 · 75.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.5s · import 0.000s · 76MB
75MB installed
● package 75MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
drf_spectacular_sidecar
✓ INSTALLED_APPS = [
# ...
'drf_spectacular_sidecar',
# ...
]
The library itself is a Django app that provides static files; it's activated by adding it to INSTALLED_APPS, not by direct Python imports for typical usage.
After installation, add `drf_spectacular_sidecar` to your Django project's `INSTALLED_APPS`. If you are using `drf-spectacular`, configure `SPECTACULAR_SETTINGS` to point `SWAGGER_UI_DIST`, `SWAGGER_UI_FAVICON_HREF`, and `REDOC_DIST` to `'SIDECAR'` to utilize the locally served assets.
# settings.py
INSTALLED_APPS = [
# ... your other apps
'drf_spectacular_sidecar',
'drf_spectacular', # Only if you are using drf-spectacular
# ...
]
# Only if you are using drf-spectacular and want to use the sidecar for UI assets
SPECTACULAR_SETTINGS = {
'SWAGGER_UI_DIST': 'SIDECAR',
'SWAGGER_UI_FAVICON_HREF': 'SIDECAR',
'REDOC_DIST': 'SIDECAR',
# ... other drf-spectacular settings
}
Debug
Known issues
gotchaContent Security Policy (CSP) errors, especially with libraries like `django-csp`, can prevent Swagger UI or Redoc from displaying correctly. The sidecar mitigates issues with external asset loading, but you might still need to adjust `CSP_DEFAULT_SRC` for `unsafe-inline` scripts or consider `SpectacularSwaggerSplitView` as an alternative.fixConsult the `drf-spectacular` FAQ on CSP issues for specific `SPECTACULAR_SETTINGS` and `CSP_DEFAULT_SRC` adjustments.
affects: All versions
breakingWhen using custom static file storage backends (e.g., `ManifestStaticFilesStorage`, Amazon S3 via `django-storages`), the sidecar may fail to correctly resolve static file paths, leading to broken UI or `collectstatic` errors. This often manifests as attempts to load from `/static/` instead of the configured storage.fixThis is a complex issue; refer to `drf-spectacular` GitHub issues #718 and #847 for potential workarounds or updates. A common fix involves ensuring proper usage of Django's staticfiles storage mechanisms or overriding URL resolution.
affects: Versions affected by drf-spectacular issues #718 and #847 (specifically from 2022.4.x onwards that incorporated changes related to #718).
gotchaIt is crucial to add `'drf_spectacular_sidecar'` to your `INSTALLED_APPS` in `settings.py`. Failing to do so will prevent Django from discovering and serving the necessary static files for Swagger UI and Redoc, resulting in blank or non-functional documentation pages.fixEnsure `drf_spectacular_sidecar` is explicitly listed in `INSTALLED_APPS`.
affects: All versions
gotchaThe `drf-spectacular-sidecar` package is intended to serve static UI files locally, not to integrate a documentation interface directly into the Django Admin. Misunderstanding this purpose can lead to incorrect expectations about its functionality.fixUnderstand that the sidecar provides the raw static assets for the UI, which `drf-spectacular` then uses to render the documentation pages at specified URLs (e.g., `/api/schema/swagger-ui/`).
affects: All versions
Upgrade
Version history
2026.8.1latest on PyPI · released Aug 1, 2026
Audit
Dependencies
DjangorequiredRequired for integration as a Django application.
drf-spectacularoptionalTypically used in conjunction with drf-spectacular to provide local Swagger UI/Redoc assets.