Serving Static Files with Django

Image designed by me

Serving static files with Django has been a hit-and-miss for me. It usually follows the same pattern: the application works perfectly locally, I deploy the application, I realize my static files are not loading, I mess around with the nginx configuration, check if it works (it usually differs based on the hosting environment), and do it all over again.

After resolving the issue numerous times, I sincerely cannot tell you what method works, just trying and prodding the server configuration until something good happens. Until I discovered the Whitenoise library.

It turns out the library author was in the same shoes as I was, having explained the complexities of serving static files with Django using the server configurations. Here are their exact words:

What’s the point in WhiteNoise when I can do the same thing in a few lines of Apache/nginx config?

…WhiteNoise is designed to work in situations where Apache, nginx and the like aren’t easily available. But more importantly, it’s easy to underestimate what’s involved in serving static files correctly. Does your few lines of nginx config distinguish between files which might change and files which will never change and set the cache headers appropriately? Did you add the right CORS headers so that your fonts load correctly when served via a CDN? Did you turn on the special nginx setting which allows it to send gzipped content in response to an HTTP/1.0 request, which for some reason CloudFront still uses? Did you install the extension which allows you to serve pre-compressed brotli-encoded content to modern browsers?

I did a combination of these, and more, to get it to work!

Using Whitenoise middleware

It’s better to refer to the documentation (linked below) for a detailed overview of the library, but I will share a simple way you can get started.

First, install the library (in the same virtual environment of your Django application):

pip install whitenoise

Add the middleware to the list of middleware in settings.py:

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

Update the settings for your static files in settings.py:

STATIC_URL = 'static/'
STATIC_ROOT = 'static'

STATIC_URL refers to the endpoint where files will be served from, for example, a URL of “static/” serves http://yourdomain.com/static/css/app.css

STATIC_ROOT refers to the folder location of your static files, in this case, the static folder in the root.

Run the Django collectstatic command:

python manage.py collectstatic

And that’s it. Your files can now be served properly. To test this without doing much, run the createsuperuser command and access your Django admin. If it works the page should load its styles and script correctly.

When should I use it?

As I wrote in an earlier article, a critical part of programming knowledge is knowing when to do things yourself or let others do them. I have been serving static files in Django myself by tweaking the server configurations but once I knew better, I decided it was better to let Whitenoise handle it for me.

If you prefer to handle it yourself because you need some custom behavior, or you just want to learn how it works, go for it. Also, if you do decide to use Whitenoise, take some time to learn some of its caveats and how to mitigate them. For example, Whitenoise slows down your application start-up time making your tests run too slow, and this can be resolved by adding WHITENOISE_AUTOREFRESH = True in your settings file (recommended for development).

Learn more from its official documentation for Django here:

Using WhiteNoise with Django - WhiteNoise 6.8.2 documentation

Further reading

Middleware | Django documentation

Don’t Over-Abstract — Stop Writing Code That Only You Understand

How to manage static files (e.g. images, JavaScript, CSS) | Django documentation

Managing Static Files in Django: A Comprehensive Guide - SitePoint