This example demonstrates how to solve hCaptcha step-by-step, from start to finish, using the SolveCaptcha Python SDK. It also shows how to configure and use proxy servers for solving captchas.
This repository contains an example of bypassing hCaptcha using the SolveCaptcha Python SDK and SeleniumBase.
This repository includes a single script for captcha bypass:
- hcaptcha_solve_seleniumbase_proxy.py — an end-to-end example that:
- Uses the SolveCaptcha API to solve hCaptcha on democaptcha.com.
- Optionally supports proxy configuration via
.envfile. - Controls a Chrome browser using SeleniumBase.
- Inserts the hCaptcha token and submits the form.
⚠️ This recording is shown at an accelerated speed for demonstration purposes. In real usage the captcha-solving process takes longer, so please wait while the service returns a result.
- Python 3.x
- SeleniumBase
- SolveCaptcha Python SDK
- python-dotenv (for
.envloading)
⚠️ The SolveCaptcha SDK is not published to PyPI. Install it directly from GitHub.
pip install seleniumbase python-dotenv git+https://github.com/solvercaptcha/solvecaptcha-python.gitCreate a .env file in the root directory with the following content:
API_KEY=YOUR_API_KEY
USE_PROXY=False
PROXY_HOST=host
PROXY_PORT=port
PROXY_USER=username
PROXY_PASS=passwordRun the script:
python hcaptcha_solve_seleniumbase_proxy.pyConsole output will guide you through the steps:
- Initialize SDK.
- Solve the captcha.
- Launch browser.
- Insert token.
- Click submit.
- Check for success message.
To use this example on your own site, you'll need to update the captcha configuration:
SITEKEY = "your-site-key"
PAGE_URL = "https://your-site.com/page-with-hcaptcha"Also, be sure to specify your SolveCaptcha API key in the .env file:
API_KEY=YOUR_API_KEY- The way the captcha token is applied to the page may differ depending on how hCaptcha is implemented on your website.
- Update the JavaScript execution logic if necessary to match your site's requirements.
- Finally, review or adjust any browser actions after token insertion — such as button clicks, custom validations, or post-submit checks — so they reflect the actual behavior of your form.
- Browser runs in non-headless mode by default.
- Proxy usage is optional and controlled via
.env. - Target page: https://democaptcha.com/demo-form-eng/hcaptcha.html
Selenium Python Proxy
Using a proxy when solving hCaptcha is necessary in the following cases:
- IP Address Masking: A proxy allows you to mask your real IP address, which helps avoid blocks when too many requests originate from a single address.
- Consistent Request Origin: For accurate captcha solving, it is important that all requests (both for loading the page via Selenium and for sending the captcha-solving task via the API) come from the same IP address. Therefore, it is recommended to use the same proxy for both operations.
- Stable Operation: Proxies can ensure stable script performance if the primary IP is blocked or restricted due to geolocation issues.
Recommendation: Use identical proxy settings for both page loading and captcha solving to guarantee that both requests originate from the same source (one IP address).
This project is provided for demonstration and testing purposes only. It is not intended to encourage or promote the circumvention of captcha systems on websites without proper authorization.
Captcha systems are often used to protect websites from abuse, and bypassing them may be against the terms of service of the target website, and/or local laws or regulations in your region.
Before using this code on any third-party site, you must ensure that your actions are compliant with the site's rules and applicable legal requirements.
You are solely responsible for how you use this code.
We have also compiled the most common issues encountered when solving hCaptcha into a separate document, FAQ.md. In it, you will find answers to frequently asked questions.