Django reCAPTCHA form field/widget integration app.
[!NOTE] django-recaptcha supports Google reCAPTCHA V2 - Checkbox (Default), Google reCAPTCHA V2 - Invisible and Google reCAPTCHA V3. Please look at the widgets section for more information.
Django reCAPTCHA uses a modified version of the Python reCAPTCHA client which is included in the package as
client.py.
Tested with:
This package only supports modern, “evergreen” desktop and mobile browsers. For IE11 support, make sure to add a polyfill for Element.closest.
Install with pip install django-recaptcha.
Add 'django_recaptcha' to your INSTALLED_APPS setting.
INSTALLED_APPS = [
...,
'django_recaptcha',
...
]
RECAPTCHA_PUBLIC_KEY and
RECAPTCHA_PRIVATE_KEY. Note that omitting these settings will
default to a set of test keys refer to Local Development and
Functional Testing for
more information.For example:
RECAPTCHA_PUBLIC_KEY = 'MyRecaptchaKey123'
RECAPTCHA_PRIVATE_KEY = 'MyRecaptchaPrivateKey456'
These can also be specified per field by passing the public_key
or private_key parameters to ReCaptchaField - see field usage
below.
RECAPTCHA_PROXY setting
(dictionary of proxies), for example:RECAPTCHA_PROXY = {'http': 'http://127.0.0.1:8000', 'https': 'https://127.0.0.1:8000'}
www.google.com is not accessible the
RECAPTCHA_DOMAIN setting can be changed to www.recaptcha.net as
per the reCAPTCHA
FAQ:RECAPTCHA_DOMAIN = 'www.recaptcha.net'
This will change the Google JavaScript api domain as well as the client side field verification domain.
The quickest way to add reCAPTCHA to a form is to use the included
ReCaptchaField field class. A ReCaptchaV2Checkbox will be rendered
by default. For example:
from django import forms
from django_recaptcha.fields import ReCaptchaField
class FormWithCaptcha(forms.Form):
captcha = ReCaptchaField()
Be sure to include the captcha field in your forms. There are many ways to add fields to forms in Django. We recommend you refer to the form rendering options and rendering fields manually sections of the official Django documentation for forms.
To allow for runtime specification of keys you can optionally pass the
private_key or public_key parameters to the constructor. For
example:
captcha = ReCaptchaField(
public_key='76wtgdfsjhsydt7r5FFGFhgsdfytd656sad75fgh',
private_key='98dfg6df7g56df6gdfgdfg65JHJH656565GFGFGs',
)
If specified, these parameters will be used instead of your reCAPTCHA project settings.
There are three widgets that can be used with the ReCaptchaField
class:
ReCaptchaV2Checkbox for Google reCAPTCHA V2 - CheckboxReCaptchaV2Invisible for Google reCAPTCHA V2 - InvisibleReCaptchaV3 for Google reCAPTCHA V3To make use of widgets other than the default Google reCAPTCHA V2 -
Checkbox widget, simply replace the ReCaptchaField widget. For
example:
from django import forms
from django_recaptcha.fields import ReCaptchaField
from django_recaptcha.widgets import ReCaptchaV2Invisible
class FormWithCaptcha(forms.Form):
captcha = ReCaptchaField(widget=ReCaptchaV2Invisible)
The reCAPTCHA widget supports several data
attributes
that customize the behaviour of the widget, such as data-theme,
data-size, etc. You can forward these options to the widget by passing
an attrs parameter to the widget, containing a dictionary of options.
For example:
captcha = fields.ReCaptchaField(
widget=widgets.ReCaptchaV2Checkbox(
attrs={
'data-theme': 'dark',
'data-size': 'compact',
}
)
)
# The ReCaptchaV2Invisible widget
# ignores the "data-size" attribute in favor of 'data-size="invisible"'
The reCAPTCHA api supports several
parameters.
To customise the parameters that get sent along pass an api_params
parameter to the widget, containing a dictionary of options. For
example:
captcha = fields.ReCaptchaField(
widget=widgets.ReCaptchaV2Checkbox(
api_params={'hl': 'cl', 'onload': 'onLoadFunc'}
)
)
# The dictionary is urlencoded and appended to the reCAPTCHA api url.
By default, the widgets provided only supports a single form with a single widget on each page.
The language can be set with the 'h1' parameter, look at language codes for the language code options. Note that translations need to be added to this package for the errors to be shown correctly. Currently the package has error translations for the following language codes: es, fr, nl, pl, pt_BR, ru, zh_CN, zh_TW
However, the JavaScript used by the widgets can easily be overridden in the templates.
The templates are located in:
django_recaptcha/includes/js_v2_checkbox.html for overriding the reCAPTCHA V2 - Checkbox templatedjango_recaptcha/includes/js_v2_invisible.html for overriding the reCAPTCHA V2 - Invisible templatedjango_recaptcha/includes/js_v3.html for overriding the reCAPTCHA V3 templateFor more information about overriding templates look at Django's template override
As of version 3, reCAPTCHA also returns a score value. This can be used to determine the likelihood of the page interaction being a bot. See the Google documentation for more details.
To set a project wide score limit use the RECAPTCHA_REQUIRED_SCORE setting.
For example:
RECAPTCHA_REQUIRED_SCORE = 0.85
For per field, runtime, specification the attribute can also be passed to the widget:
captcha = fields.ReCaptchaField(
widget=ReCaptchaV3(
attrs={
'required_score':0.85,
...
}
)
)
In the event the score does not meet the requirements, the field validation will fail as expected and an error message will be logged.
Google's reCAPTCHA V3 API supports passing an action value. Actions allow you to tie reCAPTCHA validations to a specific form on your site for analytical purposes, enabling you to perform risk analysis per form. This will allow you to make informed decisions about adjusting the score threshold for certain forms because abusive behavior can vary depending on the nature of the form.
To set the action value, pass an action argument when instantiating the ReCaptcha
widget. Be careful to only use alphanumeric characters, slashes and underscores as stated in the reCAPTCHA documentation.
captcha = fields.ReCaptchaField(
widget=widgets.ReCaptchaV3(
action='signup'
)
)
Setting an action is entirely optional. If you don't specify an action, no action will be passed to the reCAPTCHA V3 API.
If RECAPTCHA_PUBLIC_KEY and RECAPTCHA_PRIVATE_KEY are not set,
django-recaptcha will use Google's test
keys instead. These
cannot be used in production since they always validate to true and a
warning will be shown on the reCAPTCHA. Google's test keys only work for
reCAPTCHA version 2.
To bypass the security check that prevents the test keys from being used
unknowingly add
SILENCED_SYSTEM_CHECKS = [..., 'django_recaptcha.recaptcha_test_key_error', ...]
to your settings, here is an example:
SILENCED_SYSTEM_CHECKS = ['django_recaptcha.recaptcha_test_key_error']
If you want to mock the call to Google's servers altogether, have a look at test_fields.py:
from unittest.mock import patch
from django.test import TestCase
from django_recaptcha.client import RecaptchaResponse
class TestFields(TestCase):
@patch("django_recaptcha.fields.client.submit")
def test_client_success_response(self, mocked_submit):
mocked_submit.return_value = RecaptchaResponse(is_valid=True)
...
Originally developed by Praekelt Consulting
Inspired Marco Fucci's blogpost titled Integrating reCAPTCHA with Django
client.py taken from recaptcha-client licensed MIT/X11 by Mike Crawford.
reCAPTCHA copyright 2012 Google.
FAQs
Django recaptcha form field/widget app.
We found that django-recaptcha demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.