Skip to main content

Add Cloudflare Turnstile validator widget to the forms of your django project

Project description

Add Cloudflare Turnstile validator widget to the forms of your django project.

This project refers to github project django-hcaptcha (author: AndrejZbin)


Add “turnstile” to your INSTALLED_APPS setting like this:


For development purposes no further configuration is required. By default, django-Turnstile will use dummy keys.

For production, you’ll need to obtain your Turnstile site key and secret key and add them to you settings:

TURNSTILE_SITEKEY = '<your sitekey>'
TURNSTILE_SECRET = '<your secret key>'

You can also configure your Turnstile widget globally (see all options):

    'onload': 'name_of_js_function',
    'render': 'explicit',
    'theme': 'dark',  # do not use data- prefix
    'size': 'compact',  # do not use data- prefix

If you need to, you can also override default turnstile endpoints:


Use proxies:

   'http': '',

Change default verification timeout:



Simply add TurnstileField to your forms:

from turnstile.fields import TurnstileField

class Forms(forms.Form):
    turnstile = TurnstileField()

In your template, if you need to, you can then use {{ form.turnstile }} to access the field.

You can override default config by passing additional arguments:

class Forms(forms.Form):
    turnstile = TurnstileField(theme='dark', size='compact')

How it Works

When a form is submitted by a user, Turnstile’s JavaScript will send one POST parameter to your backend: cf-turnstile-response. It will be received by your app and will be used to complete the turnstile form field in your backend code.

When your app receives these two values, the following will happen:

  • Your backend will send these values to the Cloudflare Turnstile servers

  • Their servers will indicate whether the values in the fields are correct

  • If so, your turnstile form field will validate correctly

Unit Tests

You will need to disable the Turnstile field in your unit tests, since your tests obviously cannot complete the Turnstile successfully. One way to do so might be something like:

from unittest.mock import MagicMock, patch

from django.test import TestCase

@patch("turnstile.fields.TurnstileField.validate", return_value=True)
class ContactTest(TestCase):
    test_msg = {
        "name": "pandora",
        "message": "xyz",
        "turnstile": "xxx",  # Any truthy value is fine

    def test_something(self, mock: MagicMock) -> None:
        response ="/contact/", self.test_msg)
        self.assertEqual(response.status_code, HTTP_302_FOUND)

Project details

Download files

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

Source Distribution

django-turnstile-0.1.0.tar.gz (5.3 kB view hashes)

Uploaded Source

Built Distribution

django_turnstile-0.1.0-py3-none-any.whl (6.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page