{"id":9665,"library":"django-bleach","title":"django-bleach","description":"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.","status":"active","version":"3.1.0","language":"python","source_language":"en","source_url":"https://github.com/marksweb/django-bleach","tags":["django","bleach","html-sanitizer","security","xss"],"install":[{"cmd":"pip install django-bleach","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Framework integration for Django applications.","package":"Django","optional":false},{"reason":"Core HTML sanitization library.","package":"bleach","optional":false}],"imports":[{"wrong":"from django_bleach import BleachHTMLField","symbol":"VERSION","correct":"from django_bleach import VERSION"}],"quickstart":{"code":"import os\nfrom django.db import models\nfrom django_bleach.models import BleachHTMLField\n\n# Configure settings (e.g., in settings.py or test setup)\n# You can also pass these directly to the field constructor\n# os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'your_project.settings')\n# os.environ['BLEACH_ALLOWED_TAGS'] = \"['p', 'a', 'strong', 'em']\"\n# os.environ['BLEACH_ALLOWED_ATTRIBUTES'] = \"{'a': ['href', 'title']}\"\n\nclass Article(models.Model):\n    title = models.CharField(max_length=200)\n    # Use BleachHTMLField for content that might contain HTML\n    content = BleachHTMLField(\n        blank=True,\n        null=True,\n        # Field-specific allowed tags and attributes override global settings\n        tags=['p', 'a', 'h1', 'h2', 'strong', 'em', 'img'],\n        attributes={'a': ['href', 'title'], 'img': ['alt', 'src']},\n        strip_tags=False, # Do not strip tags not explicitly allowed (default is False)\n        strip_comments=True # Strip HTML comments (default is True)\n    )\n\n    def __str__(self):\n        return self.title\n\n# Example usage (after creating and migrating the model):\n# article = Article.objects.create(title='My Article', content='<h1>Hello</h1><p>This is <strong>safe</strong> content.</p><script>alert(\"XSS!\")</script>')\n# print(article.content) # Script tag should be removed.","lang":"python","description":"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."},"warnings":[{"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.","message":"`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.","severity":"breaking","affected_versions":"3.0.0+"},{"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.","message":"`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.","severity":"breaking","affected_versions":"2.0.0+"},{"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.","message":"Improper 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'3.1.0':46 'bleach':3,6,17,56,71 'bump':65 'cadenc':50 'chang':69 'clean':34 'compat':68 'current':43 'depend':64 'django':2,5,9,22,54,70 'django-bleach':1,4 'easi':13 'field':29 'filter':32 'follow':53 'framework':67 'general':52 'html':18,38,73 'html-sanit':72 'integr':14 'librari':20 'major':60 'model':23,28 'new':59 'offer':27 'packag':10 'prevent':39 'provid':12 'releas':49,58 'sanit':19,74 'secur':75 'signific':63 'suppli':37 'templat':25,31 'updat':57 'user':36 'user-suppli':35 'version':44,61 'vulner':41 'xss':40,76","created_at":"2026-04-17T01:20:05.074555+00:00","updated_at":"2026-04-17T01:20:05.074555+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.1.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/marksweb/django-bleach","docs":"https://django-bleach.readthedocs.io/","changelog":"https://github.com/marksweb/django-bleach/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/django-bleach/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","auth-security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-08-02","install_tag":null}}