Django reCAPTCHA

4.1.0 · active · verified Tue Apr 14

django-recaptcha is a Django application that integrates Google reCAPTCHA functionality into Django forms. It provides form fields and widgets for reCAPTCHA v2 (Checkbox, Invisible) and reCAPTCHA v3. The current version is 4.1.0, and the project is actively maintained with regular releases to support the latest Django and Python versions.

Warnings

breaking In version 4.0.0, the internal package namespace was renamed from `captcha` to `django_recaptcha` to avoid conflicts. All import statements for `ReCaptchaField`, `ReCaptchaWidget`, and other components must be updated.
Fix: Update all import paths from `from captcha...` to `from django_recaptcha...`. For example, `from django_recaptcha.fields import ReCaptchaField`.
breaking Version 3.0.0 introduced support for Django 3.2 and 4.0, removing the upper Django dependency constraint. This means older Django versions (prior to 3.2) are no longer officially supported by this major release.
Fix: Ensure your Django project is running on Django 3.2 or newer when upgrading to django-recaptcha 3.0.0 or later.
gotcha For production environments, you must set `RECAPTCHA_PUBLIC_KEY` and `RECAPTCHA_PRIVATE_KEY` in your Django settings. If these are not provided, the library defaults to Google's test keys, which always validate successfully but display a warning and only work for reCAPTCHA v2. This can lead to unverified submissions in production.
Fix: Obtain your reCAPTCHA keys from the Google reCAPTCHA Admin Console and configure them in `settings.py` or via environment variables.
gotcha When using reCAPTCHA v3, the validation relies on a score returned by Google. By default, `django-recaptcha` will not automatically fail a form submission based on this score unless you configure `RECAPTCHA_SCORE_THRESHOLD` in your settings or explicitly check `form.cleaned_data['recaptcha'].get('score')` in your view. If not configured, all successful token responses pass, regardless of the score.
Fix: For automatic enforcement, set `RECAPTCHA_SCORE_THRESHOLD` to a value between 0.0 (highest risk) and 1.0 (lowest risk) in your `settings.py`. Alternatively, manually check `form.cleaned_data['recaptcha'].get('score')` in your form's `clean` method or view logic.
gotcha In versions prior to 4.0.0, reCAPTCHA v3 tokens were requested on page load. If a user left the form open for more than two minutes before submitting, the token would expire, causing validation to fail. This issue was addressed in version 4.0.0.
Fix: Upgrade to django-recaptcha 4.0.0 or later to benefit from the fix where reCAPTCHA v3 tokens are requested upon form submission, preventing premature expiration.

Install

pip install django-recaptcha Install with pip

Imports

ReCaptchaField
```
from django_recaptcha.fields import ReCaptchaField
```
As of version 4.0.0, the package namespace changed from `captcha` to `django_recaptcha`. This affects all import paths.
ReCaptchaV2Checkbox
```
from django_recaptcha.widgets import ReCaptchaV2Checkbox
```
As of version 4.0.0, the package namespace changed from `captcha` to `django_recaptcha`. This affects all import paths.
ReCaptchaV3
```
from django_recaptcha.widgets import ReCaptchaV3
```
As of version 4.0.0, the package namespace changed from `captcha` to `django_recaptcha`. This affects all import paths.

Quickstart

To quickly integrate django-recaptcha, first add `django_recaptcha` to your `INSTALLED_APPS` and configure your `RECAPTCHA_PUBLIC_KEY` and `RECAPTCHA_PRIVATE_KEY` in `settings.py`. Then, include `ReCaptchaField` in your Django form and render it in your template. For reCAPTCHA v3, you can use `ReCaptchaV3` widget and optionally define `RECAPTCHA_SCORE_THRESHOLD` in settings.

# settings.py
import os

INSTALLED_APPS = [
    # ... other apps
    'django_recaptcha',
]

RECAPTCHA_PUBLIC_KEY = os.environ.get('RECAPTCHA_PUBLIC_KEY', '')
RECAPTCHA_PRIVATE_KEY = os.environ.get('RECAPTCHA_PRIVATE_KEY', '')

# Optional: For reCAPTCHA v3, set a default score threshold
# RECAPTCHA_SCORE_THRESHOLD = 0.5

# forms.py
from django import forms
from django_recaptcha.fields import ReCaptchaField
from django_recaptcha.widgets import ReCaptchaV2Checkbox # or ReCaptchaV3

class ContactForm(forms.Form):
    name = forms.CharField(max_length=100)
    email = forms.EmailField()
    message = forms.CharField(widget=forms.Textarea)
    recaptcha = ReCaptchaField(widget=ReCaptchaV2Checkbox) # Default to V2 Checkbox

# views.py
from django.shortcuts import render, redirect
from .forms import ContactForm

def contact_view(request):
    if request.method == 'POST':
        form = ContactForm(request.POST)
        if form.is_valid():
            # Process the form data
            # For ReCaptchaV3, you might check form.cleaned_data['recaptcha'].get('score')
            return redirect('success_url') # Replace with your success URL name
    else:
        form = ContactForm()
    return render(request, 'contact.html', {'form': form})

# templates/contact.html
<!-- Make sure to load the Google reCAPTCHA API script in your base template or head, e.g., -->
<!-- <script src="https://www.google.com/recaptcha/api.js" async defer></script> -->

<form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <button type="submit">Submit</button>
</form>

view raw JSON →