reCAPTCHA Python client

Latest release:1.0rc1
Author:2degrees Limited

This is a pythonic and well-documented reCAPTCHA client that supports all the features of the remote API to generate and verify CAPTCHA challenges.

The library has been created using Python 2.7 but is expected to work in Python 2.6 as well.

Mailhide support is outside the scope of the project.


Firstly, you need to initialize the client:

from recaptcha import RecaptchaClient
recaptcha_client = RecaptchaClient('private key', 'public key')

The client is stateless, so it’s absolutely fine to create it once and reuse it as many times as you want, even across different threads.

For more information, read the documentation for RecaptchaClient.

Generating challenges

To generate the markup to present a challenge, you need to use the RecaptchaClient.get_challenge_markup() method:

>>> print recaptcha_client.get_challenge_markup()

<script type="text/javascript">
    var RecaptchaOptions = {};
   <br />
   <textarea name="recaptcha_challenge_field" rows="3" cols="40"></textarea>

If the user failed to enter the correct solution and you need to redisplay the form with a different challenge, you need to call get_challenge_markup() with the argument was_previous_solution_incorrect set to True.

For more information, read the documentation for get_challenge_markup().

Verifying solutions

To verify the solution to a CAPTCHA challenge, you need to call the RecaptchaClient.is_solution_correct() method. For example:

    is_solution_correct = recaptcha_client.is_solution_correct(
        'hello world',
except RecaptchaUnreachableError as exc:
    disable_form(reason='reCAPTCHA is unreachable; please try again later')
except RecaptchaException as exc:
    if is_solution_correct:
        redisplay_form(error='Invalid solution to CAPTCHA challenge')

For more information, read the documentation for is_solution_correct().

Client API

class recaptcha.RecaptchaClient(private_key, public_key, recaptcha_options=None, verification_timeout=None)

Stateless reCAPTCHA client.

  • private_key (str) – The reCAPTCHA API private key
  • public_key (str) – The reCAPTCHA API public key
  • recaptcha_options (dict that can be serialized to JSON) – Options to customize the challenge
  • verification_timeout (int) – Maximum number of seconds to wait for reCAPTCHA to respond to a verification request

When verification_timeout is None, the default socket timeout will be used. See is_solution_correct().

get_challenge_markup(was_previous_solution_incorrect=False, use_ssl=False)

Return the X/HTML code to present a challenge.

Parameters:use_ssl (bool) – Whether to generate the markup with HTTPS URLs instead of HTTP ones
Return type:str

This method does not communicate with the remote reCAPTCHA API.

is_solution_correct(solution_text, challenge_id, remote_ip)

Report whether the solution_text for challenge_id is correct.

  • solution_text (basestring) – The user’s solution to the CAPTCHA challenge identified by challenge_id
  • remote_ip (str) – The IP address of the user who provided the solution_text
Return type:


  • RecaptchaInvalidChallengeError – If challenge_id is not valid
  • RecaptchaInvalidPrivateKeyError
  • RecaptchaUnreachableError – If it couldn’t communicate with the reCAPTCHA API or the connection timed out

solution_text must be a string encoded in RECAPTCHA_CHARACTER_ENCODING.

This method communicates with the remote reCAPTCHA API and uses the verification_timeout set in the constructor.


The character encoding to be used when making requests to the remote API.

Keep in mind that an ASCII string is also a valid UTF-8 string. So applications which use ASCII exclusively don’t need to encode their strings to use this library.

This is not officially documented but can be inferred from the encoding used in the noscript challenge.


exception recaptcha.RecaptchaException

Base class for all reCAPTCHA-related exceptions.

exception recaptcha.RecaptchaInvalidChallengeError
exception recaptcha.RecaptchaInvalidPrivateKeyError
exception recaptcha.RecaptchaUnreachableError


For general reCAPTCHA support, please visit the reCAPTCHA developers’ site.

For suggestions and questions about the library, please use our 2degrees-floss mailing list.

Indices and tables

Table Of Contents

This Page