Home/bypass-cloudflare-turnstile-with-python

How to Bypass Cloudflare Turnstile with Python#

March 26,2026

What is Cloudflare Turnstile?#

Cloudflare Turnstile is a smart CAPTCHA alternative designed to verify users without intrusive challenges. Unlike traditional CAPTCHAs that require image selection or text input, Turnstile runs invisible browser challenges to determine whether the visitor is human. It is widely adopted by websites using Cloudflare's services, and it can be a significant obstacle for web scraping and automation workflows.

Prerequisites#

Before getting started, make sure you have Python 3.7 or higher installed. You also need a NextCaptcha API key — sign up at NextCaptcha to get free trial credits. Then install the NextCaptcha Python SDK:

pip install nextcaptcha-python

Quick Start with NextCaptcha SDK#

First, create a NextCaptchaAPI instance with your API key. You can find your client key in the NextCaptcha dashboard:

from nextcaptcha import NextCaptchaAPI
 
api = NextCaptchaAPI(client_key="YOUR_CLIENT_KEY")

Now call the turnstile method with the target website URL and the Turnstile site key. The site key can be found in the data-sitekey attribute of the Turnstile widget on the target page:

result = api.turnstile(
    website_url="https://example.com",
    website_key="0x4XXXXXXXXXXXXXXXXX"
)
 
if result["status"] == "ready":
    token = result["solution"]["token"]
    print(f"Turnstile token: {token}")

Complete Example with Error Handling#

Here is a production-ready example with proper error handling and environment variable support:

import os
import sys
from nextcaptcha import NextCaptchaAPI
 
CLIENT_KEY = os.getenv("NEXTCAPTCHA_KEY", "YOUR_CLIENT_KEY")
WEBSITE_URL = "https://example.com"
WEBSITE_KEY = "0x4XXXXXXXXXXXXXXXXX"
 
api = NextCaptchaAPI(client_key=CLIENT_KEY)
 
try:
    result = api.turnstile(
        website_url=WEBSITE_URL,
        website_key=WEBSITE_KEY
    )
 
    if result["status"] == "ready":
        token = result["solution"]["token"]
        print(f"Turnstile solved successfully!")
        print(f"Token: {token[:50]}...")
    else:
        print(f"Failed to solve: {result.get('errorDescription', 'Unknown error')}")
        sys.exit(1)
 
except Exception as e:
    print(f"Error: {e}")
    sys.exit(1)

Using the Raw API (Without SDK)#

If you prefer not to use the SDK, you can call the NextCaptcha API directly using the requests library. This approach gives you full control over the HTTP requests:

import requests
import time
 
API_KEY = "YOUR_API_KEY"
WEBSITE_URL = "https://example.com"
WEBSITE_KEY = "0x4XXXXXXXXXXXXXXXXX"
 
# Step 1: Create task
response = requests.post("https://api.nextcaptcha.com/createTask", json={
    "clientKey": API_KEY,
    "task": {
        "type": "TurnstileTaskProxyless",
        "websiteURL": WEBSITE_URL,
        "websiteKey": WEBSITE_KEY
    }
})
 
data = response.json()
if data.get("errorId", 0) != 0:
    print(f"Error creating task: {data.get('errorDescription')}")
    exit()
 
task_id = data["taskId"]
print(f"Task created: {task_id}")
 
# Step 2: Poll for result
while True:
    time.sleep(3)
    result = requests.post("https://api.nextcaptcha.com/getTaskResult", json={
        "clientKey": API_KEY,
        "taskId": task_id
    }).json()
 
    if result["status"] == "ready":
        token = result["solution"]["token"]
        print(f"Solved! Token: {token[:50]}...")
        break
    elif result["status"] == "failed":
        print(f"Failed: {result.get('errorDescription')}")
        break
    else:
        print("Waiting for solution...")

This approach involves two API calls: createTask to submit the Turnstile challenge, and getTaskResult to poll for the solution. The polling interval of 3 seconds is recommended to avoid rate limiting.

Summary#

In this guide, we covered two methods to bypass Cloudflare Turnstile with Python: using the NextCaptcha Python SDK for a simple, high-level approach, and using the raw API for full control. NextCaptcha handles the Turnstile challenge solving automatically, returning a valid token that you can submit to the target website. For more details, check the links below: