Django Compressor

Warnings

• gotcha The `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.
  Fix: For 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`.
• gotcha When 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.
  Fix: Ensure 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'}`.
• gotcha Nesting `{% compress %}` blocks is not supported and will result in errors.
  Fix: Avoid placing one `{% compress %}` block inside another. Refactor your templates to ensure `compress` blocks are self-contained.
• gotcha When 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.
  Fix: Ensure your deployment script or process runs `python manage.py collectstatic --noinput` followed by `python manage.py compress`.
• gotcha For 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.
  Fix: Configure `CACHES` in `settings.py` for a production-grade cache (e.g., `django-redis`) and set `COMPRESS_CACHE_BACKEND = 'your_cache_alias'`.

Install

• pip install django-compressor Install stable version

Imports

• compress

  {% load compress %} ... {% compress css %} ... {% endcompress %}

  Primary usage is through a Django template tag.
• COMPRESS_ENABLED

  from django.conf import settings
  settings.COMPRESS_ENABLED

  Access configuration settings from django.conf.settings.
• CompressorFinder

  STATICFILES_FINDERS = [
      # ...
      'compressor.finders.CompressorFinder',
  ]

  Must be added to STATICFILES_FINDERS for staticfiles integration.

Quickstart

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.