Install & Compatibility
Where this runs
tested against v3.0.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.920 runs
installs and imports cleanly · install 0.0s · import 0.235s · 21MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.220s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Environment
✓ from webassets import Environment
The core class for managing asset configuration and bundles.
Bundle
✓ from webassets import Bundle
Used to define collections of files, filters, and output settings.
This quickstart demonstrates how to set up `webassets` in a standalone Python application. It initializes an `Environment`, defines `Bundle`s for CSS and JavaScript, registers them, and then prints the generated URLs in both production (merged/filtered) and debug (individual files) modes. This example includes a basic cleanup of temporary files.
import os
import shutil
from webassets import Environment, Bundle
# Define base directories and create dummy files for demonstration
base_dir = "webassets_quickstart_temp"
static_dir = os.path.join(base_dir, "static")
css_dir = os.path.join(static_dir, "css")
js_dir = os.path.join(static_dir, "js")
output_dir = os.path.join(static_dir, "gen")
os.makedirs(css_dir, exist_ok=True)
os.makedirs(js_dir, exist_ok=True)
os.makedirs(output_dir, exist_ok=True)
with open(os.path.join(css_dir, "style.css"), "w") as f:
f.write("body { font-family: sans-serif; }\n")
with open(os.path.join(js_dir, "main.js"), "w") as f:
f.write("console.log('Hello from main.js');\n")
with open(os.path.join(js_dir, "utils.js"), "w") as f:
f.write("function greet() { return 'Greetings!'; }\n")
# Initialize the Environment
# `directory` is the base path for source files and output
# `url` is the base URL from which assets are served in the browser
env = Environment(directory=static_dir, url='/static')
# Define a CSS bundle (no filters for simplicity in this quickstart)
css_bundle = Bundle(
'css/style.css',
output='gen/packed.css'
)
# Define a JavaScript bundle with an included filter (rjsmin)
js_bundle = Bundle(
'js/main.js',
'js/utils.js',
filters='rjsmin', # rjsmin is included with webassets
output='gen/packed.js'
)
# Register bundles with the environment
env.register('all_css', css_bundle)
env.register('all_js', js_bundle)
# Access the URLs in production mode (default behaviour: merges and applies filters)
print("CSS URLs (production mode):", env['all_css'].urls())
print("JS URLs (production mode):", env['all_js'].urls())
# Switch to debug mode to see individual source files (for development)
env.debug = True
print("\nCSS URLs (debug mode):", env['all_css'].urls())
print("JS URLs (debug mode):", env['all_js'].urls())
# Clean up dummy files and directories
shutil.rmtree(base_dir)
webassets --version
Errors
Common errors & fixes
FilterError: sass: subprocess had error: stderr=(sass):1: File to import not found or unreadable: <file_name>
External filters like Sass often use standard input when applied to merged bundles, which can prevent them from resolving relative `@import` paths correctly.
fixEnsure all imported files are directly accessible via `load_path` settings in your `Environment` or adjust your build process to pre-compile Sass files that use relative imports before `webassets` processes them.
command not found: <filter_executable>
An external tool required by a filter (e.g., `uglifyjs`, `cleancss`, `tsc`) is not installed on the system or is not in the system's PATH.
fixInstall the missing external tool (e.g., `npm install -g uglify-js` for UglifyJS) and verify its executable is available in your system's PATH. Alternatively, specify the full path to the executable in your `webassets` configuration (e.g., `env.config['UGLIFYJS_BIN'] = '/usr/local/bin/uglifyjs'`).
404 Not Found for web assets like JS or CSS files
Incorrect `directory` or `url` configuration in the `Environment` instance, or issues with symlink resolution on the web server.
fixVerify that `Environment.directory` points to the correct base directory where your static files reside, and `Environment.url` matches the URL prefix under which these assets are served by your web server. Check server configurations for symlink handling if applicable.
Upgrade
Version history
3.0.0latest on PyPI · released Aug 17, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.10 or later.