Install & Compatibility
Where this runs
tested against v4.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 67.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.8s · import 0.000s · 68MB
67MB installed
● package 67MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
compress
✓ from compressor.templatetags.compress import compress
✗ from compressor.templatetags.compress import compress
To quickly integrate Django Compressor, add 'compressor' to `INSTALLED_APPS` and 'compressor.finders.CompressorFinder' to `STATICFILES_FINDERS`. Define `STATIC_URL` and `STATIC_ROOT`. Use the `{% load compress %}` and `{% compress css %}`/`{% compress js %}` template tags around your static and inline assets. For production, set `COMPRESS_ENABLED = True` and typically `COMPRESS_OFFLINE = True`, then run `python manage.py collectstatic` followed by `python manage.py compress` during deployment to pre-process assets.
import os
# settings.py example
DEBUG = True # Or False, affects compression behavior
INSTALLED_APPS = [
# ... other apps
'django.contrib.staticfiles',
'compressor',
]
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'staticfiles')
STATICFILES_FINDERS = (
'django.contrib.staticfiles.finders.FileSystemFinder',
'django.contrib.staticfiles.finders.AppDirectoriesFinder',
'compressor.finders.CompressorFinder',
)
# COMPRESS_ENABLED defaults to not DEBUG. Set explicitly for consistent behavior.
COMPRESS_ENABLED = not DEBUG # For production, typically True
COMPRESS_OFFLINE = True # For pre-compressing assets during deployment
# Example template (e.g., base.html)
# {% load static compress %}
#
# <head>
# {% compress css %}
# <link rel="stylesheet" href="{% static 'css/base.css' %}">
# <style>body { font-family: sans-serif; }</style>
# {% endcompress %}
# </head>
# <body>
# <!-- Content -->
# {% compress js %}
# <script src="{% static 'js/main.js' %}"></script>
# <script>console.log('Hello from inline JS!');</script>
# {% endcompress %}
# </body>
# --- Steps to run ---
# 1. Add above settings to your project's settings.py.
# 2. Add the template code to one of your Django templates.
# 3. Create static/css/base.css and static/js/main.js in an app's static directory.
# 4. Run:
# python manage.py collectstatic --noinput
# python manage.py compress
# 5. Start development server:
# python manage.py runserver
# 6. View the rendered page source; you should see compressed CSS/JS links.
Debug
Known issues
gotchaThe `COMPRESS_ENABLED` setting (defaulting to `not DEBUG`) significantly alters behavior. If `DEBUG` is True and `COMPRESS_ENABLED` is also True, inaccessible or non-existent linked files within `{% compress %}` blocks will raise exceptions. If `DEBUG` is False, these files are silently stripped. Always test compression behavior explicitly, especially when `DEBUG` is True.fixFor consistent testing of compressed output in development, explicitly set `COMPRESS_ENABLED = True` in your settings. For production, ensure `COMPRESS_ENABLED = True` and consider `COMPRESS_OFFLINE = True`.
affects: All versions
gotchaWhen using `COMPRESS_OFFLINE = True` (recommended for production), any Django template context variables used inside `{% compress %}` blocks will *not* be available during the `manage.py compress` command execution unless explicitly defined in `COMPRESS_OFFLINE_CONTEXT`. This can lead to `OfflineGenerationError` or incorrect output if variables are missing.fixEnsure all template context variables needed within `{% compress %}` blocks during offline compression are added to the `COMPRESS_OFFLINE_CONTEXT` dictionary in your settings. For example: `COMPRESS_OFFLINE_CONTEXT = {'STATIC_URL': '/static/', 'APP_VERSION': '1.0'}`. affects: All versions with `COMPRESS_OFFLINE = True`
gotchaNesting `{% compress %}` blocks is not supported and will result in errors.fixAvoid placing one `{% compress %}` block inside another. Refactor your templates to ensure `compress` blocks are self-contained. affects: All versions
gotchaWhen using offline compression (`COMPRESS_OFFLINE = True`), the `manage.py collectstatic` command should be run *before* `manage.py compress`. Running them in the reverse order can cause `compress` to not find the static files it needs to process, resulting in uncompressed assets or errors.fixEnsure your deployment script or process runs `python manage.py collectstatic --noinput` followed by `python manage.py compress`.
affects: All versions with `COMPRESS_OFFLINE = True`
gotchaFor optimal production performance, it is strongly recommended to configure a robust Django cache backend (e.g., Memcached or Redis) and point `COMPRESS_CACHE_BACKEND` to it. The default filesystem cache might lead to performance bottlenecks, especially with frequent checks of compressed files.fixConfigure `CACHES` in `settings.py` for a production-grade cache (e.g., `django-redis`) and set `COMPRESS_CACHE_BACKEND = 'your_cache_alias'`.
affects: All versions
Upgrade
Version history
4.6.0latest on PyPI · released Nov 10, 2025
Audit
Dependencies
django-appconfrequiredUsed internally for handling Django settings configuration, automatically installed.
rcssminrequiredDefault CSS minifier.
rjsminrequiredDefault JavaScript minifier.
beautifulsoup4optionalOptional parser: compressor.parser.BeautifulSoupParser.
lxmloptionalOptional parser: compressor.parser.LxmlParser (requires libxml2).
html5liboptionalOptional parser: compressor.parser.Html5LibParser.
calmjsoptionalOptional JavaScript filter: compressor.filters.jsmin.CalmjsFilter.
csscompressoroptionalOptional CSS filter: compressor.filters.cssmin.CSSCompressorFilter.
brotlioptionalOptional for compressor.storage.BrotliCompressorFileStorage.
django-sekizaioptionalOptional for including template code into main template.
jinja2optionalOptional for Jinja2 templating support.