Crispy Bootstrap3

Common errors

• ModuleNotFoundError: No module named 'crispy_bootstrap3'

  cause The `crispy-bootstrap3` package has not been installed or has not been added to your `INSTALLED_APPS` in `settings.py` after upgrading `django-crispy-forms` to version 2.0 or newer.
  fix Run `pip install crispy-bootstrap3` and ensure `'crispy_bootstrap3'` is listed in your `INSTALLED_APPS` in `settings.py`.

• django.template.exceptions.TemplateDoesNotExist: bootstrap3/uni_form.html (or similar path)

  cause This typically means `crispy_bootstrap3` is either not installed, not added to `INSTALLED_APPS`, or the `CRISPY_TEMPLATE_PACK` setting is incorrect or pointing to a non-existent template pack. It can also occur if `django-crispy-forms` is too old (pre-2.0) and doesn't expect template packs to be separate.
  fix Verify `crispy-bootstrap3` is installed and in `INSTALLED_APPS`. Check `CRISPY_TEMPLATE_PACK = 'bootstrap3'` in `settings.py`. Ensure `django-crispy-forms` is version 2.0 or higher.

• Forms are not styled correctly (e.g., no Bootstrap classes applied, plain HTML)

  cause The Bootstrap 3 CSS/JS files are missing from your HTML templates, or the `CRISPY_TEMPLATE_PACK` setting is not correctly configured to 'bootstrap3', or a frontend framework (e.g. CDN) is using a different version of Bootstrap.
  fix Confirm Bootstrap 3 CSS and JavaScript are loaded in your base HTML. Double-check `CRISPY_TEMPLATE_PACK = 'bootstrap3'` in `settings.py`. Ensure `{% load crispy_forms_tags %}` is present in your template.

Warnings

• breaking Template packs, including `crispy-bootstrap3`, were extracted from the core `django-crispy-forms` library starting with version 2.0. If you are upgrading `django-crispy-forms` from a version prior to 2.0 to 2.0 or newer, you must now explicitly install `crispy-bootstrap3` and add `'crispy_bootstrap3'` to your `INSTALLED_APPS` in `settings.py`.
  Fix: Install `crispy-bootstrap3` via `pip install crispy-bootstrap3` and add `'crispy_bootstrap3'` to your `INSTALLED_APPS` list in `settings.py`.
• gotcha `crispy-bootstrap3` only provides the Django template rendering logic. It does *not* include the Bootstrap 3 CSS or JavaScript files themselves. You must manually include Bootstrap 3's static files (e.g., via CDN or local installation) in your project's HTML templates for the forms to be styled correctly.
  Fix: Ensure Bootstrap 3 CSS and JS files are linked in your base Django template (`<link>` and `<script>` tags).
• gotcha Ensure the `CRISPY_TEMPLATE_PACK` setting in `settings.py` correctly matches the template pack you intend to use (e.g., 'bootstrap3'). A mismatch, especially if you have multiple `crispy-bootstrapX` packages installed or a CDN for a different Bootstrap version, can lead to `TemplateDoesNotExist` errors or incorrectly styled forms.
  Fix: Verify that `CRISPY_TEMPLATE_PACK = 'bootstrap3'` is set in `settings.py` and that your frontend includes Bootstrap 3 assets, not Bootstrap 4 or 5.
• gotcha When using inline forms with `crispy-bootstrap3`, form errors (e.g., from validation failures) might not display by default. This is because the default `inline_field.html` template may not include the necessary logic to render error messages, unlike standard field templates.
  Fix: To display errors in inline forms, you may need to create a custom template for `inline_field.html` or override the relevant `bootstrap3/layout/help_text_and_errors.html` to ensure error rendering is included. Consult `django-crispy-forms` documentation on custom template overrides.

Install

• pip install crispy-bootstrap3 Install latest version

Imports

• crispy_forms_tags

  {% load crispy_forms_tags %}

  This is a Django template tag library, not a Python import. It's used in HTML templates to enable crispy forms rendering.

Quickstart

To integrate `crispy-bootstrap3`, first install the package. Then, add `'crispy_forms'` and `'crispy_bootstrap3'` to your `INSTALLED_APPS` in your Django `settings.py` file. Crucially, set `CRISPY_ALLOWED_TEMPLATE_PACKS = 'bootstrap3'` and `CRISPY_TEMPLATE_PACK = 'bootstrap3'` to activate the Bootstrap 3 template pack. In your Django templates, load the `crispy_forms_tags` library and render your form using `{% crispy form %}` for a complete form, or `{{ field|as_crispy_field }}` for individual fields. Remember to include Bootstrap 3's own CSS and JavaScript files in your project, as `crispy-bootstrap3` only provides the form rendering templates.

import os

# settings.py
# ...
INSTALLED_APPS = [
    # ...
    'crispy_forms',
    'crispy_bootstrap3',
    # ...
]

CRISPY_ALLOWED_TEMPLATE_PACKS = 'bootstrap3'
CRISPY_TEMPLATE_PACK = 'bootstrap3'

# forms.py (example Django Form)
from django import forms
from crispy_forms.helper import FormHelper
from crispy_forms.layout import Layout, Submit

class ContactForm(forms.Form):
    name = forms.CharField(label="Your Name")
    email = forms.EmailField(label="Your Email")
    message = forms.CharField(widget=forms.Textarea, label="Your Message")

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.helper = FormHelper()
        self.helper.layout = Layout(
            'name',
            'email',
            'message',
            Submit('submit', 'Submit', css_class='btn-primary')
        )

# my_template.html (example Django template)
# Make sure Bootstrap 3 CSS and JS are linked in your base template
# {% load crispy_forms_tags %}
# <form method="post">
#     {% csrf_token %}
#     {% crispy form %}
# </form>