- Breaking changes
- The latest version of WhiteNoise removes some options which were deprecated in the previous major release:
- The WSGI integration option for Django
(which involved editing
wsgi.py) has been removed. Instead, you should add WhiteNoise to your middleware list in
settings.pyand remove any reference to WhiteNoise from
wsgi.py. See the documentation for more details.
(The pure WSGI integration is still available for non-Django apps.)
whitenoise.django.GzipManifestStaticFilesStoragealias has now been removed. Instead you should use the correct import path:
If you are not using either of these integration options you should have no issues upgrading to the latest version.
Index file support¶
WhiteNoise now supports serving index files for
directories (e.g. serving
/example/). It also
creates redirects so that visiting the index file directly, or visiting the URL
without a trailing slash will redirect to the correct URL.
Range header support (“byte serving”)¶
WhiteNoise now respects the HTTP Range header which allows a client to request only part of a file. The main use for this is in serving video files to iOS devices as Safari refuses to play videos unless the server supports the Range header.
WhiteNoise now adds ETag headers to files using the same algorithm used by
nginx. This gives slightly better caching behviour than relying purely on Last
Modified dates (although not as good as creating immutable files using
ManifestStaticFilesStorage, which is still the best option
if you can use it).
If you need to generate your own ETags headers for any reason you can define a
Customisable immutable files test¶
WhiteNoise ships with code which detects when you are using Django’s
ManifestStaticFilesStorage backend and sends optimal caching headers for files
which are guaranteed not to change. If you are using a different system for
generating cacheable files then you might need to supply your own function for
detecting such files. Previously this required subclassing WhiteNoise, but now
you can use the
Fix runserver_nostatic to work with Channels¶
The old implementation of runserver_nostatic (which disables Django’s default static file handling in development) did not work with Channels, which needs its own runserver implementation. The runserver_nostatic command has now been rewritten so that it should work with Channels and with any other app which provides its own runserver.
Reduced storage requirements for static files¶
WHITENOISE_KEEP_ONLY_HASHED_FILES setting reduces the number of
files in STATIC_ROOT by half by storing files only under their hashed names
app.db8f2edc0c8a.js), rather than also keeping a copy with the
original name (e.g.
Improved start up performance¶
When in production mode (i.e. when
is disabled), WhiteNoise scans all static files when the application starts in
order to be able to serve them as efficiently and securely as possible. For
most applications this makes no noticeable difference to start up time, however
for applications with very large numbers of static files this process can take
some time. In WhiteNoise 4.0 the file scanning code has been rewritten to do
the minimum possible amount of filesystem access which should make the start up
process considerably faster.
WhiteNoise has always aimed to support Windows as well as *NIX platforms but we are now able to run the test suite against Windows as part of the CI process which should ensure that we can maintain Windows compatibility in future.
Modification times for compressed files¶
The compressed storage backend (which generates Gzip and Brotli compressed files) now ensures that compressed files have the same modification time as the originals. This only makes a difference if you are using the compression backend with something other than WhiteNoise to actually serve the files, which very few users do.
- Support the new immutable Cache-Control header. This gives better caching behaviour for immutable resources than simply setting a large max age.
- Gracefully handle invalid byte sequences in URLs.
- Gracefully handle filenames which are too long for the filesystem.
- Send correct Content-Type for Adobe’s
- Convert any config values supplied as byte strings to text to avoid runtime encoding errors when encountering non-ASCII filenames.
- Handle non-ASCII URLs correctly when using the
- Fix exception triggered when a static files “finder” returned a directory rather than a file.
- Add support for the new-style middleware classes introduced in Django 1.10. The same WhiteNoiseMiddleware class can now be used in either the old
MIDDLEWARE_CLASSESlist or the new
- Fixed a bug where incorrect Content-Type headers were being sent on 304 Not Modified responses (thanks @oppianmatt).
- Return Vary and Cache-Control headers on 304 responses, as specified by the RFC.
- Add new
WHITENOISE_STATIC_PREFIXsetting to give flexibility in supporting non-standard deployment configurations e.g. serving the application somewhere other than the domain root.
- Fix bytes/unicode bug when running with Django 1.10 on Python 2.7
The latest version of WhiteNoise contains some small breaking changes. Most users will be able to upgrade without any problems, but some less-used APIs have been modified:
- The setting
WHITENOISE_GZIP_EXCLUDE_EXTENSIONShas been renamed to
- The CLI compression utility has moved from
python -m whitenoise.gzipto
python -m whitenoise.compress.
- The now redundant
gzipstaticmanagement command has been removed.
- WhiteNoise no longer uses the system mimetypes files, so if you are serving particularly obscure filetypes you may need to add their mimetypes explicitly using the new
- Older versions of Django (1.4-1.7) and Python (2.6) are no longer supported. If you need support for these platforms you can continue to use WhiteNoise 2.x.
whitenoise.django.GzipManifestStaticFilesStoragestorage backend has been moved to
whitenoise.storage.CompressedManifestStaticFilesStorage. The old import path will continue to work for now, but users are encouraged to update their code to use the new path.
Simpler, cleaner Django middleware integration¶
WhiteNoise can now integrate with Django by adding a single line to
MIDDLEWARE_CLASSES without any need to edit
wsgi.py. This also means
that WhiteNoise plays nicely with other middleware classes such as
SecurityMiddleware, and that it is fully compatible with the new Channels
system. See the updated documentation for details.
Brotli compression support¶
Brotli is the modern, more efficient alternative to gzip for HTTP
compression. To benefit from smaller files and faster page loads, just install
the brotlipy library, update your
requirements.txt and WhiteNoise
will take care of the rest. See the documentation
It’s now possible to add custom headers to WhiteNoise without needing to create
a subclass, using the new
Use WhiteNoise in development with Django¶
There’s now an option to force Django to use WhiteNoise in development, rather than its own static file handling. This results in more consistent behaviour between development and production environments and fewer opportunities for bugs and surprises. See the documentation for details.
Improved mimetype handling¶
WhiteNoise now ships with its own mimetype definitions (based on those shipped
with nginx) instead of relying on the system ones, which can vary between
environments. There is a new
configuration option which makes it easy to add additional type definitions if
- Rebuild with latest version of wheel to get extras_require support.
- Add missing argparse dependency for Python 2.6 (thanks @movermeyer)).
- Report path on MissingFileError (thanks @ezheidtmann).
- Add __version__ attribute.
- More helpful error message when STATIC_URL is set to the root of a domain (thanks @dominicrodger).
- Add support for Python 2.6.
- Add a more helpful error message when attempting to import DjangoWhiteNoise before DJANGO_SETTINGS_MODULE is defined.
- Add an autorefresh mode which picks up changes to static files made after application startup (for use in development).
- Add a use_finders mode for DjangoWhiteNoise which finds files in their original directories without needing them collected in STATIC_ROOT (for use in development). Note, this is only useful if you don’t want to use Django’s default runserver behaviour.
- Remove the follow_symlinks argument from add_files and now always follow symlinks.
- Support extra mimetypes which Python doesn’t know about by default (including .woff2 format)
- Some internal refactoring. Note, if you subclass WhiteNoise to add custom behaviour you may need to make some small changes to your code.
- Fix unhelpful exception inside make_helpful_exception on Python 3 (thanks @abbottc).
- Fix error when attempting to gzip empty files (thanks @ryanrhee).
- Don’t attempt to gzip
.wofffiles as they’re already compressed.
- Base decision to gzip on compression ratio achieved, so we don’t incur gzip overhead just to save a few bytes.
- More helpful error message from
collectstaticif CSS files reference missing assets.
- Fix bug in Last Modified date handling (thanks to Atsushi Odagiri for spotting).
- Set the default max_age parameter in base class to be what the docs claimed it was.
- Fix path-to-URL conversion for Windows.
- Remove cruft from packaging manifest.
- First stable release.