Registry / web-framework / django-bleach

django-bleach

JSON →
library3.1.0pypypi✓ verified 82d ago

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-bleach
INSTALL
IMPORT
SIG · DJANGO-BLEACH
D
django-bleach
web-frameworkpythonv3.1.0
Install
3.8s avg
Import
Disk
67MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 68.2MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 3.8s · import 0.000s · 69MB
67MB installed
● package 67MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

VERSION
from django_bleach import VERSION
from django_bleach import BleachHTMLField

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.

import os from django.db import models from django_bleach.models import BleachHTMLField # Configure settings (e.g., in settings.py or test setup) # You can also pass these directly to the field constructor # os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'your_project.settings') # os.environ['BLEACH_ALLOWED_TAGS'] = "['p', 'a', 'strong', 'em']" # os.environ['BLEACH_ALLOWED_ATTRIBUTES'] = "{'a': ['href', 'title']}" class Article(models.Model): title = models.CharField(max_length=200) # Use BleachHTMLField for content that might contain HTML content = BleachHTMLField( blank=True, null=True, # Field-specific allowed tags and attributes override global settings tags=['p', 'a', 'h1', 'h2', 'strong', 'em', 'img'], attributes={'a': ['href', 'title'], 'img': ['alt', 'src']}, strip_tags=False, # Do not strip tags not explicitly allowed (default is False) strip_comments=True # Strip HTML comments (default is True) ) def __str__(self): return self.title # Example usage (after creating and migrating the model): # article = Article.objects.create(title='My Article', content='<h1>Hello</h1><p>This is <strong>safe</strong> content.</p><script>alert("XSS!")</script>') # print(article.content) # Script tag should be removed.
Debug
Known issues
breaking`django-bleach` version 3.0.0 updated its core `bleach` dependency to require `bleach>=5.0.0`. If you are upgrading from an older `django-bleach` version, ensure your existing `bleach` configurations (e.g., `BLEACH_ALLOWED_TAGS`, `BLEACH_ALLOWED_ATTRIBUTES`, or custom callbacks) are compatible with `bleach` 5.x, as `bleach` itself may have breaking changes or behavioral differences.
fix
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.
affects: 3.0.0+
breaking`django-bleach` version 2.0.0 dropped support for older Python and Django versions. Specifically, it now requires Python `>=3.8` and Django `>=3.2`. Attempting to install or run `django-bleach` 2.x or later on incompatible environments will result in errors.
fix
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.
affects: 2.0.0+
gotchaImproper configuration of allowed HTML tags and attributes can lead to either over-stripping of desired HTML content or insufficient sanitization, potentially introducing security vulnerabilities (e.g., XSS). The default global settings might not be appropriate for all use cases, and field-specific overrides are critical.
fix
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.
affects: All versions
Upgrade
Version history
3.1.0latest on PyPI · released Aug 5, 2023
Audit
Dependencies
DjangorequiredFramework integration for Django applications.
bleachrequiredCore HTML sanitization library.
Agent activity
30 hits · last 30 days
node
28
OpenAI (training)
1
Resources
django-bleach — pip install django-bleach · libregistry