Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
reCAPTCHA API for Python 2. Improved version of Python's recaptcha-client-1.0.6, adding full SSL support, a timeout setting, and more.
branch: master
Failed to load latest commit information.
recaptcha Code cleanup. Variable change.
recaptcha_client.egg-info first commit
.gitignore .DS_Store banished
PKG-INFO first commit
README.markdown Edited readme file. first commit
setup.cfg first commit first commit



recaptcha-client-1.0.6-ssl is a Python 2.x module that interfaces with reCAPTCHA and reCAPTCHA Mailhide. It generates HTML to let you display reCAPTCHA on your website, and to submit reCAPTCHA attempts to the reCAPTCHA server.

  • reCAPTCHA is generally used inside HTML forms. Users must solve a reCAPTCHA to submit a form successfully.
  • reCAPTCHA Mailhide masks email addresses, and requires a user to solve a reCAPTCHA to reveal the full email address.

This code is forked from the original Python recaptcha-client 1.0.6, and is fully backwards compatible with it (no code changes are necessary to implement). It has all of the features of recaptcha-client 1.0.6, plus the following new ones:

  • SSL support for submit() in
  • SSL support for asurl() and ashtml() in
  • Timeout variable for submit().
  • Exception handling for urllib2.urlopen in submit().
  • Lots of comments.
  • Code tidying.

This code falls under its original MIT/X11 license. The author of this fork is not associated or affiliated with reCAPTCHA in any way.

More information about reCAPTCHA and reCAPTCHA Mailhide:



If you wish to use reCAPTCHA Mailhide (recaptcha.client.mailhide), you must also install the Python Crypto library. This is not required if you only use reCAPTCHA (recaptcha.client.captcha). The easiest way to install this is with pip:

$ sudo pip install pycrypto
$ python
>>> import Crypto
>>> Crypto
<module 'Crypto' from '.../site-packages/Crypto/__init__.pyc'>

Download and Install:

Make sure to uninstall any old versions of recaptcha-client first.

$ git clone git://
$ cd .../recaptcha-client-1.0.6-ssl
$ sudo python install

Test Installation:

$ python
>>> import recaptcha
>>> recaptcha
<module 'recaptcha' from 'recaptcha/__init__.pyc'>


$ python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
$ sudo rm -r <path_to_python>.../site-packages/recaptcha_client-1.0.6_ssl*.egg


  • You must have both a Public and Private reCAPTCHA API Key.
  • These keys are different than reCAPTCHA Mailhide API Keys.
  • Register for free keys here:
  • Note: A global key is not needed for local development (

Generate reCAPTCHA HTML:

Place the generated HTML inside your form code, and render it to a webpage as a HTTP Response.

>>> from recaptcha.client.captcha import displayhtml
>>> html = displayhtml(public_key=PUBLIC_KEY, use_ssl=True, error=None)
>>> print html
<script type="text/javascript" src=""></script><noscript>  <iframe src="" height="300" width="500" frameborder="0"></iframe><br />  <textarea name="recaptcha_challenge_field" rows="3" cols="40"></textarea>  <input type='hidden' name='recaptcha_response_field' value='manual_challenge' /></noscript>


After receiving an HTTP POST Request from a submitted form, extract both recaptcha_challenge_field and recaptcha_response_field from the POST. You should also extract the clients IP address (see your API/webserver for details on how to do this).

>>> from recaptcha.client.captcha import submit
>>> recaptcha_challenge_field = http_request_post.get("recaptcha_challenge_field", None)   # Psuedo-code
>>> recaptcha_response_field = http_request_post.get("recaptcha_response_field", None)     # Psuedo-code
>>> client_ip_address = ...
>>> recaptcha_response = submit(recaptcha_challenge_field, recaptcha_response_field, PRIVATE_KEY, client_ip_address, use_ssl=True, timeout_seconds=60)
>>> if recaptcha_response.is_valid:
...    print "reCAPTCHA was solved successfully"
... else:
...    print "reCAPTCHA failed with error: %s" % recaptcha_response.error_code

reCAPTCHA Mailhide Usage

  • You must have both a Public and Private reCAPTCHA Mailhide API Key.
  • These keys are different than reCAPTCHA API Keys.
  • Register for a free keys here:
  • You MUST install Python's Crypto library to use this. Otherwise an exception will be raised. See Installation for details.

Generate reCAPTCHA Mailhide HTML:

Place this HTML inside your webpage. The email address will be abridged. To reveal the full email address, the user clicks on a link to open a pop-up window containing a reCAPTCHA. After solving the reCAPTCHA, the full email address is displayed.

>>> from recaptcha.client.mailhide import ashtml
>>> EMAIL = ""
>>> print html
susa<a href=";c=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY" onclick="';c=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY', '', 'toolbar=0,scrollbars=0,location=0,statusbar=0,menubar=0,resizable=0,width=500,height=300'); return false;" title="Reveal this e-mail address">...</a>
Something went wrong with that request. Please try again.