Django Dart Sass Finder
A static files finder for Django that compiles Sass files
This continues the original django-sass-finder,
which no longer works with current Django or Python. The settings and the finder to configure are
the same (the module is still django_sass_finder); what is new is the compiler, which is now
Dart Sass. See the changelog for what to check when upgrading.
Installation
WARNING: MAKE SURE YOU HAVE NO OTHER SASS PACKAGES INSTALLED!
Run pip install django-dart-sass-finder to add this module to your virtualenv (it is imported as
django_sass_finder), then install the Sass compiler (see below), and add the finder to the list of
your static file finders. If you used the original django-sass-finder package, uninstall it first:
it installs a module of the same name.
STATICFILES_FINDERS = [
# add the default Django finders as this setting will override the default
'django.contrib.staticfiles.finders.FileSystemFinder',
'django.contrib.staticfiles.finders.AppDirectoriesFinder',
# our finder
'django_sass_finder.finders.ScssFinder',
]
There is no need to add django_sass_finder into settings.INSTALLED_APPS.
The compiler
By default the finder compiles with Dart Sass, the reference
implementation of Sass, which supports the modern @use/@forward module system. It is a
separate program rather than a Python package, so install it into your virtualenv with:
python -m django_sass_finder.install
This downloads the official release for your platform from GitHub, verifies its SHA-256
checksum, and links sass into the virtualenv's bin directory, so it is on PATH whenever the
virtualenv is active. The finder also finds it there when you run the virtualenv's python directly.
Any other Dart Sass on PATH (for example from npm install sass) works too.
The version installed is, in order of precedence: --version on the command line, the
DART_SASS_VERSION environment variable, dart-sass-version in your pyproject.toml
(searching upwards from the current directory), or the version this package was tested with:
[tool.django-sass-finder]
dart-sass-version = "1.108.1"
Run the install command again after changing the version (and in CI, Docker builds, etc.).
LibSass (legacy)
LibSass is deprecated, does not support @use
and has known security issues. It is still available to ease migration:
pip install "django-dart-sass-finder[libsass]" and set SCSS_COMPILER = 'libsass'.
Settings
The following additional (with examples) settings are used by this staticfiles finder:
BASE_DIR = ...
SCSS_ROOT = BASE_DIR / 'scss' # required: where the .scss files are sourced
SCSS_COMPILE = [ # a list of filename pattern to search for within SCSS_ROOT
'site.scss', # default is **/*.scss (all scss source files in and below SCSS_ROOT)
'admin/admin.scss', # files whose name starts with an underscore are partials: never compiled on their own
]
SCSS_INCLUDE_PATHS = [ # optional: scss compiler include (load) paths (default = empty)
BASE_DIR / 'node_modules'
]
SCSS_COMPILER = 'dart' # optional: 'dart' (default), 'libsass' or a dotted path to a Compiler class
SCSS_EXECUTABLE = None # optional: path of the sass executable (default: search for it)
SCSS_RESCAN_INTERVAL = 0.5 # optional: look for changed sources at most this often (seconds)
CSS_STYLE = 'compressed' # optional: output format, 'expanded' or 'compressed'
# (libsass also has 'nested' and 'compact')
CSS_MAP = True # optional: generate a source map, next to the css as {name}.css.map
CSS_COMPILE_DIR = BASE_DIR / 'static' / 'css' # optional: The target directories for the compiled .css
STATICFILES_DIRS = [ # this should be at or above the CSS_COMPILE_DIR
BASE_DIR / 'static' # but targetting {app}/static should also work
]
BASE_DIR and variants above are pathlib.Path objects, but path strings can also be used.
If CSS_COMPILE_DIR is not set, the SCSS_ROOT is used and css (and map) files are generated next to the scss source files.
Django's system checks (manage.py check) report a missing compiler, a SCSS_COMPILER that cannot be
loaded, an unsupported CSS_STYLE, and SCSS_COMPILE patterns that match no files or only partials.
Usage
This module dynamically compiles to target .css files, and recompiles them on demand whenever
the source files are updated. A file is recompiled when it, or any file it loads (@use, @import),
changes. Without CSS_MAP a restarted server cannot tell what an earlier run loaded, so it compiles
every file once at start up; with CSS_MAP it reads that back from the source maps.
The collectstatic management command compiles these and copies them into STATIC_ROOT along with
the usual files from STATICFILES_DIRS and app static directories.
The development server is perfectly able to serve these from STATICFILES_DIRS without the need
to run collectstatic.
Limitations:
- Compile into an output directory from one process at a time. Two processes (for example two
collectstaticruns) compiling the same files at once can leave a partly written file behind. - The output of a source is removed when that source is deleted while the finder is running. If a
source was deleted while the server was stopped, delete its
.css(and.css.map) by hand; a file that cannot be removed is logged as a warning and left alone.
Continuous integration
Install the package, then run the same command as above, before anything that compiles:
- run: uv sync --locked
- run: uv run python -m django_sass_finder.install
(or pip install . followed by python -m django_sass_finder.install). No separate setup action is
needed, and the archive is small (about 4 MB).
License
This package is licensed under the MIT license.
Metadata
Release files for django-dart-sass-finder 3.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_dart_sass_finder-3.0.0.tar.gz | 16.3 kB | Without provenance | Details for django_dart_sass_finder-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_dart_sass_finder-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for django_dart_sass_finder-3.0.0-py3-none-any.whl |
Total release size: 35.4 kB
Release files / django_dart_sass_finder-3.0.0.tar.gz
| Download URL | django_dart_sass_finder-3.0.0.tar.gz |
|---|---|
| Size | 16.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9d2e5182b6fa32b138648a857f63cfe430446afa1d36b0a1853f9540c728f600
|
|
BLAKE2b-256 checksum How to use checksums |
a6c809f1c286d455abf6d63b39ca8c6b5553d418402edfa8bad8062917dc4cf4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / django_dart_sass_finder-3.0.0-py3-none-any.whl
| Download URL | django_dart_sass_finder-3.0.0-py3-none-any.whl |
|---|---|
| Size | 19.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8165a4475f8e4ade97418deed490c20114ea677f7342d4960d98f4b901749b55
|
|
BLAKE2b-256 checksum How to use checksums |
f2bfe2e78836b4e25457aa69129840a5297e35d15029d0b384fc8b583dc5e7f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for django-dart-sass-finder 3.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.