{"id":5909,"library":"django-recaptcha","title":"Django reCAPTCHA","description":"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.","status":"active","version":"4.1.0","language":"en","source_language":"en","source_url":"https://github.com/django-recaptcha/django-recaptcha","tags":["django","recaptcha","forms","security","captcha"],"install":[{"cmd":"pip install django-recaptcha","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core framework dependency. Tested with Django 4.2, 5.0, 5.1, and 5.2.","package":"Django","optional":false},{"reason":"Runtime environment. Tested with Python 3.9, 3.10, 3.11, 3.12, 3.13.","package":"Python","optional":false}],"imports":[{"note":"As of version 4.0.0, the package namespace changed from `captcha` to `django_recaptcha`. This affects all import paths.","wrong":"from captcha.fields import ReCaptchaField","symbol":"ReCaptchaField","correct":"from django_recaptcha.fields import ReCaptchaField"},{"note":"As of version 4.0.0, the package namespace changed from `captcha` to `django_recaptcha`. This affects all import paths.","wrong":"from captcha.widgets import ReCaptchaV2Checkbox","symbol":"ReCaptchaV2Checkbox","correct":"from django_recaptcha.widgets import ReCaptchaV2Checkbox"},{"note":"As of version 4.0.0, the package namespace changed from `captcha` to `django_recaptcha`. This affects all import paths.","wrong":"from captcha.widgets import ReCaptchaV3","symbol":"ReCaptchaV3","correct":"from django_recaptcha.widgets import ReCaptchaV3"}],"quickstart":{"code":"# settings.py\nimport os\n\nINSTALLED_APPS = [\n    # ... other apps\n    'django_recaptcha',\n]\n\nRECAPTCHA_PUBLIC_KEY = os.environ.get('RECAPTCHA_PUBLIC_KEY', '')\nRECAPTCHA_PRIVATE_KEY = os.environ.get('RECAPTCHA_PRIVATE_KEY', '')\n\n# Optional: For reCAPTCHA v3, set a default score threshold\n# RECAPTCHA_SCORE_THRESHOLD = 0.5\n\n# forms.py\nfrom django import forms\nfrom django_recaptcha.fields import ReCaptchaField\nfrom django_recaptcha.widgets import ReCaptchaV2Checkbox # or ReCaptchaV3\n\nclass ContactForm(forms.Form):\n    name = forms.CharField(max_length=100)\n    email = forms.EmailField()\n    message = forms.CharField(widget=forms.Textarea)\n    recaptcha = ReCaptchaField(widget=ReCaptchaV2Checkbox) # Default to V2 Checkbox\n\n# views.py\nfrom django.shortcuts import render, redirect\nfrom .forms import ContactForm\n\ndef contact_view(request):\n    if request.method == 'POST':\n        form = ContactForm(request.POST)\n        if form.is_valid():\n            # Process the form data\n            # For ReCaptchaV3, you might check form.cleaned_data['recaptcha'].get('score')\n            return redirect('success_url') # Replace with your success URL name\n    else:\n        form = ContactForm()\n    return render(request, 'contact.html', {'form': form})\n\n# templates/contact.html\n<!-- Make sure to load the Google reCAPTCHA API script in your base template or head, e.g., -->\n<!-- <script src=\"https://www.google.com/recaptcha/api.js\" async defer></script> -->\n\n<form method=\"post\">\n    {% csrf_token %}\n    {{ form.as_p }}\n    <button type=\"submit\">Submit</button>\n</form>","lang":"python","description":"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."},"warnings":[{"fix":"Update all import paths from `from captcha...` to `from django_recaptcha...`. For example, `from django_recaptcha.fields import ReCaptchaField`.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your Django project is running on Django 3.2 or newer when upgrading to django-recaptcha 3.0.0 or later.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Obtain your reCAPTCHA keys from the Google reCAPTCHA Admin Console and configure them in `settings.py` or via environment variables.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions with V3 support"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.0.0"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}