Install & Compatibility
Where this runs
tested against v2.1.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.715s · 29.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.8s · import 0.660s · 30MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Environment
✓ from flask_assets import Environment
Used to initialize the asset management environment.
Bundle
✓ from flask_assets import Bundle
Used to define collections of source files, filters, and output targets.
This quickstart demonstrates how to set up `Flask-Assets` to manage CSS and JavaScript files. It initializes an `Environment`, defines `Bundle` objects for minifying and combining static files, registers them, and shows how to include these bundles in a Jinja2 template. Run the script, then navigate to `http://127.0.0.1:5000/` in your browser. The static files will be automatically generated in `static/gen`.
from flask import Flask, render_template
from flask_assets import Environment, Bundle
import os
app = Flask(__name__)
# Configure Flask for assets
app.config['ASSETS_DEBUG'] = True # Set to False in production
# Initialize Flask-Assets
assets = Environment(app)
# Define asset bundles
js_bundle = Bundle(
'js/main.js',
'js/utils.js',
filters='jsmin',
output='gen/packed.js'
)
css_bundle = Bundle(
'css/style.css',
'css/theme.css',
filters='cssmin',
output='gen/packed.css'
)
# Register bundles
assets.register('main_js', js_bundle)
assets.register('main_css', css_bundle)
@app.route('/')
def index():
return render_template('index.html')
if __name__ == '__main__':
# Create static/js and static/css directories for the example
os.makedirs(os.path.join(app.static_folder, 'js'), exist_ok=True)
os.makedirs(os.path.join(app.static_folder, 'css'), exist_ok=True)
# Create dummy asset files
with open(os.path.join(app.static_folder, 'js', 'main.js'), 'w') as f:
f.write('console.log("Main JS loaded");')
with open(os.path.join(app.static_folder, 'js', 'utils.js'), 'w') as f:
f.write('function utility() { return "utility"; }')
with open(os.path.join(app.static_folder, 'css', 'style.css'), 'w') as f:
f.write('body { font-family: sans-serif; }')
with open(os.path.join(app.static_folder, 'css', 'theme.css'), 'w') as f:
f.write('h1 { color: #333; }')
# Create a simple template (templates/index.html)
template_content = '''
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Flask-Assets Example</title>
{% assets "main_css" %}
<link rel="stylesheet" type="text/css" href="{{ ASSET_URL }}">
{% endassets %}
</head>
<body>
<h1>Hello from Flask-Assets!</h1>
{% assets "main_js" %}
<script type="text/javascript" src="{{ ASSET_URL }}"></script>
{% endassets %}
</body>
</html>
'''
os.makedirs('templates', exist_ok=True)
with open('templates/index.html', 'w') as f:
f.write(template_content)
app.run(debug=True)
Errors
Common errors & fixes
TemplateSyntaxError: Encountered unknown tag 'assets'
The Flask-Assets Jinja2 extension is not correctly registered or initialized with the Flask application.
fixEnsure `Environment(app)` or `assets.init_app(app)` is called after creating your Flask app. If using an application factory, call `assets.init_app(app)` within the factory function after the app is created. The `Environment` constructor automatically registers the Jinja2 extension when an app instance is passed.
webassets.exceptions.FilterError: Filter 'jsmin' not found
A specified filter (e.g., `jsmin`, `cssmin`, `less`, `sass`) is not installed in the Python environment.
fixInstall the Python package that provides the missing filter. For 'jsmin', run `pip install jsmin`. For other filters, consult the `webassets` documentation for the correct package name (e.g., `cssmin`, `lesscpy`, `pyscss`).
GET /static/gen/packed.js HTTP/1.1" 404 -
The generated asset file (e.g., `packed.js` or `packed.css`) is not found, often due to incorrect paths, `ASSETS_DEBUG` configuration, or the files not being built.
fixVerify that `output` paths in your `Bundle` definitions are correct and relative to your Flask app's static directory. In development, ensure `ASSETS_DEBUG` is `True` to see individual files or set `app.config['ASSETS_AUTO_BUILD'] = True` (or manually run `flask assets build`) to ensure bundles are generated.
How to pass variables to assets in Flask (Jinja2) / JavaScript file cannot access Flask/Jinja2 variables.
JavaScript assets are static and processed once, before template rendering. Direct inline Jinja2 variable substitution within a linked `.js` file is not possible.
fixPass data from Flask to JavaScript by rendering a `<script>` block *within* your Jinja2 template, before your linked asset. Use `window.YOUR_VAR = {{ flask_variable | tojson }};` to make Python variables accessible to your JavaScript assets. Ensure `| tojson` is used for proper JSON encoding of complex objects. Upgrade
Version history
2.1.0latest on PyPI · released Oct 22, 2023
Audit
Dependencies
FlaskrequiredCore web framework integration.
webassetsrequiredThe underlying asset management library Flask-Assets integrates with.
jsminoptionalOptional filter for JavaScript minification.
cssminoptionalOptional filter for CSS minification.
lesscpyoptionalOptional filter for LESS compilation.
pyscssoptionalOptional filter for SCSS compilation.