Django Pipeline

Common errors

• ModuleNotFoundError: No module named 'pipeline'

  cause The 'pipeline' app is not included in your Django project's `INSTALLED_APPS` setting.
  fix Add `'pipeline'` to your `INSTALLED_APPS` list in `settings.py`: `INSTALLED_APPS = [... 'pipeline',]`

• No static file generated by django-pipeline for group 'my_group' OR 'Hashed filenames not being updated'

  cause This typically occurs because `DEBUG = True` (disabling compression), `python manage.py collectstatic` was not run, or `STATICFILES_STORAGE` is incorrectly configured.
  fix Ensure `DEBUG = False` for production behavior. Run `python manage.py collectstatic` after any changes to `PIPELINE` settings or static files. Verify that `STATICFILES_STORAGE` is set to `'pipeline.storage.PipelineManifestStorage'` (or correctly configured within `STORAGES` for Django 4.2+).

• django.core.exceptions.ImproperlyConfigured: 'yuglify' could not be found. Make sure it's installed and available in your PATH.

  cause An external compressor or compiler binary (like `yuglify`, `uglifyjs`, `lessc`, `sass`) is specified in your `PIPELINE` settings but is not installed on your system or its path is not correctly configured.
  fix Install the missing binary (e.g., `npm install -g yuglify` or `sudo apt-get install yuglify`). If the binary is not in your system's PATH, explicitly set its absolute path in your `PIPELINE` settings, e.g., `PIPELINE['YUGLIFY_BINARY'] = '/usr/local/bin/yuglify'`.

Warnings

• gotcha Pipeline's asset compression and bundling features are only active when Django's `DEBUG` setting is `False`. When `DEBUG` is `True`, Pipeline serves individual source files for easier debugging, which can be confusing if you expect bundled output in development.
  Fix: To see compressed output, ensure `DEBUG = False` in your `settings.py` and run `python manage.py collectstatic`. For debugging, keep `DEBUG = True` to load individual files.
• breaking `django-pipeline` often requires external binary compilers/compressors (e.g., Yuglify, UglifyJS, Less, Sass). These tools must be installed manually (e.g., via Node.js/NPM) and their paths correctly configured in your `PIPELINE` settings. Failure to do so will result in 'command not found' errors during `collectstatic` or when serving assets.
  Fix: Install required compilers/compressors via your system's package manager or Node.js's npm (e.g., `npm install -g yuglify`). Then, configure the absolute path to the binary in your `PIPELINE` settings, for example: `PIPELINE.update({'YUGLIFY_BINARY': '/usr/local/bin/yuglify'})`.
• deprecated For Django versions 4.2 and higher, the `STATICFILES_STORAGE` setting is superseded by the `STORAGES` setting. While `STATICFILES_STORAGE` might still work for static files in some configurations, it is recommended to update to the `STORAGES` dictionary format for full compatibility and future-proofing.
  Fix: Update your `settings.py` to use `STORAGES` instead of `STATICFILES_STORAGE`. Example: `STORAGES = {'staticfiles': {'BACKEND': 'pipeline.storage.PipelineManifestStorage'}}`. Remove the old `STATICFILES_STORAGE` setting.

Install

• pip install django-pipeline Install stable version

Imports

• pipeline
  wrong:

  apps.add('pipeline')

  correct:

  INSTALLED_APPS = ['pipeline']

  Ensure 'pipeline' is listed in your project's INSTALLED_APPS setting in settings.py.
• PipelineManifestStorage

  STATICFILES_STORAGE = 'pipeline.storage.PipelineManifestStorage'

  Required to enable Pipeline's static file handling and manifest generation.
• PipelineFinder

  STATICFILES_FINDERS = ('django.contrib.staticfiles.finders.FileSystemFinder', 'django.contrib.staticfiles.finders.AppDirectoriesFinder', 'pipeline.finders.PipelineFinder',)

  Adds Pipeline's finder to locate static assets.
• pipeline template tags
  wrong:

  {% load compressed %}

  correct:

  {% load pipeline %}

  The template library changed from 'compressed' to 'pipeline' in newer versions.

Quickstart

This quickstart demonstrates basic configuration in `settings.py` for CSS and JavaScript asset groups. It includes setting `INSTALLED_APPS`, `STATICFILES_STORAGE`, `STATICFILES_FINDERS`, and the `PIPELINE` dictionary. In your templates, load the `pipeline` tags and use `{% stylesheet 'group_name' %}` and `{% javascript 'group_name' %}`. Remember to run `python manage.py collectstatic` after configuration for production.

import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

# settings.py snippets
INSTALLED_APPS = [
    # ... other apps
    'django.contrib.staticfiles',
    'pipeline',
]

STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / 'staticfiles'
STATICFILES_DIRS = [
    BASE_DIR / 'static',
]

STATICFILES_STORAGE = 'pipeline.storage.PipelineManifestStorage'
STATICFILES_FINDERS = (
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'pipeline.finders.PipelineFinder',
)

PIPELINE = {
    'STYLESHEETS': {
        'main_css': {
            'source_filenames': (
                'css/normalize.css',
                'css/base.css',
            ),
            'output_filename': 'css/packed_css.css',
            'extra_context': {
                'media': 'screen,projection',
            },
        },
    },
    'JAVASCRIPT': {
        'main_js': {
            'source_filenames': (
                'js/jquery.js',
                'js/app.js',
            ),
            'output_filename': 'js/packed_js.js',
        }
    }
}

# Example of manually specifying a compressor binary if needed
# PIPELINE.update({
#     'YUGLIFY_BINARY': os.path.join(BASE_DIR, 'node_modules/.bin/yuglify'),
# })

# -----------------------------------------------------
# templates/base.html (or similar)
# Add at the top of the template:
# {% load pipeline %}

# In <head> for CSS:
# {% stylesheet 'main_css' %}

# Before </body> for JS:
# {% javascript 'main_js' %}

# After configuring settings.py and templates, run:
# python manage.py collectstatic