Install & Compatibility
Where this runs
tested against v6.12.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.910 runs
installs and imports cleanly · install 0.0s · import 0.054s · 21.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.7s · import 0.049s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WhiteNoise
✓ from whitenoise import WhiteNoise
WhiteNoiseMiddleware
✓ from whitenoise.middleware import WhiteNoiseMiddleware
Used specifically for Django applications.
This quickstart demonstrates how to wrap a generic WSGI application with WhiteNoise to serve static files from a specified directory (`STATIC_ROOT`). The resulting `application` object can then be served by any WSGI server. Comments highlight optional but recommended production settings like compression and aggressive caching (`max_age`).
import os
from whitenoise import WhiteNoise
# Your existing WSGI application (e.g., from Django, Flask, or a simple function)
# For this example, we use a minimal dummy app:
def my_wsgi_app(environ, start_response):
status = '200 OK'
headers = [('Content-type', 'text/plain')]
start_response(status, headers)
return [b"Hello from the main WSGI app!"]
# Path to your static files (e.g., collected via Django's collectstatic)
# Ensure this directory exists and contains your static assets (e.g., 'staticfiles/hello.txt')
STATIC_ROOT = os.path.join(os.path.dirname(__file__), 'staticfiles')
# Wrap your WSGI application with WhiteNoise
# Basic setup: serves files from STATIC_ROOT at the root URL path ('/')
application = WhiteNoise(my_wsgi_app, root=STATIC_ROOT,
# For production, consider enabling compression and setting a max_age:
# gzip=True, brotli=True, # Requires 'zopfli' and 'brotli' packages
# max_age=31536000 # Cache static files for 1 year in browsers
)
# If you need to serve additional static directories or with specific URL prefixes:
# application.add_files('/path/to/another/static/dir', prefix='another-prefix/')
# The 'application' object is now ready to be served by any WSGI server
# e.g., gunicorn -w 4 your_project.wsgi:application
Debug
Known issues
breakingThe `max_age` default for static file caching was changed. In version 6.0+, it's 0 (no caching) in development and 60 seconds in production. Previously, it was 1 year by default.fixExplicitly set `max_age` for production deployments, e.g., `max_age=31536000` for one year of caching. For Django, this is typically done in `settings.py` via `WHITENOISE_MAX_AGE`.
affects: 6.0.0+
breakingCompression (Gzip/Brotli) is disabled by default in WhiteNoise 5.0+. This can lead to a significant performance regression if not re-enabled.fixExplicitly enable compression by passing `gzip=True` and `brotli=True` to the `WhiteNoise` constructor or by setting `WHITENOISE_GZIP=True` and `WHITENOISE_BROTLI=True` in Django `settings.py`. Remember to install `zopfli` and `brotli` packages.
affects: 5.0.0+
breakingThe `WhiteNoise.configure()` method was removed in version 6.0.0. All configuration must now be passed directly to the `WhiteNoise` constructor or, for Django, via `settings.py` variables.fixRemove calls to `configure()`. Pass all options as keyword arguments when initializing `WhiteNoise(app, root='/path/to/static', **options)` or use Django settings like `WHITENOISE_ROOT`, `WHITENOISE_MAX_AGE`, etc.
affects: 6.0.0+
gotchaIn Django applications, the order of `WhiteNoiseMiddleware` in `MIDDLEWARE` is critical. It should be placed after `django.middleware.security.SecurityMiddleware` and any other middleware that may redirect or rewrite URLs, but *before* `django.contrib.sessions.middleware.SessionMiddleware` and *especially before* `django.middleware.gzip.GZipMiddleware` if you are using both.fixAdjust your `MIDDLEWARE` setting in `settings.py` similar to this:
```python
MIDDLEWARE = [
'django.middleware.security.SecurityMiddleware',
'whitenoise.middleware.WhiteNoiseMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
# ... other middleware
]
``` affects: All versions with Django
Upgrade
Version history
6.12.0latest on PyPI · released Feb 27, 2026
Audit
Dependencies
brotlioptionalOptional: For Brotli compression of static files.
zopflioptionalOptional: For Zopfli/Gzip compression of static files.