Captcha

For documentation, see https://github.com/praekelt/django-recaptcha

Warning

django-recaptcha does not support Enterprise reCAPTCHA (yet) For more information, see recaptcha enterprise issue 234

Sign Up

Sign up to reCAPTCHA on https://console.cloud.google.com/security/recaptcha

You will want to Create key (Classic keys should be replaced).
If you want to use the Captcha on your laptop from http://localhost:8000/, then add localhost to the list of domains.

_images/2025-07-26-recaptcha-create-key.png

You will receive a site key.
You will need to request a secret key using the options under Integrating with a third party.

_images/2025-07-28-recaptcha-third-party.png

Tip

Integrating with a third party will only be until django-recaptcha supports Enterprise reCAPTCHA. (for more information, see recaptcha enterprise issue 234)

Salt

In the salt sls file for your site, add the norecaptcha_site_key and the norecaptcha_secret_key e.g:

norecaptcha_site_key: <your site key>
norecaptcha_secret_key: <your secret key>

Note

Replace <your site key> and <your secret key> with the actual reCAPTCHA keys.

Django

Add the following to requirements/base.txt:

django-recaptcha

Add the following to settings/base.py:

THIRD_PARTY_APPS = (
    "django_recaptcha",
    # ...
)

Add the following to settings/production.py:

# https://github.com/praekelt/django-recaptcha
RECAPTCHA_PRIVATE_KEY = get_env_variable('NORECAPTCHA_SECRET_KEY')
RECAPTCHA_PUBLIC_KEY = get_env_variable('NORECAPTCHA_SITE_KEY')
# https://github.com/torchbox/django-recaptcha#recaptcha-v3-score
RECAPTCHA_REQUIRED_SCORE = 0.85

Tip

We are using reCAPTCHA version 3, but if you are testing reCAPTCHA version 2, do not set RECAPTCHA_PRIVATE_KEY or RECAPTCHA_PUBLIC_KEY. Google provides test keys which are set as the default.

To add a captcha field to your form:

from django_recaptcha.fields import ReCaptchaField
from django_recaptcha.widgets import ReCaptchaV3

class EnquiryForm(RequiredFieldForm):
    captcha = ReCaptchaField(widget=ReCaptchaV3)

Testing

We are using reCAPTCHA version 3, but if you are using reCAPTCHA version 2 then add the following to your local settings file e.g. settings/dev_patrick.py:

SILENCED_SYSTEM_CHECKS = ["django_recaptcha.recaptcha_test_key_error"]

From Django reCAPTCHA, Unit Testing:

data = {
    "name": "Patrick",
    "captcha": "123",
    "g-recaptcha-response": "PASSED",
}
response = client.post(reverse("example.enquiry.create"), data)

Tip

Make sure to add captcha to the data.

Note

No need to use os.environ["RECAPTCHA_TESTING"] = "True" in tests any more!

Note

g-recaptcha-response has replaced recaptcha_response_field.

Note

We are using reCAPTCHA version 3, but if you are testing reCAPTCHA version 2, do not set RECAPTCHA_PRIVATE_KEY or RECAPTCHA_PUBLIC_KEY. Google provides test keys which are set as the default.