Django SASS Processor

1.4.2 · active · verified Thu Apr 16

Django SASS Processor compiles SCSS files into CSS dynamically during development or offline for production. It integrates seamlessly with Django's staticfiles system and provides template tags for easy inclusion of compiled CSS in templates. The current version is 1.4.2, with minor releases occurring every few months, and major versions (like 1.0.0) introducing breaking changes less frequently.

Common errors

```
ModuleNotFoundError: No module named 'sass_processor'
```
cause `django-sass-processor` is not installed or not properly configured in your Python environment.

fix Install the library: `pip install django-sass-processor`. If already installed, ensure your virtual environment is active.
```
django.template.library.InvalidTemplateLibrary: 'sass_processor' is not a registered tag library
```
cause The `sass_processor` app is missing from your Django project's `INSTALLED_APPS` setting.

fix Add `'sass_processor'` to your `INSTALLED_APPS` list in `settings.py`.
```
libsass-python: C compiler cannot create executables
```
cause The underlying `libsass-python` dependency requires a C/C++ compiler to build, which is not found on your system.

fix Install the necessary build tools for your operating system (e.g., `build-essential` on Linux, Xcode Command Line Tools on macOS, Visual C++ Build Tools on Windows).
```
The path to the SASS files is not defined.
```
cause The `SASS_PROCESSOR_ROOT` setting is not configured, or points to an invalid directory, preventing `django-sass-processor` from finding your SCSS files.

fix Set `SASS_PROCESSOR_ROOT` in `settings.py` to the absolute path of the directory containing your SCSS files (e.g., `os.path.join(BASE_DIR, 'sass')`).

Warnings

breaking In version 1.0.0, the `compilescss` management command's argument `--use-processor-root` was removed and replaced with `--use-storage`.
Fix: Update any scripts or commands that use `manage.py compilescss --use-processor-root` to `manage.py compilescss --use-storage`.
breaking In version 1.0.0, `SassS3Boto3Storage` was removed. It is no longer needed as `django-sass-processor` now works directly with standard `S3Boto3Storage` from `django-storages`.
Fix: If you were using `SassS3Boto3Storage`, switch to using `S3Boto3Storage` directly from `django-storages` in your `STATICFILES_STORAGE` setting.
gotcha Installation of `libsass-python` (a core dependency) often fails if a C/C++ compiler is not available on your system, leading to `error: Failed building wheel for libsass-python`.
Fix: Ensure you have build tools installed: On Debian/Ubuntu, `sudo apt-get install build-essential`. On macOS, `xcode-select --install`. On Windows, install Visual C++ Build Tools (part of Visual Studio installer) or use WSL.
gotcha During development (`DEBUG=True`), changes to SCSS files may not immediately reflect in the browser due to caching or the processor not detecting file changes.
Fix: Ensure `SASS_PROCESSOR_ENABLED = True` (default in DEBUG mode). Clear your browser cache. For persistent issues, manually force recompilation by running `python manage.py compilescss --force`.

Install

pip install django-sass-processor Install stable version

Imports

CssFinder
```
from sass_processor.finders import CssFinder
```
Used in STATICFILES_FINDERS configuration.

Quickstart

Configure `django-sass-processor` by adding it to `INSTALLED_APPS` and defining `SASS_PROCESSOR_ROOT`. Then, load the `sass_tags` in your templates to reference your compiled SCSS files. Remember to run `python manage.py collectstatic` in production.

import os

# settings.py snippet

INSTALLED_APPS = [
    # ... other Django apps
    'django.contrib.staticfiles',
    'sass_processor',
]

STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'staticfiles')

# Define where your SCSS files are located
SASS_PROCESSOR_ROOT = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'sass')

# Example template (e.g., templates/base.html)
# Make sure to create a directory 'sass' in your project root
# and add an example.scss file: sass/example.scss
# body {
#   color: blue;
# }

# To test, create a file named 'example.scss' in the SASS_PROCESSOR_ROOT directory:
# $body-color: blue;
# body {
#   color: $body-color;
# }

view raw JSON →