Install & Compatibility
Where this runs
tested against v3.2.4 · 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 · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
webpack_loader
✓ INSTALLED_APPS = ['webpack_loader', ...]
Add 'webpack_loader' to your Django project's INSTALLED_APPS in settings.py.
render_bundle
✓ {% load render_bundle from webpack_loader %}
Used in Django templates to render Webpack bundles (e.g., JS or CSS files) for a specific entry point.
webpack_static
✓ {% load webpack_static from webpack_loader %}
Similar to Django's built-in `static` tag, but for Webpack-managed static assets.
This quickstart demonstrates the essential Django `settings.py` configuration for `django-webpack-loader` and an example of its usage within a Django template. It defines `INSTALLED_APPS`, `STATICFILES_DIRS` to tell Django where static assets are located, and the `WEBPACK_LOADER` dictionary, which points to the `webpack-stats.json` file and specifies the bundle output directory. A minimal `webpack.config.js` setup is also provided as context, showing how to configure `webpack-bundle-tracker` to generate the necessary `webpack-stats.json` file. Remember that `webpack-bundle-tracker` must be separately installed and configured in your Webpack build process.
import os
# settings.py
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
INSTALLED_APPS = [
# ... other Django apps
'webpack_loader',
]
STATICFILES_DIRS = (
os.path.join(BASE_DIR, 'assets'), # Where your frontend source and webpack bundles might live
)
WEBPACK_LOADER = {
'DEFAULT': {
'BUNDLE_DIR_NAME': 'webpack_bundles/', # Webpack output directory within STATICFILES_DIRS
'STATS_FILE': os.path.join(BASE_DIR, 'webpack-stats.json'), # Path to webpack-stats.json
'POLL_INTERVAL': 0.1, # Optional: Poll interval for stats file changes in dev mode (default 0.1s)
'TIMEOUT': 10, # Optional: Timeout for webpack compilation in dev mode (default 0, never timeouts)
'CACHE': not DEBUG, # Cache results in production
'PUBLIC_PATH': '/static/webpack_bundles/', # Typically matches output.publicPath in webpack config
}
}
# myapp/templates/myapp/index.html
# {% load render_bundle from webpack_loader %}
# <!DOCTYPE html>
# <html>
# <head>
# <title>My Django App</title>
# {% render_bundle 'main' 'css' %}
# </head>
# <body>
# <div id="app"></div>
# {% render_bundle 'main' 'js' %}
# </body>
# </html>
# Corresponding minimal webpack.config.js snippet (requires webpack-bundle-tracker):
# const path = require('path');
# const BundleTracker = require('webpack-bundle-tracker');
#
# module.exports = {
# context: __dirname,
# entry: './assets/js/index.js',
# output: {
# path: path.resolve('./assets/webpack_bundles/'),
# filename: '[name]-[contenthash].js',
# publicPath: '/static/webpack_bundles/',
# },
# plugins: [
# new BundleTracker({ filename: './webpack-stats.json' }),
# ],
# };
Debug
Known issues
breakingVersions >= 1.0.0 of `django-webpack-loader` require `webpack-bundle-tracker@1.0.0` or higher due to a change in the `webpack-stats.json` file format. It is recommended to maintain at least minor version parity between both packages for full compatibility.fixEnsure your `package.json` specifies `webpack-bundle-tracker` version `1.0.0` or higher (e.g., `^2.0.0` for recent `django-webpack-loader` versions) and rebuild your Webpack assets.
affects: >=1.0.0
breakingVersion 3.0.0 introduced improved support for `publicPath: 'auto'` in Webpack configurations. If your existing setup relied on specific workarounds for `publicPath` behavior with earlier versions, you might need to review and adjust your Webpack and `WEBPACK_LOADER` configurations.fixReview your `webpack.config.js` `output.publicPath` and `WEBPACK_LOADER['DEFAULT']['PUBLIC_PATH']` settings. Test thoroughly, especially if you were using complex `publicPath` configurations before version 3.0.0.
affects: 3.0.0
gotchaThe default `TIMEOUT` for `webpack_loader` in development is `0` (never timeout). This can cause your Django development server to hang silently if the Webpack development server is not running, is slow to compile, or gets stuck in a 'compile' state, blocking all requests without explicit error messages. Version 3.2.3 added a warning log for this scenario.fixIt is highly recommended to set a sensible `TIMEOUT` value in your `WEBPACK_LOADER` settings (e.g., `10` seconds) to prevent infinite waits during development: `'TIMEOUT': 10,`.
affects: All versions, specifically noticeable before 3.2.3 which added a warning.
gotchaIncorrectly configured `STATS_FILE` or `BUNDLE_DIR_NAME` in `WEBPACK_LOADER` settings relative to your Webpack output and Django's `STATICFILES_DIRS` is a very common setup error. These paths must precisely match how Webpack is configured to output `webpack-stats.json` and its bundles.fixDouble-check that `WEBPACK_LOADER['DEFAULT']['STATS_FILE']` is the absolute path to your `webpack-stats.json` and `WEBPACK_LOADER['DEFAULT']['BUNDLE_DIR_NAME']` is the *relative path* from one of your `STATICFILES_DIRS` to where Webpack places bundles. Ensure `webpack.config.js` `output.path` aligns with `STATICFILES_DIRS` and `BUNDLE_DIR_NAME`.
affects: All versions
gotchaThe `skip_common_chunks=True` option in `render_bundle` requires the Django `request` object to be present in the template context (e.g., via `django.template.context_processors.request` middleware) to function correctly and deduplicate chunks. Without it, common chunks might be duplicated in the output, and you might receive console warnings.fixEnsure `django.template.context_processors.request` is included in your `TEMPLATES` `OPTIONS['context_processors']` in `settings.py`.
affects: All versions using `skip_common_chunks`
Upgrade
Version history
3.2.4latest on PyPI · released May 13, 2026
Audit
Dependencies
webpack-bundle-trackerrequiredEssential Node.js package for Webpack that generates the `webpack-stats.json` file consumed by django-webpack-loader. It's crucial for the integration.