DRF Spectacular Sidecar

2026.4.1 · active · verified Sat Apr 11

drf-spectacular-sidecar is a Django application that serves self-contained distribution builds of Swagger UI and Redoc. It acts as an optional addition to `drf-spectacular` for environments without CDN access, but can also be used independently. The project is actively maintained, with versions updated monthly (around the 1st) by sourcing distribution files from npm via jsdelivr. The current version is 2026.4.1.

Warnings

gotcha Content 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.
Fix: Consult the `drf-spectacular` FAQ on CSP issues for specific `SPECTACULAR_SETTINGS` and `CSP_DEFAULT_SRC` adjustments.
breaking When 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.
Fix: This 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.
gotcha It 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.
Fix: Ensure `drf_spectacular_sidecar` is explicitly listed in `INSTALLED_APPS`.
gotcha The `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.
Fix: Understand 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/`).

Install

pip install drf-spectacular-sidecar Install with pip

Imports

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.

Quickstart

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
}

view raw JSON →