{"id":13469305,"url":"https://github.com/django-recaptcha/django-recaptcha","last_synced_at":"2025-12-16T18:02:46.706Z","repository":{"id":923432,"uuid":"688991","full_name":"django-recaptcha/django-recaptcha","owner":"django-recaptcha","description":" Django reCAPTCHA form field/widget integration app.","archived":false,"fork":false,"pushed_at":"2025-12-09T22:45:04.000Z","size":412,"stargazers_count":1036,"open_issues_count":19,"forks_count":263,"subscribers_count":36,"default_branch":"main","last_synced_at":"2025-12-13T04:22:58.803Z","etag":null,"topics":["django","python","recaptcha","recaptcha-v3","recaptchav2"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/django-recaptcha/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/django-recaptcha.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2010-05-27T10:10:34.000Z","updated_at":"2025-12-12T10:10:13.000Z","dependencies_parsed_at":"2023-02-19T15:01:06.601Z","dependency_job_id":"e8eff61a-0996-4bf2-b87d-52745bd6291e","html_url":"https://github.com/django-recaptcha/django-recaptcha","commit_stats":{"total_commits":403,"total_committers":89,"mean_commits":4.52808988764045,"dds":0.8387096774193549,"last_synced_commit":"bbb7e2898c6dca1d284e1b448250b134899aedbb"},"previous_names":["django-recaptcha/django-recaptcha","torchbox/django-recaptcha","praekelt/django-recaptcha"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/django-recaptcha/django-recaptcha","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django-recaptcha%2Fdjango-recaptcha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django-recaptcha%2Fdjango-recaptcha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django-recaptcha%2Fdjango-recaptcha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django-recaptcha%2Fdjango-recaptcha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/django-recaptcha","download_url":"https://codeload.github.com/django-recaptcha/django-recaptcha/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django-recaptcha%2Fdjango-recaptcha/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27730942,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-14T02:00:11.348Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","python","recaptcha","recaptcha-v3","recaptchav2"],"created_at":"2024-07-31T15:01:32.600Z","updated_at":"2025-12-16T18:02:46.698Z","avatar_url":"https://github.com/django-recaptcha.png","language":"Python","funding_links":[],"categories":["Python","D"],"sub_categories":[],"readme":"# Django reCAPTCHA \u003c!-- omit from toc --\u003e\n\n**Django reCAPTCHA form field/widget integration app.**\n\n[![PyPI latest version](https://img.shields.io/pypi/v/django-recaptcha.svg)](https://pypi.org/project/django-recaptcha/)\n[![PyPI monthly downloads](https://img.shields.io/pypi/dm/django-recaptcha.svg)](https://pypi.org/project/django-recaptcha/)\n[![CI status](https://github.com/django-recaptcha/django-recaptcha/workflows/CI/badge.svg)](https://github.com/django-recaptcha/django-recaptcha/actions)\n[![Coverage Status](https://coveralls.io/repos/github/django-recaptcha/django-recaptcha/badge.svg?branch=main)](https://coveralls.io/github/django-recaptcha/django-recaptcha?branch=main)\n\n\u003e [!NOTE]\n\u003e 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.\n\u003e\n\u003e Django reCAPTCHA uses a modified version of the [Python reCAPTCHA client](http://pypi.python.org/pypi/recaptcha-client) which is included in the package as `client.py`.\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Fields](#fields)\n  - [Widgets](#widgets)\n  - [reCAPTCHA V3 Score](#recaptcha-v3-score)\n  - [reCAPTCHA V3 Action](#recaptcha-v3-action)\n  - [Local Development and Functional Testing](#local-development-and-functional-testing)\n- [Credits](#credits)\n\n## Requirements\n\nTested with:\n\n- Python: 3.9, 3.10, 3.11, 3.12, 3.13\n- Django: 4.2, 5.0, 5.1 and 5.2\n- You can view the [Python-Django support matrix\n  here](https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django)\n\nThis package only supports modern, “evergreen” desktop and mobile\nbrowsers. For IE11 support, make sure to add a [polyfill for\nElement.closest](https://developer.mozilla.org/en-US/docs/Web/API/Element/closest#Polyfill).\n\n## Installation\n\n1.  [Sign up for reCAPTCHA](https://www.google.com/recaptcha/intro/index.html).\n\n2.  Install with `pip install django-recaptcha`.\n\n3.  Add `'django_recaptcha'` to your `INSTALLED_APPS` setting.\n\n```python\nINSTALLED_APPS = [\n    ...,\n    'django_recaptcha',\n    ...\n]\n```\n\n4.  Add the Google reCAPTCHA keys generated in step 1 to your Django\n    production settings with `RECAPTCHA_PUBLIC_KEY` and\n    `RECAPTCHA_PRIVATE_KEY`. Note that omitting these settings will\n    default to a set of test keys refer to [Local Development and\n    Functional Testing](#local-development-and-functional-testing) for\n    more information.\n\nFor example:\n\n```python\nRECAPTCHA_PUBLIC_KEY = 'MyRecaptchaKey123'\nRECAPTCHA_PRIVATE_KEY = 'MyRecaptchaPrivateKey456'\n```\n\nThese can also be specified per field by passing the `public_key`\nor `private_key` parameters to `ReCaptchaField` - see field usage\nbelow.\n\n5.  (OPTIONAL) If you require a proxy, add a `RECAPTCHA_PROXY` setting\n    (dictionary of proxies), for example:\n\n```python\nRECAPTCHA_PROXY = {'http': 'http://127.0.0.1:8000', 'https': 'https://127.0.0.1:8000'}\n```\n\n6.  (OPTIONAL) In the event `www.google.com` is not accessible the\n    `RECAPTCHA_DOMAIN` setting can be changed to `www.recaptcha.net` as\n    per the [reCAPTCHA\n    FAQ](https://developers.google.com/recaptcha/docs/faq#can-i-use-recaptcha-globally):\n\n```python\nRECAPTCHA_DOMAIN = 'www.recaptcha.net'\n```\n\nThis will change the Google JavaScript api domain as well as the client\nside field verification domain.\n\n## Usage\n\n### Fields\n\nThe quickest way to add reCAPTCHA to a form is to use the included\n`ReCaptchaField` field class. A `ReCaptchaV2Checkbox` will be rendered\nby default. For example:\n\n```python\nfrom django import forms\nfrom django_recaptcha.fields import ReCaptchaField\n\nclass FormWithCaptcha(forms.Form):\n    captcha = ReCaptchaField()\n```\n\nBe sure to include the captcha field in your forms. There are many ways\nto add fields to forms in Django. We recommend you refer to the [form\nrendering\noptions](https://docs.djangoproject.com/en/dev/topics/forms/#form-rendering-options)\nand [rendering fields\nmanually](https://docs.djangoproject.com/en/dev/topics/forms/#rendering-fields-manually)\nsections of the [official Django documentation for\nforms](https://docs.djangoproject.com/en/dev/topics/forms).\n\nTo allow for runtime specification of keys you can optionally pass the\n`private_key` or `public_key` parameters to the constructor. For\nexample:\n\n```python\ncaptcha = ReCaptchaField(\n    public_key='76wtgdfsjhsydt7r5FFGFhgsdfytd656sad75fgh',\n    private_key='98dfg6df7g56df6gdfgdfg65JHJH656565GFGFGs',\n)\n```\n\nIf specified, these parameters will be used instead of your reCAPTCHA\nproject settings.\n\n### Widgets\n\nThere are three widgets that can be used with the `ReCaptchaField`\nclass:\n\n- `ReCaptchaV2Checkbox` for [Google reCAPTCHA V2 - Checkbox](https://developers.google.com/recaptcha/docs/display)\n- `ReCaptchaV2Invisible` for [Google reCAPTCHA V2 - Invisible](https://developers.google.com/recaptcha/docs/invisible)\n- `ReCaptchaV3` for [Google reCAPTCHA V3](https://developers.google.com/recaptcha/docs/v3)\n\nTo make use of widgets other than the default Google reCAPTCHA V2 -\nCheckbox widget, simply replace the `ReCaptchaField` widget. For\nexample:\n\n```python\nfrom django import forms\nfrom django_recaptcha.fields import ReCaptchaField\nfrom django_recaptcha.widgets import ReCaptchaV2Invisible\n\nclass FormWithCaptcha(forms.Form):\n    captcha = ReCaptchaField(widget=ReCaptchaV2Invisible)\n```\n\nThe reCAPTCHA widget supports several [data\nattributes](https://developers.google.com/recaptcha/docs/display#render_param)\nthat customize the behaviour of the widget, such as `data-theme`,\n`data-size`, etc. You can forward these options to the widget by passing\nan `attrs` parameter to the widget, containing a dictionary of options.\nFor example:\n\n```python\ncaptcha = fields.ReCaptchaField(\n    widget=widgets.ReCaptchaV2Checkbox(\n        attrs={\n            'data-theme': 'dark',\n            'data-size': 'compact',\n        }\n    )\n)\n# The ReCaptchaV2Invisible widget\n# ignores the \"data-size\" attribute in favor of 'data-size=\"invisible\"'\n```\n\nThe reCAPTCHA api supports several\n[parameters](https://developers.google.com/recaptcha/docs/display#js_param).\nTo customise the parameters that get sent along pass an `api_params`\nparameter to the widget, containing a dictionary of options. For\nexample:\n\n```python\ncaptcha = fields.ReCaptchaField(\n    widget=widgets.ReCaptchaV2Checkbox(\n        api_params={'hl': 'cl', 'onload': 'onLoadFunc'}\n    )\n)\n# The dictionary is urlencoded and appended to the reCAPTCHA api url.\n```\n\nBy default, the widgets provided only supports a single form with a\nsingle widget on each page.\n\nThe language can be set with the 'hl' parameter, look at [language\ncodes](https://developers.google.com/recaptcha/docs/language) for the\nlanguage code options. Note that translations need to be added to this\npackage for the errors to be shown correctly. Currently the package has\nerror translations for the following language codes: es, fr, nl, pl,\npt_BR, ru, zh_CN, zh_TW\n\nHowever, the JavaScript used by the widgets can easily be overridden in\nthe templates.\n\nThe templates are located in:\n\n- `django_recaptcha/includes/js_v2_checkbox.html` for overriding the reCAPTCHA V2 - Checkbox template\n- `django_recaptcha/includes/js_v2_invisible.html` for overriding the reCAPTCHA V2 - Invisible template\n- `django_recaptcha/includes/js_v3.html` for overriding the reCAPTCHA V3 template\n\nFor more information about overriding templates look at [Django's template override](https://docs.djangoproject.com/en/4.2/howto/overriding-templates/)\n\n### reCAPTCHA V3 Score\n\nAs of version 3, reCAPTCHA also returns a score value. This can be used\nto determine the likelihood of the page interaction being a bot. See the Google [documentation](https://developers.google.com/recaptcha/docs/v3#score)\nfor more details.\n\nTo set a project wide score limit use the `RECAPTCHA_REQUIRED_SCORE` setting.\n\nFor example:\n\n```python\nRECAPTCHA_REQUIRED_SCORE = 0.85\n```\n\nFor per field, runtime, specification the score can also be passed to the widget:\n\n```python\ncaptcha = fields.ReCaptchaField(\n    widget=ReCaptchaV3(required_score=0.85)\n)\n```\n\nIn the event the score does not meet the requirements, the field\nvalidation will fail as expected and an error message will be logged.\n\n### reCAPTCHA V3 Action\n\n[Google's reCAPTCHA V3 API supports passing an action value](https://developers.google.com/recaptcha/docs/v3#actions).\nActions 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.\n\nTo set the action value, pass an `action` argument when instantiating the ReCaptcha\nwidget. Be careful to only use alphanumeric characters, slashes and underscores as stated in the reCAPTCHA documentation.\n\n```python\ncaptcha = fields.ReCaptchaField(\n    widget=widgets.ReCaptchaV3(\n        action='signup'\n    )\n)\n```\n\nSetting an action is entirely optional. If you don't specify an action, no action will be passed to the reCAPTCHA V3 API.\n\n### Local Development and Functional Testing\n\nIf `RECAPTCHA_PUBLIC_KEY` and `RECAPTCHA_PRIVATE_KEY` are not set,\ndjango-recaptcha will use [Google's test\nkeys](https://developers.google.com/recaptcha/docs/faq) instead. These\ncannot be used in production since they always validate to true and a\nwarning will be shown on the reCAPTCHA. Google's test keys only work for\nreCAPTCHA version 2.\n\nTo bypass the security check that prevents the test keys from being used\nunknowingly add\n`SILENCED_SYSTEM_CHECKS = [..., 'django_recaptcha.recaptcha_test_key_error', ...]`\nto your settings, here is an example:\n\n```python\nSILENCED_SYSTEM_CHECKS = ['django_recaptcha.recaptcha_test_key_error']\n```\n\nIf you want to mock the call to Google's servers altogether, have a look\nat\n[test_fields.py](https://github.com/django-recaptcha/django-recaptcha/blob/main/django_recaptcha/tests/test_fields.py):\n\n```python\nfrom unittest.mock import patch\nfrom django.test import TestCase\nfrom django_recaptcha.client import RecaptchaResponse\n\nclass TestFields(TestCase):\n    @patch(\"django_recaptcha.fields.client.submit\")\n    def test_client_success_response(self, mocked_submit):\n        mocked_submit.return_value = RecaptchaResponse(is_valid=True)\n        ...\n```\n\n## Credits\n\nOriginally developed by [Praekelt Consulting](https://github.com/praekelt).\n\nInspired Marco Fucci's blogpost titled [Integrating reCAPTCHA with Django](http://www.marcofucci.com/tumblelog/26/jul/2009/integrating-recaptcha-with-django).\n\n`client.py` taken from [recaptcha-client](http://pypi.python.org/pypi/recaptcha-client) licensed MIT/X11 by Mike Crawford.\n\nreCAPTCHA copyright 2012 Google.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjango-recaptcha%2Fdjango-recaptcha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjango-recaptcha%2Fdjango-recaptcha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjango-recaptcha%2Fdjango-recaptcha/lists"}