WhiteNoise

https://whitenoise.readthedocs.io
Admin
WhiteNoise is a radically simplified static file serving solution for Python WSGI web applications...
Tokens:22,100
Snippets:188
Trust Score:9.6
Update:15 hours ago
Show doc for...
Tokens:
Raw
### Install WhiteNoise with pip

Source: https://whitenoise.readthedocs.io/en/latest/

Install WhiteNoise using pip. This is the standard installation command.

```bash
pip install whitenoise
```

--------------------------------

### Enable WhiteNoise with Flask quick start

Source: https://whitenoise.readthedocs.io/en/latest/flask.html

Wrap the Flask WSGI app with WhiteNoise, specifying the root static folder. This is the minimal setup for serving static files.

```python
from flask import Flask
from whitenoise import WhiteNoise

app = Flask(__name__)
app.wsgi_app = WhiteNoise(app.wsgi_app, root="static/")
```

--------------------------------

### WHITENOISE_MIMETYPES example: mapping file extension to mimetype

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Example value for the WHITENOISE_MIMETYPES setting, mapping the '.foo' extension to 'application/x-foo'. WhiteNoise ships with its own default mimetypes and does not use system-supplied ones.

```python
{'.foo': 'application/x-foo'}
```

--------------------------------

### WHITENOISE_MIMETYPES example: mapping full filename to mimetype

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Example value for the WHITENOISE_MIMETYPES setting, mapping the entire filename 'some-special-file' to 'application/x-custom-type'. Mimetypes can be specified by file extension or by full filename.

```python
{'some-special-file': 'application/x-custom-type'}
```

--------------------------------

### Start Django development server with DEBUG disabled

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Run this command after setting DEBUG to False in settings.py to verify WhiteNoise serves static files locally as in production.

```bash
python manage.py runserver
```

--------------------------------

### Install WhiteNoise with Brotli support

Source: https://whitenoise.readthedocs.io/en/latest/changelog.html

Use this pip command to install WhiteNoise together with the Brotli compression library. The 'brotli' extra was added in version 4.0, replacing the previous brotlipy package.

```bash
pip install whitenoise[brotli]
```

--------------------------------

### Enable WhiteNoise with Flask app factory pattern

Source: https://whitenoise.readthedocs.io/en/latest/flask.html

Wrap the WSGI app inside a create_app function, including database setup and blueprint registration. This is for projects using the application factory pattern.

```python
from flask import Flask
from sqlalchemy import create_engine
from whitenoise import WhiteNoise

from myapp import config
from myapp.views import frontend


def create_app(database_uri, debug=False):
    app = Flask(__name__)
    app.debug = debug

    # set up your database
    app.engine = create_engine(database_uri)

    # register your blueprints
    app.register_blueprint(frontend)

    # add whitenoise
    app.wsgi_app = WhiteNoise(app.wsgi_app, root="static/")

    # other setup tasks

    return app
```

--------------------------------

### WHITENOISE_IMMUTABLE_FILE_TEST example: immutable_file_test

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Defines a function that returns True for URLs matching a filename with 12 hex digits before the extension, indicating immutable files. Set WHITENOISE_IMMUTABLE_FILE_TEST to this function in settings.

```python
def immutable_file_test(path, url):
    # Match filename with 12 hex digits before the extension
    # e.g. app.db8f2edc0c8a.js
    return re.match(r'^.+\. [0-9a-f]{12}\..+$', url)

WHITENOISE_IMMUTABLE_FILE_TEST = immutable_file_test
```

--------------------------------

### add_headers_function example: force download PDFs

Source: https://whitenoise.readthedocs.io/en/latest/base.html

Defines a function that adds a Content-Disposition header to force download for .pdf files. The function receives headers, path, and url; it modifies the headers dict directly and returns nothing.

```python
def force_download_pdfs(headers, path, url):
    if path.endswith('.pdf'):
        headers['Content-Disposition'] = 'attachment'

application = WhiteNoise(application,
                         add_headers_function=force_download_pdfs)
```

--------------------------------

### Directory layout for integrating frontend build tools with Django

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Shows the recommended directory layout for using Webpack/Browserify with Django: static_src -> static_build -> static_root, with commands for each step.

```text
./static_src
        ↓
  $ ./node_modules/.bin/webpack
        ↓
./static_build
        ↓
  $ ./manage.py collectstatic
        ↓
./static_root
```

--------------------------------

### Configure STORAGES for WhiteNoise compression and caching

Source: https://whitenoise.readthedocs.io/en/latest/

Add this to settings.py to enable forever-cacheable files and compression support using CompressedManifestStaticFilesStorage.

```python
STORAGES = {
    # ...
    "staticfiles": {
        "BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage",
    },
}
```

--------------------------------

### python -m whitenoise.compress --help

Source: https://whitenoise.readthedocs.io/en/latest/base.html

Shows the usage and options for the WhiteNoise compression utility. Requires the Brotli Python package for brotli compression. The command searches for files inside a root directory, excluding specified extensions, and produces .gz and .br files if they result in smaller files.

```bash
$ python -m whitenoise.compress --help
usage: compress.py [-h] [-q] [--no-gzip] [--no-brotli]
                   root [extensions [extensions ...]]

Search for all files inside <root> *not* matching <extensions> and produce
compressed versions with '.gz' and '.br' suffixes (as long as this results in
a smaller file)

positional arguments:
  root         Path root from which to search for files
  extensions   File extensions to exclude from compression (default: jpg,
               jpeg, png, gif, webp, zip, gz, tgz, bz2, tbz, xz, br, swf, flv,
               woff, woff2)

optional arguments:
  -h, --help   show this help message and exit
  -q, --quiet  Don't produce log output
  --no-gzip    Don't produce gzip '.gz' files
  --no-brotli  Don't produce brotli '.br' files

```

--------------------------------

### Alternative backend: CompressedStaticFilesStorage

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Use whitenoise.storage.CompressedStaticFilesStorage as the staticfiles backend if you want compression without caching behavior. This is an alternative to the CompressedManifestStaticFilesStorage backend.

```python
"whitenoise.storage.CompressedStaticFilesStorage"
```

--------------------------------

### Set FORCE_SCRIPT_NAME and STATIC_URL for subdirectory deployment

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Use these Django settings when deploying at a subdirectory prefix. FORCE_SCRIPT_NAME tells Django the app's location, and STATIC_URL must include the prefix. WhiteNoise will automatically configure itself when both are set.

```python
FORCE_SCRIPT_NAME = "/my-app"
STATIC_URL = FORCE_SCRIPT_NAME + "/static/"
```

--------------------------------

### immutable_file_test example: match hashed filenames

Source: https://whitenoise.readthedocs.io/en/latest/base.html

Defines a function that returns True for URLs matching a filename with 12 hex digits before the extension, indicating the file is immutable. The function receives path and url.

```python
def immutable_file_test(path, url):
    # Match filename with 12 hex digits before the extension
    # e.g. app.db8f2edc0c8a.js
    return re.match(r'^.+\. [0-9a-f]{12}\..+$', url)
```

--------------------------------

### WHITENOISE_ADD_HEADERS_FUNCTION example: force_download_pdfs

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Defines a function that adds a Content-Disposition header to PDF files. The function receives headers, path, and url, and modifies the headers dict directly. Set WHITENOISE_ADD_HEADERS_FUNCTION to this function in settings.

```python
def force_download_pdfs(headers, path, url):
    if path.endswith('.pdf'):
        headers['Content-Disposition'] = 'attachment'

WHITENOISE_ADD_HEADERS_FUNCTION = force_download_pdfs
```

--------------------------------

### Use static template tag for static files

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Use the Django 'static' template tag to reference static files instead of hardcoding URLs. The example shows the correct usage and the incorrect hardcoded alternative to avoid.

```html
{% load static %}
<img src="{% static "images/hi.jpg" %}" alt="Hi!">

<!-- DON'T WRITE THIS -->
<img src="/static/images/hi.jpg" alt="Hi!">
```

--------------------------------

### WhiteNoise constructor

Source: https://whitenoise.readthedocs.io/en/latest/base.html

Creates a WhiteNoise instance wrapping an existing WSGI application. Optionally configures the root directory and prefix for static files, and accepts configuration attributes via keyword arguments.

```APIDOC
## WhiteNoise(_application_, _root=None_, _prefix=None_, _\*\*kwargs_)

### Description
Creates a WhiteNoise instance that wraps an existing WSGI application to serve static files. On initialization, it walks over all files in the added directories and builds a list of available static files.

### Parameters
- **application** (callable) - Required - Original WSGI application
- **root** (str) - Optional - If set, passed to `add_files` method
- **prefix** (str) - Optional - If set, passed to `add_files` method
- **\*\*kwargs** - Optional - Sets configuration attributes for this instance

### Usage Example
```python
from whitenoise import WhiteNoise
from my_project import MyWSGIApp

application = MyWSGIApp()
application = WhiteNoise(application, root="/path/to/static/files")
```
```

--------------------------------

### Custom static folder with WhiteNoise.add_files

Source: https://whitenoise.readthedocs.io/en/latest/flask.html

Instantiate WhiteNoise without a root and add multiple static folders later using the add_files method. Useful when not using Flask's default static folder.

```python
from flask import Flask
from whitenoise import WhiteNoise

app = Flask(__name__)
app.wsgi_app = WhiteNoise(app.wsgi_app)
my_static_folders = (
    "static/folder/one/",
    "static/folder/two/",
    "static/folder/three/",
)
for static in my_static_folders:
    app.wsgi_app.add_files(static)
```

--------------------------------

### Configure STATIC_URL with CloudFront domain in settings.py

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Sets STATIC_HOST to a hardcoded CloudFront URL when DEBUG is False, and appends it to STATIC_URL. Use this when you want to hardcode your CDN domain in settings.

```python
STATIC_HOST = "https://d4663kmspf1sqa.cloudfront.net" if not DEBUG else ""
STATIC_URL = STATIC_HOST + "/static/"
```

--------------------------------

### Wrap WSGI application with WhiteNoise

Source: https://whitenoise.readthedocs.io/en/latest/

Wrap an existing WSGI application in a WhiteNoise instance and add static file directories.

```python
from whitenoise import WhiteNoise

from my_project import MyWSGIApp

application = MyWSGIApp()
application = WhiteNoise(application, root="/path/to/static/files")
application.add_files("/path/to/more/static/files", prefix="more-files/")
```

--------------------------------

### WhiteNoise.add_files

Source: https://whitenoise.readthedocs.io/en/latest/base.html

Adds a directory of static files to be served by WhiteNoise. Optionally specifies a URL prefix under which the files will be served.

```APIDOC
## WhiteNoise.add_files(_root_, _prefix=None_)

### Description
Adds a directory of static files to be served by WhiteNoise. The files are walked recursively and added to the list of available static files.

### Parameters
- **root** (str) - Required - Absolute path to a directory of static files to be served
- **prefix** (str) - Optional - If set, the URL prefix under which the files will be served. Trailing slashes are automatically added.

### Usage Example
```python
application.add_files("/path/to/more/static/files", prefix="more-files/")
```
```

--------------------------------

### Find static file with Django's findstatic command

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Use this command to debug 'ValueError: Missing staticfiles manifest entry for ...' by showing all paths Django searches for a file. Replace 'foo' with the actual filename.

```bash
python manage.py findstatic --verbosity 2 foo
```

--------------------------------

### Add whitenoise.runserver_nostatic to INSTALLED_APPS

Source: https://whitenoise.readthedocs.io/en/latest/django.html

Add 'whitenoise.runserver_nostatic' to the top of INSTALLED_APPS in settings.py to use WhiteNoise in development without passing --nostatic to runserver. Note that older versions of WhiteNoise (below v4.0) had issues with Channels, but newer versions work fine.

```python
INSTALLED_APPS = [
    # ...
    "whitenoise.runserver_nostatic",
    "django.contrib.staticfiles",
    # ...
]
```
Tokens:
Raw