WhiteNoise

Warnings

• breaking The `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.
  Fix: Explicitly 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`.
• breaking Compression (Gzip/Brotli) is disabled by default in WhiteNoise 5.0+. This can lead to a significant performance regression if not re-enabled.
  Fix: Explicitly 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.
• breaking The `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.
  Fix: Remove 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.
• gotcha In 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.
  Fix: Adjust 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 ] ```

Install

• pip install whitenoise Install core library
• pip install whitenoise[brotli,zopfli] Install with compression dependencies

Imports

• WhiteNoise

  from whitenoise import WhiteNoise

• WhiteNoiseMiddleware

  from whitenoise.middleware import WhiteNoiseMiddleware

  Used specifically for Django applications.

Quickstart

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