{"id":467,"library":"bleach","title":"Bleach","description":"Bleach is an allowed-list-based HTML sanitizing library for Python (current version 6.3.0) that escapes or strips markup and attributes based on a configurable safelist. It also provides functionality to safely linkify text, including setting `rel` attributes. Designed for sanitizing text from untrusted sources, Bleach is built upon html5lib, making it robust against malformed HTML fragments. Note that the project was deprecated in January 2023, citing upstream dependency `html5lib`'s lack of active maintenance, and is now in a minimum-maintenance mode, with new projects discouraged.","status":"deprecated","version":"6.3.0","language":"python","source_language":"en","source_url":"https://github.com/mozilla/bleach","tags":["html","sanitization","security","xss","deprecated"],"install":[{"cmd":"pip install bleach","lang":"bash","label":"Install stable version"},{"cmd":"pip install 'bleach[css]'","lang":"bash","label":"Install with CSS sanitization support"}],"dependencies":[{"reason":"Vendored since Bleach v6.0.0; no longer a direct dependency, but foundational to its parsing.","package":"html5lib","optional":true},{"reason":"Required for character encoding detection.","package":"webencodings","optional":false},{"reason":"Optional dependency for CSS sanitization in style attributes/tags.","package":"tinycss2","optional":true}],"imports":[{"symbol":"bleach","correct":"import bleach"},{"symbol":"clean","correct":"bleach.clean(...)"},{"symbol":"linkify","correct":"bleach.linkify(...)"},{"note":"Cleaner class is in bleach.sanitizer module.","wrong":"from bleach import Cleaner","symbol":"Cleaner","correct":"from bleach.sanitizer import Cleaner"}],"quickstart":{"code":"import bleach\n\n# Sanitize HTML\nhtml_input = 'An <script>alert(\"evil\")</script> example with <b>bold</b> text.'\ncleaned_html = bleach.clean(\n    html_input,\n    tags={'b', 'i', 'strong', 'em', 'a', 'p', 'br'},\n    attributes={'a': ['href', 'title']}\n)\nprint(f\"Cleaned HTML: {cleaned_html}\")\n\n# Linkify text\ntext_with_urls = 'Check out example.com or mailto:user@example.com'\nlinkified_text = bleach.linkify(text_with_urls)\nprint(f\"Linkified text: {linkified_text}\")\n\n# Using a Cleaner instance for performance/configurability\nfrom bleach.sanitizer import Cleaner\nmy_cleaner = Cleaner(\n    tags={'p', 'span'},\n    attributes={'span': ['style']},\n    css_sanitizer=None # Requires 'bleach[css]' for robust CSS sanitization\n)\ncomplex_html = '<p style=\"color: red;\">Safe paragraph</p><img src=\"x.jpg\">'\ncleaned_complex = my_cleaner.clean(complex_html)\nprint(f\"Cleaned with Cleaner: {cleaned_complex}\")","lang":"python","description":"This example demonstrates basic HTML sanitization using `bleach.clean()` and URL linkification with `bleach.linkify()`. It also shows how to use a `Cleaner` instance for more advanced or repeated sanitization tasks with custom allowed tags and attributes."},"warnings":[{"fix":"Consider alternative HTML sanitization libraries, or fork/maintain `bleach` and `html5lib` at your own risk for existing projects. Do not use for new development.","message":"The Bleach project was officially deprecated on January 23, 2023, due to its reliance on the unmaintained `html5lib` library. It is now in a minimum-maintenance mode, and new projects are explicitly discouraged from using it.","severity":"deprecated","affected_versions":">=6.0.0"},{"fix":"Update argument values from lists to Python `set` objects (e.g., `['b', 'i']` becomes `{'b', 'i'}`).","message":"For `bleach.clean()`, `bleach.sanitizer.Cleaner`, `bleach.html5lib_shim.BleachHTMLParser`, `tags` and `protocols` arguments changed from lists to sets. Similarly, for `bleach.linkify()` and `bleach.linkifier.Linker`, `skip_tags` and `recognized_tags` arguments changed from lists to sets.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Install the `css` extra (`pip install 'bleach[css]'`) and review the updated documentation for CSS sanitization in `style` attributes.","message":"CSS sanitization behavior within `style` attributes was completely rewritten. If you were sanitizing CSS, you will need to update your code. This functionality now requires installing `bleach` with the `[css]` extra: `pip install 'bleach[css]'`.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Update custom attribute callable functions to accept the `tag` argument as the first parameter.","message":"Attribute callables (functions passed to `attributes` argument) for `clean()` and `linkify()` changed their signature. They now expect three arguments: `tag`, `attribute_name`, and `attribute_value`, rather than just `attribute_name` and `attribute_value`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always pass `bleach.clean()` output through an additional escaping mechanism (like `django.utils.html.escape` or Jinja2's `escape`) if it's going into an HTML attribute or any non-HTML context.","message":"The output of `bleach.clean()` is intended for use specifically in an HTML *content* context (e.g., `<div>{{ cleaned_text }}</div>`). It is NOT safe for use in HTML attributes, CSS, JavaScript, JSON, or other contexts without further appropriate escaping (e.g., using a template engine's `escape` function).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your project runs on Python 3.10 or newer.","message":"Bleach dropped support for older Python versions: 3.6 (v6.0.0), 3.7 (v6.1.0), 3.8 (v6.2.0), and 3.9 (v6.3.0). The current version (6.3.0) requires Python >=3.10.","severity":"breaking","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-05-12T14:03:08.710Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the 'bleach' module using pip: 'pip install bleach'.","cause":"The 'bleach' module is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'bleach'"},{"fix":"Install the 'bleach_whitelist' module using pip: 'pip install bleach_whitelist'.","cause":"The 'bleach_whitelist' module is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'bleach_whitelist'"},{"fix":"Reinstall the 'bleach_allowlist' module using pip: 'pip uninstall bleach_allowlist' followed by 'pip install bleach_allowlist'.","cause":"The 'bleach_allowlist' module is either not installed correctly or is outdated.","error":"AttributeError: module 'bleach_allowlist.bleach_allowlist' has no attribute 'all_styles'"},{"fix":"Ensure you are using a compatible version of bleach (e.g., current versions provide `bleach.clean` directly). Verify the import statement is `import bleach` and call `bleach.clean(text)`.","cause":"This error often occurs when an incompatible version of bleach is installed, or when there's an incorrect import or usage pattern, as 'bleach.clean' is the standard function for sanitization.","error":"AttributeError: module 'bleach' has no attribute 'clean'"},{"fix":"Ensure that the input text passed to `bleach.clean()` or `bleach.linkify()` is always a string and not `None`. You might need to add a check for `None` or provide a default empty string.","cause":"The `bleach.clean()` or `bleach.linkify()` function was called with `None` as the input text argument, but it expects a string (text type).","error":"TypeError: argument cannot be of 'NoneType' type, must be of text type"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"css","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":7.3,"disk_size":"19.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.25,"mem_mb":7.3,"disk_size":"19.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"css","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":7.3,"disk_size":"20M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":7.3,"disk_size":"20M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"css","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.41,"mem_mb":7.5,"disk_size":"21.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.42,"mem_mb":7.5,"disk_size":"21.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"css","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.44,"mem_mb":7.5,"disk_size":"22M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.32,"mem_mb":7.5,"disk_size":"22M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"css","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.33,"mem_mb":7.4,"disk_size":"13.5M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.31,"mem_mb":7.4,"disk_size":"13.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"css","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.3,"mem_mb":7.4,"disk_size":"14M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.33,"mem_mb":7.4,"disk_size":"14M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"css","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.3,"mem_mb":7.2,"disk_size":"13.1M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.3,"mem_mb":7.2,"disk_size":"12.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"css","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":7,"disk_size":"14M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.29,"mem_mb":7,"disk_size":"13M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"css","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":7.3,"disk_size":"19.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":7.3,"disk_size":"18.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"css","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":7.3,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":7.3,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}