{"id":51215756,"url":"https://github.com/hasnainshahidx/turnstile_solver","last_synced_at":"2026-06-28T04:00:59.319Z","repository":{"id":307190960,"uuid":"1026466801","full_name":"hasnainshahidx/turnstile_solver","owner":"hasnainshahidx","description":"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.","archived":false,"fork":false,"pushed_at":"2026-01-13T13:28:07.000Z","size":34,"stargazers_count":43,"open_issues_count":0,"forks_count":12,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T16:25:31.218Z","etag":null,"topics":["automation-test","cloudflare-bypass","cloudflare-solver","hasnainshahidx","helpers-library","python-library","python-package","selenium","turnstile-bypass","turnstile-solver","web-automation"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/turnstile-solver/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hasnainshahidx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-26T00:21:54.000Z","updated_at":"2026-01-13T13:28:11.000Z","dependencies_parsed_at":"2025-07-30T00:23:56.173Z","dependency_job_id":"d38f53ec-986c-4f9a-ae24-14de22480b80","html_url":"https://github.com/hasnainshahidx/turnstile_solver","commit_stats":null,"previous_names":["hasnainshahidx/turnstile_solver"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hasnainshahidx/turnstile_solver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasnainshahidx%2Fturnstile_solver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasnainshahidx%2Fturnstile_solver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasnainshahidx%2Fturnstile_solver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasnainshahidx%2Fturnstile_solver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hasnainshahidx","download_url":"https://codeload.github.com/hasnainshahidx/turnstile_solver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasnainshahidx%2Fturnstile_solver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34876271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation-test","cloudflare-bypass","cloudflare-solver","hasnainshahidx","helpers-library","python-library","python-package","selenium","turnstile-bypass","turnstile-solver","web-automation"],"created_at":"2026-06-28T04:00:37.508Z","updated_at":"2026-06-28T04:00:59.284Z","avatar_url":"https://github.com/hasnainshahidx.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# turnstile_solver\n\n**Click and solve Cloudflare Turnstile CAPTCHA — supports both headless and GUI modes.**\n\n---\n\n## 🔍 Features\n\n- ✅ Supports **embedded** and **challenge page** Turnstile variants  \n- ✅ Uses **Chrome DevTools Protocol** for DOM access and interaction  \n- ✅ Human-like mouse movement using CDP or **PyAutoGUI**  \n- ✅ Works in both **headless** and **visible** Chrome modes  \n- ✅ Uses template-based **image matching** to locate the checkbox  \n- ✅ Optional verification detection via **MutationObserver**\n\n---\n\n## ⚠️ Disclaimer\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.\n\n---\n\n## 📦 Installation\n\n```bash\npip install turnstile_solver\n```\n\n---\n\n## ⚙️ Requirements\n\n- Python 3.7+=\n- NumPy\n- OpenCV (`opencv-python`)\n- PyAutoGUI (optional, for physical mouse clicks)\n- Selenium\n\n---\n\n## 🚀 Usage Example\n\n### ✅ Option 1: One-shot `solve()` function\n\nUse this when you want a simple, one-time solve without worrying about managing state.\n\n```python\nfrom seleniumbase import Driver\nfrom turnstile_solver import solve\n\ndriver = Driver(uc=True, headless=True)\ndriver.get(\"https://gitlab.com/users/sign_in\")\n\nsuccess = solve(\n    driver,\n    detect_timeout=5,    # Timeout for detecting the Turnstile widget\n    solve_timeout=30,    # Timeout for solving the Turnstile challenge\n    interval=1,          # Interval (in seconds) between retries/checks\n    verify=True,         # Whether to verify after solving\n    click_method=\"cdp\",  # Use \"cdp\" or \"pyautogui\" for clicking\n    theme=\"auto\",        # Options: \"auto\", \"dark\", or \"light\"\n    grayscale=False,     # Whether to convert image to grayscale before solving\n    thresh=0.8,          # Matching threshold for image verification\n    enable_logging=True  # Enable debug/info logging\n)\n\nprint(\"Solved:\", success)\n```\n\n---\n\n### ✅ Option 2: Reusable `Solver` class\n\nUse this when solving Turnstile multiple times or when you want better performance and state control.\n\n```python\nfrom seleniumbase import Driver\nfrom turnstile_solver import Solver\n\ndriver = Driver(uc=True, headless=True)\n\nsolver = Solver(driver, enable_logging=True, click_method='pyautogui')\n\ndriver.get(\"https://gitlab.com/users/sing_up\")\nif solver.detect(timeout= 5, interval=1):\n    result = solver.solve(verify=True, timeout=60, interval=1)\n    print(\"result\")\n\ndriver.get(\"https://2captcha.com/demo/cloudflare-turnstile-challenge\")\nif solver.detect(timeout= 5, interval=1):\n    result = solver.solve(timeout= 30, interval= 1, verify= False)\n    print(\"result\")\n\n# Stops script injection on future navigations; you can still call .solve() or .detect() again if needed\nsolver.cleanup()\n```\n\n---\n\n### 🔍 Parameter Reference\n\n| Parameter         | Type                                | Description |\n|------------------|-------------------------------------|-------------|\n| `driver`          | `WebDriver`                         | Selenium driver (must be on a page with Turnstile). |\n| `detect_timeout` / `solve_timeout` / `timeout` | `int`  | Max time (in seconds) to try detecting or solving. |\n| `interval`        | `float`                             | Delay between retries (in seconds). Default: `1.0` |\n| `verify`          | `bool`                              | If `True`, waits for verification. Otherwise just clicks. |\n| `click_method`    | `\"cdp\"` \\| `\"pyautogui\"`            | `'cdp'` (works in headless) or `'pyautogui'` (GUI only). |\n| `theme`           | `\"auto\"` \\| `\"dark\"` \\| `\"light\"`   | Match Turnstile theme for template matching. |\n| `grayscale`       | `bool`                              | Use grayscale for matching (faster). |\n| `thresh`          | `float`                             | Confidence threshold (0–1). Default: `0.8` |\n| `enable_logging`  | `bool`                              | Print debug logs to console. |\n\n---\n\n### 🔁 Which One Should I Use?\n\n| Scenario                             | Use               |\n|--------------------------------------|-------------------|\n| Quick one-time solve                 | `solve()`         |\n| Multiple Turnstiles on same session  | `Solver` class    |\n| Full control / performance tuning    | `Solver` class    |\n| Script or CLI use                    | `solve()`         |\n\n---\n\n## Limitations\n\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:\n\n- **CDP (Chrome DevTools Protocol)** clicks are faster and work in headless mode, but they are generally **less trusted** by Cloudflare.\n- **PyAutoGUI** simulates **real human mouse movements**, making clicks more realistic and harder to detect, **but it only works in GUI mode**.\n\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.\n\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.\n\n---\n\n## 📜 License\n\nMIT License\n\n---\n\n## 💬 Feedback or Contributions\n\nFound a bug or have a suggestion?  \nFeel free to [open an issue](https://github.com/hasnainshahidx/turnstile_solver/issues) or submit a pull request.  \nContributions are welcome and appreciated!\n\n## 🙏 Note from the Author\n\nThis is my first open-source project\nAs a new developer, I'm continuously learning—so there might be imperfections or areas for improvement.  \nAny feedback, suggestions, or contributions are more than welcome to help make this project better!\n\n## 📬 Contact \u0026 Support\n\nFor questions or support:\n\n- 🌐 [Hasnain Shahid](https://hasnainshahidx.github.io/)\n- 📧 Email: hasnainshahid822@gmail.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhasnainshahidx%2Fturnstile_solver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhasnainshahidx%2Fturnstile_solver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhasnainshahidx%2Fturnstile_solver/lists"}