https://github.com/hasnainshahidx/turnstile_solver
A Python-based solver that finds, clicks, and solves Cloudflare Turnstile CAPTCHA using Selenium and Chrome DevTools Protocol (CDP) — supports both headless and GUI modes.
https://github.com/hasnainshahidx/turnstile_solver
automation-test cloudflare-bypass cloudflare-solver hasnainshahidx helpers-library python-library python-package selenium turnstile-bypass turnstile-solver web-automation
Last synced: about 19 hours ago
JSON representation
A Python-based solver that finds, clicks, and solves Cloudflare Turnstile CAPTCHA using Selenium and Chrome DevTools Protocol (CDP) — supports both headless and GUI modes.
- Host: GitHub
- URL: https://github.com/hasnainshahidx/turnstile_solver
- Owner: hasnainshahidx
- License: mit
- Created: 2025-07-26T00:21:54.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-01-13T13:28:07.000Z (6 months ago)
- Last Synced: 2026-01-13T16:25:31.218Z (6 months ago)
- Topics: automation-test, cloudflare-bypass, cloudflare-solver, hasnainshahidx, helpers-library, python-library, python-package, selenium, turnstile-bypass, turnstile-solver, web-automation
- Language: Python
- Homepage: https://pypi.org/project/turnstile-solver/
- Size: 33.2 KB
- Stars: 43
- Watchers: 0
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# turnstile_solver
**Click and solve Cloudflare Turnstile CAPTCHA — supports both headless and GUI modes.**
---
## 🔍 Features
- ✅ Supports **embedded** and **challenge page** Turnstile variants
- ✅ Uses **Chrome DevTools Protocol** for DOM access and interaction
- ✅ Human-like mouse movement using CDP or **PyAutoGUI**
- ✅ Works in both **headless** and **visible** Chrome modes
- ✅ Uses template-based **image matching** to locate the checkbox
- ✅ Optional verification detection via **MutationObserver**
---
## ⚠️ Disclaimer
Note: This package is provided for educational and testing purposes only. Unauthorized use of this package to circumvent security measures is strictly prohibited. The author and contributors are not responsible for any misuse or consequences arising from the use of this package.
---
## 📦 Installation
```bash
pip install turnstile_solver
```
---
## ⚙️ Requirements
- Python 3.7+=
- NumPy
- OpenCV (`opencv-python`)
- PyAutoGUI (optional, for physical mouse clicks)
- Selenium
---
## 🚀 Usage Example
### ✅ Option 1: One-shot `solve()` function
Use this when you want a simple, one-time solve without worrying about managing state.
```python
from seleniumbase import Driver
from turnstile_solver import solve
driver = Driver(uc=True, headless=True)
driver.get("https://gitlab.com/users/sign_in")
success = solve(
driver,
detect_timeout=5, # Timeout for detecting the Turnstile widget
solve_timeout=30, # Timeout for solving the Turnstile challenge
interval=1, # Interval (in seconds) between retries/checks
verify=True, # Whether to verify after solving
click_method="cdp", # Use "cdp" or "pyautogui" for clicking
theme="auto", # Options: "auto", "dark", or "light"
grayscale=False, # Whether to convert image to grayscale before solving
thresh=0.8, # Matching threshold for image verification
enable_logging=True # Enable debug/info logging
)
print("Solved:", success)
```
---
### ✅ Option 2: Reusable `Solver` class
Use this when solving Turnstile multiple times or when you want better performance and state control.
```python
from seleniumbase import Driver
from turnstile_solver import Solver
driver = Driver(uc=True, headless=True)
solver = Solver(driver, enable_logging=True, click_method='pyautogui')
driver.get("https://gitlab.com/users/sing_up")
if solver.detect(timeout= 5, interval=1):
result = solver.solve(verify=True, timeout=60, interval=1)
print("result")
driver.get("https://2captcha.com/demo/cloudflare-turnstile-challenge")
if solver.detect(timeout= 5, interval=1):
result = solver.solve(timeout= 30, interval= 1, verify= False)
print("result")
# Stops script injection on future navigations; you can still call .solve() or .detect() again if needed
solver.cleanup()
```
---
### 🔍 Parameter Reference
| Parameter | Type | Description |
|------------------|-------------------------------------|-------------|
| `driver` | `WebDriver` | Selenium driver (must be on a page with Turnstile). |
| `detect_timeout` / `solve_timeout` / `timeout` | `int` | Max time (in seconds) to try detecting or solving. |
| `interval` | `float` | Delay between retries (in seconds). Default: `1.0` |
| `verify` | `bool` | If `True`, waits for verification. Otherwise just clicks. |
| `click_method` | `"cdp"` \| `"pyautogui"` | `'cdp'` (works in headless) or `'pyautogui'` (GUI only). |
| `theme` | `"auto"` \| `"dark"` \| `"light"` | Match Turnstile theme for template matching. |
| `grayscale` | `bool` | Use grayscale for matching (faster). |
| `thresh` | `float` | Confidence threshold (0–1). Default: `0.8` |
| `enable_logging` | `bool` | Print debug logs to console. |
---
### 🔁 Which One Should I Use?
| Scenario | Use |
|--------------------------------------|-------------------|
| Quick one-time solve | `solve()` |
| Multiple Turnstiles on same session | `Solver` class |
| Full control / performance tuning | `Solver` class |
| Script or CLI use | `solve()` |
---
## Limitations
While this library is designed to work in both **headless** and **GUI** modes, it's important to understand the difference in trust levels between click methods:
- **CDP (Chrome DevTools Protocol)** clicks are faster and work in headless mode, but they are generally **less trusted** by Cloudflare.
- **PyAutoGUI** simulates **real human mouse movements**, making clicks more realistic and harder to detect, **but it only works in GUI mode**.
**However**, if you're using a **clean IP address** and a **well-spoofed browser environment**, CDP clicks may still be sufficient to pass the challenge with a low risk score.
For better results and stronger browser spoofing, consider using **[SeleniumBase](https://github.com/seleniumbase/SeleniumBase)** instead of undetectable-chromedriver. It offers more advanced stealth capabilities out of the box.
---
## 📜 License
MIT License
---
## 💬 Feedback or Contributions
Found a bug or have a suggestion?
Feel free to [open an issue](https://github.com/hasnainshahidx/turnstile_solver/issues) or submit a pull request.
Contributions are welcome and appreciated!
## 🙏 Note from the Author
This is my first open-source project
As a new developer, I'm continuously learning—so there might be imperfections or areas for improvement.
Any feedback, suggestions, or contributions are more than welcome to help make this project better!
## 📬 Contact & Support
For questions or support:
- 🌐 [Hasnain Shahid](https://hasnainshahidx.github.io/)
- 📧 Email: hasnainshahid822@gmail.com