Using WhiteNoise with Flask#

This guide walks you through setting up a Flask project with WhiteNoise. In most cases it shouldn’t take more than a couple of lines of configuration.

1. Make sure where your static is located#

If you’re familiar with Flask you’ll know what to do. If you’re just getting started with a new Flask project then the default is the static folder in the root path of the application.

Check the static_folder argument in Flask Application Object documentation for further information.

2. Enable WhiteNoise#

In the file where you create your app you instantiate Flask Application Object (the flask.Flask() object). All you have to do is to wrap it with WhiteNoise() object.

If you use Flask quick start approach it will look something like that:

from flask import Flask
from whitenoise import WhiteNoise

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

If you opt for the pattern of creating your app with a function, then it would look like that:

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

That’s it – WhiteNoise will now serve your static files.

3. Custom static folder#

If it turns out that you are not using the Flask default for static folder, fear not. You can instantiate WhiteNoise and add your static folders later:

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)

See the WhiteNoise.add_files documentation for further customization.

4. Prefix#

By default, WhiteNoise will serve up static files from the URL root – i.e., http://localhost:5000/style.css.

To change that, set a prefix string:

app.wsgi_app = WhiteNoise(app.wsgi_app, root="static/", prefix="assets/")

Now, style.css will be available at http://localhost:5000/assets/style.css.