How to Use WhiteNoise in Django for Static Files

To use WhiteNoise in Django, install it via pip, add 'whitenoise.middleware.WhiteNoiseMiddleware' to your MIDDLEWARE in settings.py, and set STATIC_ROOT and STATICFILES_STORAGE to use WhiteNoise's storage class. This allows Django to serve static files directly in production without needing a separate web server.

Syntax

Here is the basic setup syntax to use WhiteNoise in a Django project:

• Install WhiteNoise with pip install whitenoise.
• Add 'whitenoise.middleware.WhiteNoiseMiddleware' to the MIDDLEWARE list in settings.py, preferably right after SecurityMiddleware.
• Set STATIC_ROOT to the directory where static files will be collected.
• Set STATICFILES_STORAGE to 'whitenoise.storage.CompressedManifestStaticFilesStorage' for efficient static file handling.

python

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',
    # other middleware
]

STATIC_ROOT = BASE_DIR / 'staticfiles'

STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

Example

This example shows a minimal Django settings.py snippet using WhiteNoise to serve static files in production.

python

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

INSTALLED_APPS = [
    'django.contrib.staticfiles',
    # other apps
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',
    # other middleware
]

STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / 'staticfiles'
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

# Run 'python manage.py collectstatic' before deploying

Output

When running the Django server in production mode, static files are served automatically at /static/ URLs without needing a separate web server.

Common Pitfalls

• Not adding WhiteNoiseMiddleware in the correct order can cause static files not to serve properly. It should come right after SecurityMiddleware.
• Forgetting to run python manage.py collectstatic means static files won't be collected to STATIC_ROOT and won't be served.
• Not setting STATICFILES_STORAGE to WhiteNoise's storage class can cause missing compression and caching benefits.
• Using WhiteNoise in development is unnecessary; Django's built-in static file serving is enough.

python

Wrong order example:
MIDDLEWARE = [
    'whitenoise.middleware.WhiteNoiseMiddleware',
    'django.middleware.security.SecurityMiddleware',  # wrong order
]

Correct order example:
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',
]

Quick Reference

Summary tips for using WhiteNoise in Django:

• Install with pip install whitenoise.
• Add middleware right after SecurityMiddleware.
• Set STATIC_ROOT and run collectstatic.
• Use CompressedManifestStaticFilesStorage for caching and compression.
• Use WhiteNoise only in production, not development.

Key Takeaways

Add WhiteNoise middleware right after SecurityMiddleware in settings.py.

Set STATIC_ROOT and run collectstatic to gather static files for serving.

Use WhiteNoise's CompressedManifestStaticFilesStorage for efficient static file handling.

WhiteNoise lets Django serve static files in production without extra servers.

Avoid using WhiteNoise middleware order incorrectly to prevent static file issues.