{"id":26587491,"url":"https://github.com/luminati-io/bypass-captcha-with-selenium","last_synced_at":"2026-05-04T04:35:14.555Z","repository":{"id":283784000,"uuid":"951769255","full_name":"luminati-io/bypass-captcha-with-selenium","owner":"luminati-io","description":"Bypass CAPTCHAs in Selenium using Python. This guide covers stealth techniques, browser automation, and proxy integration to avoid detection.","archived":false,"fork":false,"pushed_at":"2025-03-20T09:18:46.000Z","size":201,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-22T07:02:01.926Z","etag":null,"topics":["bot-detection","captcha","captcha-solver","python","selenium"],"latest_commit_sha":null,"homepage":"https://brightdata.com/blog/web-data/bypass-captchas-with-selenium","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luminati-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-03-20T08:04:38.000Z","updated_at":"2025-03-20T09:36:26.000Z","dependencies_parsed_at":"2025-03-22T07:02:08.373Z","dependency_job_id":"0946e7f3-4177-465d-af04-7e7cc93c060f","html_url":"https://github.com/luminati-io/bypass-captcha-with-selenium","commit_stats":null,"previous_names":["luminati-io/bypass-captcha-with-selenium"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/luminati-io/bypass-captcha-with-selenium","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luminati-io%2Fbypass-captcha-with-selenium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luminati-io%2Fbypass-captcha-with-selenium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luminati-io%2Fbypass-captcha-with-selenium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luminati-io%2Fbypass-captcha-with-selenium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luminati-io","download_url":"https://codeload.github.com/luminati-io/bypass-captcha-with-selenium/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luminati-io%2Fbypass-captcha-with-selenium/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32595198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"online","status_checked_at":"2026-05-04T02:00:06.625Z","response_time":58,"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":["bot-detection","captcha","captcha-solver","python","selenium"],"created_at":"2025-03-23T12:20:06.936Z","updated_at":"2026-05-04T04:35:14.535Z","avatar_url":"https://github.com/luminati-io.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bypassing CAPTCHAs With Selenium in Python\n\n[![Promo](https://github.com/luminati-io/LinkedIn-Scraper/raw/main/Proxies%20and%20scrapers%20GitHub%20bonus%20banner.png)](https://brightdata.com/)\n\nThis guide explains how to bypass CAPTCHAs in Selenium:\n\n- [Common CAPTCHA Types](#common-captcha-types)\n- [Selenium CAPTCHA Handling: Step-By-Step Tutorial](#selenium-captcha-handling-step-by-step-tutorial)\n  - [Step #1: Create a New Python Project](#step-1-create-a-new-python-project)\n  - [Step #2: Install Selenium](#step-2-install-selenium)\n  - [Step #3: Set Up Your Selenium Script](#step-3-set-up-your-selenium-script)\n  - [Step #4: Add the Browser Automation Logic](#step-4-add-the-browser-automation-logic)\n  - [Step #5: Install the Selenium Stealth Plugin](#step-5-install-the-selenium-stealth-plugin)\n  - [Step #6: Configure the Stealth Settings to Avoid CAPTCHAs](#step-6-configure-the-stealth-settings-to-avoid-captchas)\n  - [Step #7: Repeat the Bot Detection Test](#step-7-repeat-the-bot-detection-test)\n - [What If the Above Solution Does Not Work](#what-if-the-above-solution-does-not-work)\n\n\n## What Are CAPTCHAs?\n\n\nA [**CAPTCHA**](https://brightdata.com/blog/web-data/what-is-a-captcha) (Completely Automated Public Turing test to tell Computers and Humans Apart) is used to distinguish human users from bots. It presents challenges that are easy for humans but difficult for machines. Common providers include Google reCAPTCHA, hCaptcha, and BotDetect.\n\n## Common CAPTCHA Types\n\n- **Text-based**: Enter distorted letters/numbers.  \n- **Image-based**: Identify specific objects in a grid.  \n- **Audio-based**: Type words from an audio clip.  \n- **Puzzle-based**: Solve simple puzzles (e.g., mazes).  \n\n![Text CAPTCHA example](https://github.com/luminati-io/bypass-captcha-with-selenium/blob/main/images/Text-CAPTCHA-example.png)\n\nOften, CAPTCHAs appear at the final step of form submissions:\n\n![CAPTCHA in form submission](https://github.com/luminati-io/bypass-captcha-with-selenium/blob/main/images/CAPTCHA-as-a-step-of-a-form-submission-process-example.png)\n\nThey prevent automated bots from completing actions. While CAPTCHA-solving services exist, hard-coded CAPTCHAs are rare due to **poor user experience**.\n\nCAPTCHAs are part of broader security measures like **Web Application Firewalls (WAFs)**:\n\n![Web Application Firewall](https://github.com/luminati-io/bypass-captcha-with-selenium/blob/main/images/Example-of-a-Web-Application-Firewall-1024x488.png)\n\nThese systems trigger CAPTCHAs when detecting suspicious activity. To bypass them, bots must **mimic human behavior**, which requires frequent script updates. \n\n## Selenium CAPTCHA Handling: Step-By-Step Tutorial\n\nOne of the best tools to mimic human behavior while controlling a browser for is [Selenium](https://www.selenium.dev/), a popular browser automation library. Let's learn how to avoid CAPTCHAs in Selenium using a Python script.\n\n### Step #1: Create a New Python Project\n\nYou will need Python 3 and Crhome installed locally to follow this guide.\n\nIf you already have a Selenium web scraping or testing script, skip the first three steps. Otherwise, create a folder for your Selenium CAPTCHA bypass demo project and navigate to it in the terminal window:\n\n```bash\nmkdir selenium_demo\n\ncd selenium_demo\n```\n\nNext, add a new [Python virtual environment](https://docs.python.org/3/library/venv.html) inside it:\n\n```bash\npython -m venv venv\n```\n\nOpen the project’s folder in your favorite Python IDE and create a new file named `script.py`.\n\n### Step #2: Install Selenium\n\nActivate the [Python virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#activate-a-virtual-environment).\n\nOn Windows:\n\n```powershell\nvenv\\Scripts\\activate\n```\n\nOn Linux or macOS:\n\n```bash\nsource venv/bin/activate\n```\n\nInstall Selenium:\n\n```bash\npip install selenium\n```\n\n### Step #3: Set Up Your Selenium Script\n\nImport Selenium by adding the following line to `script.py`:\n\n```python\nfrom selenium import webdriver\n```\n\nCreate a [`ChromeOptions`](https://selenium-python.readthedocs.io/api.html#module-selenium.webdriver.chrome.options) object to configure Chrome to start in headless mode:\n\n```python\noptions = webdriver.ChromeOptions()\n\noptions.add_argument(\"--headless\")\n```\n\nInitialize a [Chrome WebDriver](https://selenium-python.readthedocs.io/api.html#module-selenium.webdriver.chrome.webdriver) instance with these options, and finally close it with `quit()`. This is what your current `script.py` file should currently look like:\n\n```python\nfrom selenium import webdriver\n\n# configure Chrome to start in headless mode\n\noptions = webdriver.ChromeOptions()\n\noptions.add_argument(\"--headless\")\n\n# start a Chrome instance\n\ndriver = webdriver.Chrome(options=options)\n\n# browser automation logic...\n\n# close the browser and release its resources\n\ndriver.quit()\n```\n\nThe above script launches a new Chrome instance in headless mode before closing the browser.\n\n### Step #4: Add the Browser Automation Logic\n\nTo test Selenium CAPTCHA bypass logic, the script will connect to **[bot.sannysoft.com](https://bot.sannysoft.com/)** and capture a screenshot. This page runs various tests to detect whether the visitor is a human or a bot. When accessed via a standard browser, all tests pass.\n\nUse the [`get()`](https://selenium-python.readthedocs.io/api.html#selenium.webdriver.remote.webdriver.WebDriver.get) method to instruct Chrome to visit the target page:\n\n```python\ndriver.get(\"https://bot.sannysoft.com/\")\n```\n\nSelenium does not provide a built-in function to capture a full-page screenshot. As a workaround, adjust the browser window size to match the `\u003cbody\u003e` dimensions before taking a screenshot.\n\n\n```python\n# get the body width and height\n\nfull_width = driver.execute_script(\"return document.body.parentNode.scrollWidth\")\n\nfull_height = driver.execute_script(\"return document.body.parentNode.scrollHeight\")\n\n# set the browser window to the body width and height\n\ndriver.set_window_size(full_width, full_height)\n\n# take a screenshot of the entire page\n\ndriver.save_screenshot(\"screenshot.png\")\n\n# restore the original window size\n\ndriver.set_window_size(original_size[\"width\"], original_size[\"height\"])\n```\n\nThe above trick will do, and `screenshot.png` will contain the screenshot of the entire page.\n\nPut it all together, and you will have the following logic:\n\n```python\nfrom selenium import webdriver\n\n# configure Chrome to start in headless mode\n\noptions = webdriver.ChromeOptions()\n\noptions.add_argument(\"--headless\")\n\n# start a Chrome instance\n\ndriver = webdriver.Chrome(options=options)\n\n# connect to the target page\n\ndriver.get(\"https://bot.sannysoft.com/\")\n\n# get the current window size\n\noriginal_size = driver.get_window_size()\n\n# get the body width and height\n\nfull_width = driver.execute_script(\"return document.body.parentNode.scrollWidth\")\n\nfull_height = driver.execute_script(\"return document.body.parentNode.scrollHeight\")\n\n# set the browser window to the body width and height\n\ndriver.set_window_size(full_width, full_height)\n\n# take a screenshot of the entire page\n\ndriver.save_screenshot(\"screenshot.png\")\n\n# restore the original window size\n\ndriver.set_window_size(original_size[\"width\"], original_size[\"height\"])\n\n# close the browser and release its resources\n\ndriver.quit()\n```\n\nLaunch the `script.py` file above with this command:\n\n```bash\npython script.py\n```\n\nThe script launches a **Chromium instance in headless mode**, navigates to the target page, captures a screenshot, and then closes the browser. After execution, a `screenshot.png` file will appear in the project root folder.\n\n![screenshot.png file example](https://github.com/luminati-io/bypass-captcha-with-selenium/blob/main/images/screenshot.png-file-example-206x1024.png)\n\nAs shown by the red boxes, Chrome in headless mode fails multiple detection tests. This means your script is likely flagged as a bot, leading to CAPTCHA challenges on protected sites.\n\nTo avoid detection and prevent CAPTCHAs, use the Stealth plugin.\n\n### Step #5: Install the Selenium Stealth Plugin\n\n[Selenium Stealth](https://github.com/diprajpatra/selenium-stealth) is a Python package that reduces the likelihood of Chrome/Chromium being detected as a bot when controlled by Selenium. It helps bypass anti-bot detection by modifying browser properties to prevent automation leaks.\n\nSelenium Stealth alters various browser attributes to mimic human behavior and avoid detection. It functions similarly to Puppeteer Stealth but is designed for Selenium.\n\nInstall Selenium Stealth via `pip`:\n\n```sh\npip install selenium-stealth\n```\n\nThen, import the library by adding this line to the `script.py` file:\n\n```python\nfrom selenium_stealth import stealth\n```\n\n### Step #6: Configure the Stealth Settings to Avoid CAPTCHAs\n\nTo register Selenium Stealth and configure the Chrome WebDriver to avoid CAPTCHAs, call the `stealth()` function:\n\n```python\nstealth(\n\ndriver,\n\nuser_agent=\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36\",\n\nlanguages=[\"en-US\", \"en\"],\n\nvendor=\"Google Inc.\",\n\nplatform=\"Win32\",\n\nwebgl_vendor=\"Intel Inc.\",\n\nrenderer=\"Intel Iris OpenGL Engine\",\n\nfix_hairline=True,\n\n)\n```\n\nSet the function arguments as needed, but note that the values above are sufficient to bypass most anti-bot defenses.\n\nWith these settings, the Selenium-controlled browser will mimic a real user’s browser.\n\n### Step #7: Repeat the Bot Detection Test\n\nBelow is the final `script.js` file:\n\n```python\nfrom selenium import webdriver\n\nfrom selenium_stealth import stealth\n\n# configure Chrome to start in headless mode\n\noptions = webdriver.ChromeOptions()\n\noptions.add_argument(\"--headless\")\n\n# start a Chrome instance\n\ndriver = webdriver.Chrome(options=options)\n\n# configure the WebDriver to avoid bot detection\n\n# with Selenium Stealth\n\nstealth(\n\ndriver,\n\nuser_agent=\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36\",\n\nlanguages=[\"en-US\", \"en\"],\n\nvendor=\"Google Inc.\",\n\nplatform=\"Win32\",\n\nwebgl_vendor=\"Intel Inc.\",\n\nrenderer=\"Intel Iris OpenGL Engine\",\n\nfix_hairline=True,\n\n)\n\n# connect to the target page\n\ndriver.get(\"https://bot.sannysoft.com/\")\n\n# get the current window size\n\noriginal_size = driver.get_window_size()\n\n# get the body width and height\n\nfull_width = driver.execute_script(\"return document.body.parentNode.scrollWidth\")\n\nfull_height = driver.execute_script(\"return document.body.parentNode.scrollHeight\")\n\n# set the browser window to the body width and height\n\ndriver.set_window_size(full_width, full_height)\n\n# take a screenshot of the entire page\n\ndriver.save_screenshot(\"screenshot.png\")\n\n# restore the original window size\n\ndriver.set_window_size(original_size[\"width\"], original_size[\"height\"])\n\n# close the browser and release its resources\n\ndriver.quit()\n```\n\nExecute the bypass CAPTCHA Selenium Python script again:\n\n```bash\npython script.py\n```\n\nTake a look at `screenshot.png`, and you will notice that all bot detection tests have been passed:\n\n![All bot detection tests passed on the new screenshot.png](https://github.com/luminati-io/bypass-captcha-with-selenium/blob/main/images/All-bot-detction-tests-passed-on-the-new-screenshot-249x1024.png)\n\n## What If the Above Solution Does Not Work?\n\nAnti-bot systems don’t just analyze browser settings—IP reputation is crucial. Simply switching IPs with a free library won’t work; you need Selenium proxy integration.\n\nEven with an optimally configured browser, CAPTCHAs may still appear. For basic reCAPTCHA v2 challenges, you can try [selenium-recaptcha-solver](https://pypi.org/project/selenium-recaptcha/), but these libraries are outdated and limited.\n\nBasic methods fail against complex anti-bot systems like Cloudflare. For a robust solution, use Bright Data’s web scraping tools, which support  reCAPTCHA, hCaptcha, px_captcha, SimpleCaptcha, GeeTest, FunCaptcha, Cloudflare Turnstile, AWS WAF Captcha, KeyCAPTCHA, and more.\n\n[Bright Data’s CAPTCHA Solver](https://brightdata.com/products/web-unlocker/captcha-solver) works with any HTTP client or browser automation tool, including Selenium.\n\n## Conclusion\n\nThanks to the Selenium Stealth library, you can override the default configurations of Chrome to limit bot detection. However, this approach is not a definitive solution. Advanced bot detection tools will still be able to block you. The real solution is to connect to the target site via an unblocking API that can return the CAPTCHA-free HTML of any web page.\n\nOne of such solutions is [Web Unlocker](https://brightdata.com/products/web-unlocker), a scraping API that automatically rotates your exit IP with each request via proxy integration and handles browser fingerprinting, automatic retries, and CAPTCHA resolution for you. Dealing with CAPTCHAs has never been easier!\n\nSign up now and start your free trial.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluminati-io%2Fbypass-captcha-with-selenium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluminati-io%2Fbypass-captcha-with-selenium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluminati-io%2Fbypass-captcha-with-selenium/lists"}