A robust Python library for solving captchas through browser automation, providing seamless integration between web captcha services and Python applications.
- 🌐 Browser Integration: Automatically opens captchas in your browser for solving
- 🔄 Real-time Communication: Handles browser-server communication seamlessly
- 🎯 Multiple Captcha Types: Supports ReCaptcha v2, ReCaptcha v3, hCaptcha, and Cloudflare Turnstile
- ⚡ Threaded HTTP Server: Non-blocking server for handling multiple requests
- 🛡️ Secure: Local-only server with automatic cleanup
- 🎨 Easy API: Simple, intuitive interface for developers
pip install browser-captcha-solverfrom browser_captcha_solver import CaptchaSolver
# Create solver and start server
with CaptchaSolver() as solver:
# Create a ReCaptcha challenge
challenge = solver.create_challenge(
challenge_type="RecaptchaV2Challenge",
site_key="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI", # Test key
site_domain="example.com",
host="example.com",
explain="Please solve this captcha to continue",
timeout=300
)
# Solve the challenge (opens browser automatically)
result = solver.solve_challenge(challenge, timeout=300)
if result:
print(f"Success! Token: {result}")
else:
print("Failed to solve captcha")ReCaptcha v3 provides invisible verification with risk scoring. This implementation requires explicit user interaction for security and compliance.
from browser_captcha_solver import CaptchaSolver
with CaptchaSolver() as solver:
# Create a ReCaptcha v3 challenge
challenge = solver.create_challenge(
challenge_type="RecaptchaV3Challenge",
site_key="your-recaptcha-v3-site-key", # Get from Google reCAPTCHA Admin
site_domain="your-domain.com",
host="your-domain.com",
secure_token="homepage", # Action name (login, register, etc.)
timeout=300
)
# Solve the challenge - user clicks "Execute ReCaptcha v3" button
result = solver.solve_challenge(challenge, timeout=300)
if result:
print(f"reCAPTCHA v3 token: {result}")
# Use token for server-side verification to get risk score
else:
print("Failed to execute reCAPTCHA v3")from browser_captcha_solver import CaptchaSolver
def on_captcha_solved(challenge):
print(f"Captcha {challenge.id} solved!")
print(f"Token: {challenge.result}")
with CaptchaSolver(port=8080) as solver:
challenge = solver.create_challenge(
challenge_type="HCaptchaChallenge",
site_key="10000000-ffff-ffff-ffff-000000000001", # Test key
site_domain="example.com",
host="example.com"
)
# Solve with callback
result = solver.solve_challenge(
challenge,
timeout=300,
callback=on_captcha_solved
)The package also provides CLI tools for testing:
# Test ReCaptcha v3 with your site key
python recaptcha_v3_cli.py --site-key YOUR_SITE_KEY --domain localhost --action test
# Run examples
python recaptcha_v3_example.py
# Quick functionality test
python test_recaptcha_v3.pyTraditional CLI (if available):
# Start the server
browser-captcha-solver start --port 8080
# Test ReCaptcha solving
browser-captcha-solver test --type recaptchaMain class for managing captcha challenges and browser communication.
CaptchaSolver(port=0, browser_command=None)port(int): HTTP server port (0 for auto-select)browser_command(str, optional): Custom browser command
Creates a new captcha challenge.
Parameters:
challenge_type(str): Type of captcha ("RecaptchaV2Challenge", "HCaptchaChallenge")site_key(str): Site key for the captcha servicesite_domain(str): Domain where the captcha will be solvedhost(str): Host identifier for the challenge**kwargs: Additional parameters (timeout, explain, type_id, etc.)
Returns: CaptchaChallenge object
Solves a captcha challenge by opening it in the browser.
Parameters:
challenge(CaptchaChallenge): The challenge to solvetimeout(int, optional): Timeout in secondscallback(callable, optional): Callback function when solved
Returns: Solution token (str) or None if failed
Returns a list of active challenges.
Returns: List of CaptchaJob objects
Removes expired challenges from memory.
Represents a captcha challenge.
id(str): Unique challenge identifierchallenge_type(str): Type of captchasite_key(str): Site key for the captcha servicesite_domain(str): Domain for the challengehost(str): Host identifiertimeout(int): Timeout in secondscreated(datetime): Creation timestampsolved(bool): Whether the challenge is solvedresult(str): Solution token
get_remaining_timeout(): Returns remaining timeout in secondsis_expired(): Returns True if the challenge has expired
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Application │◄──►│ CaptchaSolver │◄──►│ HTTP Server │
│ (Your Code) │ │ │ │ (Port 8080) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
▲ ▲
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Challenge Store │ │ Web Browser │
│ (In Memory) │ │ (User Opens) │
└─────────────────┘ └─────────────────┘
challenge = solver.create_challenge(
challenge_type="RecaptchaV2Challenge",
site_key="your-recaptcha-site-key",
site_domain="example.com",
host="example.com"
)challenge = solver.create_challenge(
challenge_type="RecaptchaV3Challenge",
site_key="your-recaptcha-v3-site-key",
site_domain="example.com",
host="example.com",
secure_token="homepage" # Action name for this challenge
)Note: ReCaptcha v3 requires explicit user interaction in this implementation. The user needs to click a button to execute the challenge. The returned token contains a risk score (available only during server-side verification).
challenge = solver.create_challenge(
challenge_type="HCaptchaChallenge",
site_key="your-hcaptcha-site-key",
site_domain="example.com",
host="example.com"
)challenge = solver.create_challenge(
challenge_type="TurnstileChallenge",
site_key="your-turnstile-site-key",
site_domain="example.com",
host="example.com"
)challenge = solver.create_challenge(
challenge_type="ManualChallenge",
site_key="",
site_domain="example.com",
host="example.com",
explain="Please solve the captcha shown in the image"
)from browser_captcha_solver import CaptchaSolver
import requests
def scrape_with_captcha():
session = requests.Session()
# Detect captcha on page
response = session.get("https://example.com/protected")
if "recaptcha" in response.text.lower():
# Extract site key from HTML
site_key = extract_site_key(response.text)
# Solve captcha
with CaptchaSolver() as solver:
challenge = solver.create_challenge(
challenge_type="RecaptchaV2Challenge",
site_key=site_key,
site_domain="example.com",
host="example.com"
)
token = solver.solve_challenge(challenge)
if token:
# Submit with captcha token
data = {"g-recaptcha-response": token}
response = session.post("https://example.com/submit", data=data)
return response
return Nonefrom browser_captcha_solver import CaptchaSolver
def process_multiple_captchas():
with CaptchaSolver() as solver:
challenges = []
# Create multiple challenges
for i in range(3):
challenge = solver.create_challenge(
challenge_type="RecaptchaV2Challenge",
site_key="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
site_domain="example.com",
host=f"host-{i}",
timeout=300
)
challenges.append(challenge)
# Solve them sequentially
results = []
for challenge in challenges:
result = solver.solve_challenge(challenge, timeout=120)
results.append(result)
return resultsfrom browser_captcha_solver import CaptchaSolver
try:
with CaptchaSolver() as solver:
challenge = solver.create_challenge(
challenge_type="RecaptchaV2Challenge",
site_key="invalid-key",
site_domain="example.com",
host="example.com"
)
result = solver.solve_challenge(challenge, timeout=60)
if not result:
print("Captcha solving failed or timed out")
except Exception as e:
print(f"Error: {e}")# Clone the repository
git clone https://github.com/xAffan/browser-captcha-solver.git
cd browser-captcha-solver
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black .
# Type checking
mypy browser_captcha_solver/# Build the package
python -m build
# Upload to PyPI (requires authentication)
twine upload dist/*- Python 3.8+
- requests >= 2.25.0
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
If you encounter any issues or have questions, please file an issue on the GitHub repository.