Registry / web-framework / django-widget-tweaks

django-widget-tweaks

JSON →
library1.5.1pypypi✓ verified 24d ago

Django Widget Tweaks is a Python library that allows developers to customize the rendering of Django form fields directly within templates using template tags and filters, rather than modifying Python-level form definitions. This enables front-end developers to easily add CSS classes and HTML attributes. It is actively maintained by Jazzband, with version 1.5.1 supporting Django 5.0 and released annually or more frequently.

pip install django-widget-tweaks
INSTALL
IMPORT
SIG · DJANGO-WIDGET-TWEA
D
django-widget-tweaks
web-frameworkpythonv1.5.1
Install
3.4s avg
Import
Disk
66MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.5.1 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 66.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.4s · import 0.000s · 67MB
66MB installed
● package 66MB
Code
Verified usage

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

widget_tweaks
{% load widget_tweaks %}
Used as a template tag library in Django templates.

After installing, add 'widget_tweaks' to your Django project's `INSTALLED_APPS` in `settings.py`. Then, in your Django templates, load the `widget_tweaks` library using `{% load widget_tweaks %}`. You can then use the `render_field` tag or various filters (like `add_class`) to customize form fields, adding HTML attributes and CSS classes directly in the template. This example demonstrates using `render_field` to apply Bootstrap classes and attributes.

import os # settings.py snippet INSTALLED_APPS = [ # ... other apps 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', 'widget_tweaks', # Add this line ] # forms.py example from django import forms class ContactForm(forms.Form): name = forms.CharField(max_length=100, help_text='Your full name') email = forms.EmailField(help_text='A valid email address') message = forms.CharField(widget=forms.Textarea, help_text='Your message') # my_template.html example # {% load widget_tweaks %} # # <form method="post"> # {% csrf_token %} # <div class="form-group"> # <label for="{{ form.name.id_for_label }}">Name:</label> # {% render_field form.name class="form-control" placeholder="Your name" %} # {% if form.name.errors %} # <div class="invalid-feedback d-block">{% for error in form.name.errors %}{{ error }}{% endfor %}</div> # {% endif %} # </div> # <div class="form-group"> # <label for="{{ form.email.id_for_label }}">Email:</label> # {% render_field form.email type="email" class="form-control" %} # {% if form.email.errors %} # <div class="invalid-feedback d-block">{% for error in form.email.errors %}{{ error }}{% endfor %}</div> # {% endif %} # </div> # <div class="form-group"> # <label for="{{ form.message.id_for_label }}">Message:</label> # {% render_field form.message class="form-control" rows="5" %} # {% if form.message.errors %} # <div class="invalid-feedback d-block">{% for error in form.message.errors %}{{ error }}{% endfor %}</div> # {% endif %} # </div> # <button type="submit" class="btn btn-primary">Submit</button> # </form>
Debug
Known issues
breakingDjango Compatibility: Version 1.5.1 officially adds support for Django 5.0 and concurrently drops support for Django 4.1. Users on older Django versions (pre-4.2) should consult the `django-widget-tweaks` changelog to find a compatible version of the library.
fix
Upgrade Django to 4.2+ or downgrade `django-widget-tweaks` to a version compatible with your Django installation.
affects: 1.5.1 and newer
gotchaJinja2 Template Engine Incompatibility: `django-widget-tweaks` is built for Django's default template language (DTL). It does not natively integrate with Jinja2 template environments. Attempting to use `{% load widget_tweaks %}` directly in Jinja2 templates will fail.
fix
For Jinja2, you must manually import and expose the desired functions (e.g., `render_field`, `add_class`) from `widget_tweaks.templatetags.widget_tweaks` into your Jinja2 environment's globals or filters. This requires custom setup in your Django project's Jinja2 configuration.
affects: All versions
gotchaINSTALLED_APPS Requirement: The `django-widget-tweaks` template tags will not be available in your templates unless 'widget_tweaks' is explicitly added to the `INSTALLED_APPS` list in your project's `settings.py` file. This is a common oversight during initial setup.
fix
Ensure that 'widget_tweaks' is present in your `INSTALLED_APPS` list in `settings.py`.
affects: All versions
gotchaPurpose Misunderstanding: This library is strictly for *template-level* manipulation of HTML attributes and CSS classes on form fields. It is not intended to modify form field definitions or widgets in Python code (e.g., in `forms.py` or `models.py`).
fix
If you need to define widget attributes or classes at the Python level (e.g., dynamically based on backend logic), use Django's built-in `widget.attrs` or form field initialization. `django-widget-tweaks` complements, but does not replace, Python-level form customization.
affects: All versions
Upgrade
Version history
1.5.1latest on PyPI · released Jan 2, 2026
Audit
Dependencies
DjangorequiredCore functionality is based on Django forms.
PythonrequiredRequires Python 3.9 or newer.
Agent activity
5 hits · last 30 days
node
4
Resources
django-widget-tweaks — pip install django-widget-tweaks · libregistry