Install & Compatibility
Where this runs
tested against v4.1.0 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 66.7MB
glibcpy 3.10–3.920 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.
ReCaptchaField
✓ from django_recaptcha.fields import ReCaptchaField
✗ from django_recaptcha.fields import ReCaptchaField
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>
Debug
Known issues
breakingIn 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.fixUpdate all import paths from `from captcha...` to `from django_recaptcha...`. For example, `from django_recaptcha.fields import ReCaptchaField`.
affects: >=4.0.0
breakingVersion 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.fixEnsure your Django project is running on Django 3.2 or newer when upgrading to django-recaptcha 3.0.0 or later.
affects: >=3.0.0
gotchaFor 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.fixObtain your reCAPTCHA keys from the Google reCAPTCHA Admin Console and configure them in `settings.py` or via environment variables.
affects: All versions
gotchaWhen 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.fixFor 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. affects: All versions with V3 support
gotchaIn 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.fixUpgrade 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.
affects: <4.0.0
Upgrade
Version history
4.1.0latest on PyPI · released Mar 28, 2025
Audit
Dependencies
DjangorequiredCore framework dependency. Tested with Django 4.2, 5.0, 5.1, and 5.2.
PythonrequiredRuntime environment. Tested with Python 3.9, 3.10, 3.11, 3.12, 3.13.