Using with Flask

This guide explains how to use libsass with Flask web framework. sassutils package provides several tools that can be integrated to web applications written in Flask.

Directory layout

Imagine the project contained in such directory layout:


  • myapp/


    • static/

      • sass/

      • css/

    • templates/

Sass/SCSS files will go inside myapp/static/sass/ directory. Compiled CSS files will go inside myapp/static/css/ directory. CSS files can be regenerated, so add myapp/static/css/ into your ignore list like .gitignore or .hgignore.

Defining manifest

The sassutils defines a concept named manifest. Manifest is building settings of Sass/SCSS. It specifies some paths related to building Sass/SCSS:

  • The path of the directory which contains Sass/SCSS source files.

  • The path of the directory compiled CSS files will go.

  • The path, is exposed to HTTP (through WSGI), of the directory that will contain compiled CSS files.

Every package may have their own manifest. Paths have to be relative to the path of the package.

For example, in the project the package name is myapp. The path of the package is myapp/. The path of Sass/SCSS directory is static/sass/ (relative to the package directory). The path of CSS directory is static/css/. The exposed path is /static/css.

This settings can be represented as the following manifests:

    'myapp': ('static/sass', 'static/css', '/static/css')

As you can see the above, the set of manifests are represented in dictionary. Keys are packages names. Values are tuples of paths.

Building Sass/SCSS for each request

See also

Flask — Hooking in WSGI Middlewares

The section which explains how to integrate WSGI middlewares to Flask.

Flask — Application Dispatching

The documentation which explains how Flask dispatch each request internally.

In development, to manually build Sass/SCSS files for each change is so tiring. SassMiddleware makes the web application to automatically build Sass/SCSS files for each request. It’s a WSGI middleware, so it can be plugged into the web app written in Flask.

SassMiddleware takes two required parameters:

  • The WSGI-compliant callable object.

  • The set of manifests represented as dictionary.


from flask import Flask
from sassutils.wsgi import SassMiddleware

app = Flask(__name__)

app.wsgi_app = SassMiddleware(app.wsgi_app, {
    'myapp': ('static/sass', 'static/css', '/static/css')

And then, if you want to link a compiled CSS file, use url_for() function:

<link href="{{ url_for('static', filename='css/style.scss.css') }}"
      rel="stylesheet" type="text/css">


The linked filename is style.scss.css, not just style.scss. All compiled filenames have trailing .css suffix.

Building Sass/SCSS for each deployment


This section assumes that you use setuptools for deployment.

See also

Flask — Deploying with Setuptools

How to deploy Flask application using setuptools.

If libsass has been installed in the site-packages (for example, your virtualenv), script also gets had new command provided by libsass: build_sass. The command is aware of sass_manifests option of and builds all Sass/SCSS sources according to the manifests.

Add these arguments to script:

    # ...,
    setup_requires=['libsass >= 0.6.0'],
        'myapp': ('static/sass', 'static/css', '/static/css')

The setup_requires option makes sure that the libsass is installed in site-packages (for example, your virtualenv) before script. That means: if you run script and libsass isn’t installed yet at the moment, it will automatically install libsass first.

The sass_manifests specifies the manifests for libsass.

Now build_sass will compile all Sass/SCSS files in the specified path and generates compiled CSS files into the specified path (according to the manifests).

If you use it with sdist or bdist command, a packed archive also will contain compiled CSS files!

$ python build_sass sdist

You can add aliases to make these commands to always run build_sass command before. Make setup.cfg config:

sdist = build_sass sdist
bdist = build_sass bdist

Now it automatically builds Sass/SCSS sources and include compiled CSS files to the package archive when you run sdist.