# 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, developed at the age of 18.
As a young 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
Raw data
{
"_id": null,
"home_page": null,
"name": "turnstile-solver",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "captcha-solver, turnstile-solver, cloudflare-bypass, solver, automation",
"author": null,
"author_email": "Hasnain Shahid <hasnainshahid822@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/be/90/8faa4e2f3c7a3e5e01f8eeb0709f747dae60d585ce88be08732abd7facb1/turnstile_solver-0.1.4.tar.gz",
"platform": null,
"description": "# turnstile_solver\r\n\r\n**Click and solve Cloudflare Turnstile CAPTCHA \u2014 supports both headless and GUI modes.**\r\n\r\n---\r\n\r\n## \ud83d\udd0d Features\r\n\r\n- \u2705 Supports **embedded** and **challenge page** Turnstile variants \r\n- \u2705 Uses **Chrome DevTools Protocol** for DOM access and interaction \r\n- \u2705 Human-like mouse movement using CDP or **PyAutoGUI** \r\n- \u2705 Works in both **headless** and **visible** Chrome modes \r\n- \u2705 Uses template-based **image matching** to locate the checkbox \r\n- \u2705 Optional verification detection via **MutationObserver**\r\n\r\n---\r\n\r\n## \u26a0\ufe0f Disclaimer\r\nNote: 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.\r\n\r\n---\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n```bash\r\npip install turnstile_solver\r\n```\r\n\r\n---\r\n\r\n## \u2699\ufe0f Requirements\r\n\r\n- Python 3.7+=\r\n- NumPy\r\n- OpenCV (`opencv-python`)\r\n- PyAutoGUI (optional, for physical mouse clicks)\r\n- Selenium\r\n\r\n---\r\n\r\n## \ud83d\ude80 Usage Example\r\n\r\n### \u2705 Option 1: One-shot `solve()` function\r\n\r\nUse this when you want a simple, one-time solve without worrying about managing state.\r\n\r\n```python\r\nfrom seleniumbase import Driver\r\nfrom turnstile_solver import solve\r\n\r\ndriver = Driver(uc=True, headless=True)\r\ndriver.get(\"https://gitlab.com/users/sign_in\")\r\n\r\nsuccess = solve(\r\n driver,\r\n detect_timeout=5, # Timeout for detecting the Turnstile widget\r\n solve_timeout=30, # Timeout for solving the Turnstile challenge\r\n interval=1, # Interval (in seconds) between retries/checks\r\n verify=True, # Whether to verify after solving\r\n click_method=\"cdp\", # Use \"cdp\" or \"pyautogui\" for clicking\r\n theme=\"auto\", # Options: \"auto\", \"dark\", or \"light\"\r\n grayscale=False, # Whether to convert image to grayscale before solving\r\n thresh=0.8, # Matching threshold for image verification\r\n enable_logging=True # Enable debug/info logging\r\n)\r\n\r\nprint(\"Solved:\", success)\r\n```\r\n\r\n---\r\n\r\n### \u2705 Option 2: Reusable `Solver` class\r\n\r\nUse this when solving Turnstile multiple times or when you want better performance and state control.\r\n\r\n```python\r\nfrom seleniumbase import Driver\r\nfrom turnstile_solver import Solver\r\n\r\ndriver = Driver(uc=True, headless=True)\r\n\r\nsolver = Solver(driver, enable_logging=True, click_method='pyautogui')\r\n\r\ndriver.get(\"https://gitlab.com/users/sing_up\")\r\nif solver.detect(timeout= 5, interval=1):\r\n result = solver.solve(verify=True, timeout=60, interval=1)\r\n print(\"result\")\r\n\r\ndriver.get(\"https://2captcha.com/demo/cloudflare-turnstile-challenge\")\r\nif solver.detect(timeout= 5, interval=1):\r\n result = solver.solve(timeout= 30, interval= 1, verify= False)\r\n print(\"result\")\r\n\r\n# Stops script injection on future navigations; you can still call .solve() or .detect() again if needed\r\nsolver.cleanup()\r\n```\r\n\r\n---\r\n\r\n### \ud83d\udd0d Parameter Reference\r\n\r\n| Parameter | Type | Description |\r\n|------------------|-------------------------------------|-------------|\r\n| `driver` | `WebDriver` | Selenium driver (must be on a page with Turnstile). |\r\n| `detect_timeout` / `solve_timeout` / `timeout` | `int` | Max time (in seconds) to try detecting or solving. |\r\n| `interval` | `float` | Delay between retries (in seconds). Default: `1.0` |\r\n| `verify` | `bool` | If `True`, waits for verification. Otherwise just clicks. |\r\n| `click_method` | `\"cdp\"` \\| `\"pyautogui\"` | `'cdp'` (works in headless) or `'pyautogui'` (GUI only). |\r\n| `theme` | `\"auto\"` \\| `\"dark\"` \\| `\"light\"` | Match Turnstile theme for template matching. |\r\n| `grayscale` | `bool` | Use grayscale for matching (faster). |\r\n| `thresh` | `float` | Confidence threshold (0\u20131). Default: `0.8` |\r\n| `enable_logging` | `bool` | Print debug logs to console. |\r\n\r\n---\r\n\r\n### \ud83d\udd01 Which One Should I Use?\r\n\r\n| Scenario | Use |\r\n|--------------------------------------|-------------------|\r\n| Quick one-time solve | `solve()` |\r\n| Multiple Turnstiles on same session | `Solver` class |\r\n| Full control / performance tuning | `Solver` class |\r\n| Script or CLI use | `solve()` |\r\n\r\n---\r\n\r\n## Limitations\r\n\r\nWhile 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:\r\n\r\n- **CDP (Chrome DevTools Protocol)** clicks are faster and work in headless mode, but they are generally **less trusted** by Cloudflare.\r\n- **PyAutoGUI** simulates **real human mouse movements**, making clicks more realistic and harder to detect, **but it only works in GUI mode**.\r\n\r\n**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.\r\n\r\nFor 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.\r\n\r\n---\r\n\r\n## \ud83d\udcdc License\r\n\r\nMIT License\r\n\r\n---\r\n\r\n## \ud83d\udcac Feedback or Contributions\r\n\r\nFound a bug or have a suggestion? \r\nFeel free to [open an issue](https://github.com/hasnainshahidx/turnstile_solver/issues) or submit a pull request. \r\nContributions are welcome and appreciated!\r\n\r\n## \ud83d\ude4f Note from the Author\r\n\r\nThis is my first open-source project, developed at the age of 18. \r\nAs a young developer, I'm continuously learning\u2014so there might be imperfections or areas for improvement. \r\nAny feedback, suggestions, or contributions are more than welcome to help make this project better!\r\n\r\n## \ud83d\udcec Contact & Support\r\n\r\nFor questions or support:\r\n\r\n- \ud83c\udf10 [Hasnain Shahid](https://hasnainshahidx.github.io/)\r\n- \ud83d\udce7 Email: hasnainshahid822@gmail.com\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Click and solve Cloudflare Turnstile CAPTCHA \u2014 supports both headless and GUI modes.",
"version": "0.1.4",
"project_urls": {
"Author": "https://hasnainshahidx.github.io/",
"Homepage": "https://github.com/hasnainshahidx/turnstile_solver/",
"Repository": "https://github.com/hasnainshahidx/turnstile_solver/"
},
"split_keywords": [
"captcha-solver",
" turnstile-solver",
" cloudflare-bypass",
" solver",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c717768b23ae43c9a5b7541119c734dc6df51829fb0473e3f5ddc80eddac8478",
"md5": "ece5fd3332c46c95641cf0339189b841",
"sha256": "f3717def9a0e8dadfa5c791eacb0f2593c957c285163394ee3fc4037777c1f8c"
},
"downloads": -1,
"filename": "turnstile_solver-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ece5fd3332c46c95641cf0339189b841",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 28702,
"upload_time": "2025-08-01T00:26:30",
"upload_time_iso_8601": "2025-08-01T00:26:30.047196Z",
"url": "https://files.pythonhosted.org/packages/c7/17/768b23ae43c9a5b7541119c734dc6df51829fb0473e3f5ddc80eddac8478/turnstile_solver-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "be908faa4e2f3c7a3e5e01f8eeb0709f747dae60d585ce88be08732abd7facb1",
"md5": "4d5ea7f71b012e26b87c1255ed08d5f5",
"sha256": "90857624bd29efafa3ed3446eec1f41e62d32b73d75947fafe69ca9fa65a0d96"
},
"downloads": -1,
"filename": "turnstile_solver-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "4d5ea7f71b012e26b87c1255ed08d5f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 27668,
"upload_time": "2025-08-01T00:26:31",
"upload_time_iso_8601": "2025-08-01T00:26:31.432321Z",
"url": "https://files.pythonhosted.org/packages/be/90/8faa4e2f3c7a3e5e01f8eeb0709f747dae60d585ce88be08732abd7facb1/turnstile_solver-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 00:26:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hasnainshahidx",
"github_project": "turnstile_solver",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "opencv_python",
"specs": []
},
{
"name": "pyautogui",
"specs": []
},
{
"name": "selenium",
"specs": []
}
],
"lcname": "turnstile-solver"
}
JSON
