django-bleach is a Django package that provides easy integration of the bleach HTML sanitization library with Django models and templates. It offers model fields and template filters to clean user-supplied HTML, preventing XSS vulnerabilities. The current version is 3.1.0, with a release cadence that generally follows Django and `bleach` updates, releasing new major versions for significant dependency bumps or framework compatibility changes.
pip install django-bleachVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to define a `BleachHTMLField` in a Django model. This field will automatically sanitize any HTML input based on the `tags` and `attributes` provided, or global settings configured in `settings.py`. It's crucial to explicitly define what HTML elements and attributes are permitted to prevent Cross-Site Scripting (XSS) vulnerabilities. You can define global settings like `BLEACH_ALLOWED_TAGS`, `BLEACH_ALLOWED_ATTRIBUTES` in your `settings.py` file.
Review `bleach` 5.x release notes (on PyPI or GitHub) for any changes relevant to your existing `django-bleach` configuration. Adjust `BLEACH_ALLOWED_TAGS`, `BLEACH_ALLOWED_ATTRIBUTES`, or custom logic in `settings.py` or field definitions as needed.
Before upgrading to `django-bleach` 2.x or later, ensure your project's Python environment is 3.8 or newer, and your Django version is 3.2 or newer. Upgrade your project's dependencies accordingly.
Always explicitly define `BLEACH_ALLOWED_TAGS` and `BLEACH_ALLOWED_ATTRIBUTES` in your `settings.py` for global defaults. For fields requiring different rules, override these settings directly in the `BleachHTMLField` or `BleachField` constructor. Test your sanitization thoroughly to ensure both functionality and security.