Skip to main content

Django recaptcha form field/widget app.

Project description

Django reCAPTCHA

Django reCAPTCHA form field/widget integration app.

django-recaptcha uses a modified version of the Python reCAPTCHA client which is included in the package as


  1. Install or add django-recaptcha to your Python path.

  2. Add captcha to your INSTALLED_APPS setting.

  3. Add a RECAPTCHA_PUBLIC_KEY setting to the project’s file. This is your public API key as provided by reCAPTCHA, i.e.:

    RECAPTCHA_PUBLIC_KEY = '76wtgdfsjhsydt7r5FFGFhgsdfytd656sad75fgh'

    This can be seperately specified at runtime by passing a public_key parameter when constructing the ReCaptchaField, see field usage below.

  4. Add a RECAPTCHA_PRIVATE_KEY setting to the project’s file. This is your private API key as provided by reCAPTCHA, i.e.:

    RECAPTCHA_PRIVATE_KEY = '98dfg6df7g56df6gdfgdfg65JHJH656565GFGFGs'

    This can be seperately specified at runtime by passing a private_key parameter when constructing the ReCaptchaField, see field usage below.

  5. Optionally add a RECAPTCHA_USE_SSL setting to the project’s file. This causes reCAPTCHA validation submits to be made over SSL, i.e.:


    If you don’t add this setting the default behaviour is to NOT use SSL. This can be seperately specified at runtime by passing a use_ssl parameter when constructing the ReCaptchaField, see field usage below.



The quickest way to add reCAPTHCA to a form is to use the included ReCaptchaField field type. A ReCaptcha widget will be rendered with the field validating itself without any further action required from you. For example:

from django import forms
from captcha.fields import ReCaptchaField

class FormWithCaptcha(forms.Form):
    captcha = ReCaptchaField()

To allow for runtime specification of keys and SSL usage you can optionally pass private_key, public_key or use_ssl parameters to the constructor, i.e.:

captcha = ReCaptchaField(

If specified these parameters will be used instead of your reCAPCTHA project settings.

The reCAPTCHA widget supports several Javascript options variables customizing the behaviour of the widget, such as theme and lang. You can forward these options to the widget by passing an attr parameter containing a dictionary of options to ReCaptchaField, i.e.:

captcha = ReCaptchaField(attrs={'theme' : 'clean'})

The captcha client takes the key/value pairs and writes out the RecaptchaOptions value in JavaScript.

Unit Testing

django-recaptcha introduces an environmental variable RECAPTCHA_TESTING which helps facilitate tests. The environmental variable should be set to “True”, and cleared, using the setUp() and tearDown() methods in your test classes.

Setting RECAPTCHA_TESTING to True causes django-recaptcha to accept “PASSED” as the recaptcha_response_field value.


import os
os.environ['RECAPTCHA_TESTING'] = 'True'

form_params = {'recaptcha_response_field': 'PASSED'}
form = RegistrationForm(form_params) # assuming only one ReCaptchaField
form.is_valid() # True

os.environ['RECAPTCHA_TESTING'] = 'False'
form.is_valid() # False

Passing any other values will cause django-recaptcha to continue normal processing and return a form error.

Check for a full example.


To make Recapcha work in ajax-loaded forms:

  1. import recaptcha_ajax.js on your page (not in the loaded template):

    <script type=”text/javascript” src=””></script>




Inspired Marco Fucci’s blogpost titled Integrating reCAPTCHA with Django taken from recaptcha-client licenced MIT/X11 by Mike Crawford.

reCAPTCHA copyright 2012 Google.


Praekelt Foundation

  • Shaun Sephton
  • Peter Pistorius
  • Hedley Roos



0.0.9 (2014-02-14)

  1. Bugfix: release master and not develop. This should fix the confusion due to master having been the default branch on Github.

0.0.8 (2014-02-13)

  1. Bugfix: remove reference to options.html.

0.0.7 (2014-02-12)

  1. Make it possible to load the widget via ajax.

0.0.6 (2013-01-31)

  1. Added an extra parameter lang to bypass Google’s language bug. See
  2. widget.html no longer includes options.html. Options are added directly to widget.html

0.0.5 (2013-01-17)

  1. Removed django-registration dependency
  2. Changed testing mechanism to environmental variable RECAPTCHA_TESTING


  1. Handle missing REMOTE_ADDR request meta key. Thanks Joe Jasinski.
  2. Added checks for settings.DEBUG to facilitate tests. Thanks Victor Neo.
  3. Fix for correct iframe URL in case of no javascript. Thanks gerdemb.

0.0.3 (2011-09-20)

  1. Don’t force registration version thanks kshileev.
  2. Render widget using template, thanks denz.

0.0.2 (2011-08-10)

  1. Use remote IP when validating.
  2. Added SSL support, thanks Brooks Travis.
  3. Added support for Javascript reCAPTCHA widget options, thanks Brandon Taylor.
  4. Allow for key and ssl specification at runtime, thanks Evgeny Fadeev.

0.0.1 (2010-06-17)

  1. Initial release.

Project details

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
django_recaptcha-0.0.9-py2.7.egg (14.4 kB) Copy SHA256 hash SHA256 Egg 2.7 Feb 14, 2014
django-recaptcha-0.0.9.tar.gz (8.9 kB) Copy SHA256 hash SHA256 Source None Feb 14, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page