{"id":7859,"library":"webassets","title":"Webassets","description":"Webassets is a general, dependency-independent library for managing the assets of your web application, compatible with Python 3.10 and later. It efficiently merges and compresses CSS and JavaScript files, supports various filters, and integrates with compilers like CoffeeScript or Sass. The library currently stands at version 3.0.0 and has an active development cadence, with recent major updates.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/miracle2k/webassets/","tags":["web","assets","frontend","bundling","minification","css","javascript"],"install":[{"cmd":"pip install webassets","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.10 or later.","package":"python","optional":false}],"imports":[{"note":"The core class for managing asset configuration and bundles.","symbol":"Environment","correct":"from webassets import Environment"},{"note":"Used to define collections of files, filters, and output settings.","symbol":"Bundle","correct":"from webassets import Bundle"}],"quickstart":{"code":"import os\nimport shutil\nfrom webassets import Environment, Bundle\n\n# Define base directories and create dummy files for demonstration\nbase_dir = \"webassets_quickstart_temp\"\nstatic_dir = os.path.join(base_dir, \"static\")\ncss_dir = os.path.join(static_dir, \"css\")\njs_dir = os.path.join(static_dir, \"js\")\noutput_dir = os.path.join(static_dir, \"gen\")\n\nos.makedirs(css_dir, exist_ok=True)\nos.makedirs(js_dir, exist_ok=True)\nos.makedirs(output_dir, exist_ok=True)\n\nwith open(os.path.join(css_dir, \"style.css\"), \"w\") as f:\n    f.write(\"body { font-family: sans-serif; }\\n\")\nwith open(os.path.join(js_dir, \"main.js\"), \"w\") as f:\n    f.write(\"console.log('Hello from main.js');\\n\")\nwith open(os.path.join(js_dir, \"utils.js\"), \"w\") as f:\n    f.write(\"function greet() { return 'Greetings!'; }\\n\")\n\n# Initialize the Environment\n# `directory` is the base path for source files and output\n# `url` is the base URL from which assets are served in the browser\nenv = Environment(directory=static_dir, url='/static')\n\n# Define a CSS bundle (no filters for simplicity in this quickstart)\ncss_bundle = Bundle(\n    'css/style.css',\n    output='gen/packed.css'\n)\n\n# Define a JavaScript bundle with an included filter (rjsmin)\njs_bundle = Bundle(\n    'js/main.js',\n    'js/utils.js',\n    filters='rjsmin', # rjsmin is included with webassets\n    output='gen/packed.js'\n)\n\n# Register bundles with the environment\nenv.register('all_css', css_bundle)\nenv.register('all_js', js_bundle)\n\n# Access the URLs in production mode (default behaviour: merges and applies filters)\nprint(\"CSS URLs (production mode):\", env['all_css'].urls())\nprint(\"JS URLs (production mode):\", env['all_js'].urls())\n\n# Switch to debug mode to see individual source files (for development)\nenv.debug = True\nprint(\"\\nCSS URLs (debug mode):\", env['all_css'].urls())\nprint(\"JS URLs (debug mode):\", env['all_js'].urls())\n\n# Clean up dummy files and directories\nshutil.rmtree(base_dir)","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your project runs on Python 3.10 or a newer version.","message":"Version 3.0.0 drops support for all Python versions earlier than 3.10.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace 'yui' with an alternative JavaScript or CSS compressor (e.g., 'rjsmin', 'uglifyjs', 'cleancss').","message":"The 'yui' compressor has been removed in version 3.0.0 due to being obsolete.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Install the necessary external tools (e.g., `npm install -g uglify-js` for UglifyJS) and ensure they are in your system's PATH or configure their path in `webassets` settings (e.g., `UGLIFYJS_BIN`).","message":"Many `webassets` filters (e.g., for Sass, TypeScript, Closure Compiler, UglifyJS, Clean-css) require external command-line tools to be installed and accessible in your system's PATH, or explicitly configured via `Environment` settings.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Define `output='gen/packed.%(version)s.js'` in your `Bundle` and configure `Environment.manifest` to persist version information, especially in multi-server or pre-build scenarios.","message":"For robust cache busting and consistent asset URLs across deployments, use the `%(version)s` placeholder in the `output` filename of your `Bundle` rather than relying solely on the `url_expire` querystring.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure 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.","cause":"External filters like Sass often use standard input when applied to merged bundles, which can prevent them from resolving relative `@import` paths correctly.","error":"FilterError: sass: subprocess had error: stderr=(sass):1: File to import not found or unreadable: <file_name>"},{"fix":"Install 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'`).","cause":"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.","error":"command not found: <filter_executable>"},{"fix":"Verify 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.","cause":"Incorrect `directory` or `url` configuration in the `Environment` instance, or issues with symlink resolution on the web server.","error":"404 Not Found for web assets like JS or CSS files"}]}