Django help_text Field Attribute: Syntax, Examples, and Best

django help text is the Django Field and Form Field attribute that displays contextual guidance text adjacent to form inputs, automatically rendered as an aria-describedby HTML attribute for accessibility.

field_name = models.Field(help_text = "text")

This attribute is optional and carries no validation logic. Use it to provide format hints, character limits, or privacy assurances directly below the input field.

Basic Usage

Defining on model fields

from django.db import models

class GeeksModel(models.Model):
    geeks_field = models.DateField(
        help_text="Please use the following format: <em>YYYY-MM-DD</em>."
    )

Defining on form fields

from django import forms

class ContactForm(forms.Form):
    age = forms.IntegerField(help_text="Enter your age in years.")
    nationality = forms.CharField(help_text="Country of citizenship.")
    captcha_answer = forms.IntegerField(
        label="2 + 2",
        label_suffix=" =",
        help_text="Prove you are human."
    )

Advanced Implementation & Parameters

Interaction with auto_id

When auto_id=False is passed to a form, the help text is still rendered but the aria-describedby attribute is omitted because no ID is generated. Custom templates must manually associate the help text:

f = ContactForm(auto_id=False)
print(f)  # help text present but no aria-describedby

Override help text in ModelForm

Set the help_text argument in the form field definition to override the model’s default:

class GeeksForm(forms.ModelForm):
    geeks_field = forms.DateField(
        help_text="Override: use DD/MM/YYYY"
    )
    class Meta:
        model = GeeksModel
        fields = '__all__'

Dynamic help text based on instance data

In the form’s __init__ method, set self.fields['field_name'].help_text based on the instance or request data:

class DynamicHelpForm(forms.Form):
    code = forms.CharField()

    def __init__(self, *args, **kwargs):
        user = kwargs.pop('user')
        super().__init__(*args, **kwargs)
        if user.is_superuser:
            self.fields['code'].help_text = "Enter admin token"
        else:
            self.fields['code'].help_text = "Enter your user code"

Internationalization (i18n)

Wrap help_text strings in gettext_lazy() for translation:

from django.utils.translation import gettext_lazy as _

class GeeksModel(models.Model):
    geeks_field = models.DateField(
        help_text=_("Use YYYY-MM-DD format")
    )

Error Resolution & Troubleshooting

Why use help text over alternatives?

Recommendation: Use model help_text for field-level hints that apply in all contexts (admin, model forms, APIs). Use form help_text when the hint changes per form, and rely on {{ field.help_text }} in templates for full control over positioning.

Rendering in templates

<form method="post">
  {% csrf_token %}
  {% for field in form %}
    <div>
      {{ field.label_tag }}
      {{ field }}
      <div class="helptext">{{ field.help_text }}</div>
    </div>
  {% endfor %}
</form>

When using form.as_p or form.as_div, the help text is automatically inserted below the input inside a <div class="helptext">.

Production-Grade Implementation

Accessibility-first

• Always provide help_text for fields with non-obvious format requirements. The aria-describedby ensures screen readers announce the hint after the label.
• Do not rely solely on placeholder attributes – they disappear on focus and have poor contrast in many browsers.

Security considerations

• Never include sensitive information (passwords, tokens) in help_text – it is rendered in HTML and visible to all users.
• Use conditional help_text (via __init__) to show internal guidance only to authenticated admin users.

Performance

• Help text is static at field instantiation; for database-driven hints, use ModelForm.__init__ to set help_text based on model data. Avoid querysets in help_text.
• For large forms with many fields, minimize overhead by defining help_text directly in the form class rather than reading from a database each request.

from django.db import models
class Product(models.Model):
    sku = models.CharField(max_length=30, verbose_name="SKU", help_text="Unique stock keeping unit code.")

python manage.py migrate --help

{{ field.help_text|safe }}

from rest_framework import serializers
class ProductSerializer(serializers.ModelSerializer):
    class Meta:
        model = Product
        fields = ['sku']  # help_text pulled from model

python manage.py shell -c "from django.apps import apps; [print(f'{m.__name__}: {f.name}: {f.help_text}') for m in apps.get_models() for f in m._meta.fields if f.help_text]"