Notte can automatically detect and solve captchas including reCAPTCHA v2, reCAPTCHA v3, and hCaptcha during your browser automation.
CAPTCHA solving is only available with Firefox. You must set browser_type="firefox" to use this feature.
Quick Start
Enable captcha solving when creating a session:
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(
browser_type="firefox", # Required
solve_captchas=True
) as session:
page = session.page
page.goto("https://www.google.com/recaptcha/api2/demo")
# Captcha automatically solved
Supported CAPTCHA Types
Notte automatically detects and solves:
- ✅ reCAPTCHA v2 - Checkbox and image challenges
- ✅ reCAPTCHA v3 - Invisible captchas
- ✅ hCaptcha - Checkbox and image challenges
How It Works
When captcha solving is enabled:
- Detection - Notte monitors the page for captcha elements
- Solving - Captchas are solved automatically in the background
- Continuation - Your automation continues seamlessly
No additional code is needed - captchas are solved automatically when encountered.
Complete Example
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(
browser_type="firefox",
solve_captchas=True,
headless=False # Watch it solve captchas
) as session:
page = session.page
# Navigate to a site with captcha
page.goto("https://example.com/login")
# Fill login form
page.fill('input[name="email"]', "user@example.com")
page.fill('input[name="password"]', "password")
# Click submit - captcha will be solved automatically
page.click('button[type="submit"]')
# Wait for successful login
page.wait_for_url("**/dashboard")
print("Logged in successfully!")
Captcha + Proxies
Combine captcha solving with proxies for better success rates:
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(
browser_type="firefox",
solve_captchas=True,
proxies=True # Use residential proxies
) as session:
page = session.page
page.goto("https://example.com")
# Both captcha solving and proxies active
Best Practices
1. Use Realistic Delays
Add human-like delays before and after captcha-protected actions:
import time
# Navigate to page
page.goto("https://example.com/protected")
# Wait for page to load
time.sleep(2)
# Fill form
page.fill('input[name="email"]', "user@example.com")
time.sleep(1)
# Submit (captcha will be solved)
page.click('button[type="submit"]')
2. Monitor for Failures
Check if captcha solving failed:
try:
page.click('button[type="submit"]')
page.wait_for_url("**/success", timeout=30000) # 30 seconds
except Exception as e:
print(f"Captcha solving may have failed: {e}")
# Handle failure
3. Use Headless=False for Debugging
Watch captcha solving in action:
with client.Session(
browser_type="firefox",
solve_captchas=True,
headless=False # Opens live viewer
) as session:
# You can watch captchas being solved
pass
4. Combine with Stealth
Use stealth features for better success rates:
with client.Session(
browser_type="firefox",
solve_captchas=True,
proxies=True,
viewport_width=1920,
viewport_height=1080
) as session:
# Maximum captcha success rate
pass
Limitations
What CAPTCHA Solving Can Do:
- ✅ Solve most reCAPTCHA v2 challenges
- ✅ Solve reCAPTCHA v3 automatically
- ✅ Solve most hCaptcha challenges
- ✅ Work with residential proxies
- ✅ Work in headless and non-headless mode
What It Cannot Do:
- ❌ Solve 100% of captchas (some are unsolvable)
- ❌ Work with Chromium or Chrome (Firefox only)
- ❌ Solve custom/proprietary captcha systems
- ❌ Bypass all bot detection (combine with stealth)
Common Issues
Issue: Captchas Not Being Solved
Possible causes:
- Using Chromium/Chrome instead of Firefox
solve_captchas=True not set- Captcha type not supported
- Site has additional bot detection
Solution:
# Ensure all requirements are met
with client.Session(
browser_type="firefox", # Must be Firefox
solve_captchas=True, # Must be enabled
proxies=True # Helps with detection
) as session:
pass
Issue: Timeout Waiting for Captcha
Increase session timeout for captcha-heavy workflows:
with client.Session(
browser_type="firefox",
solve_captchas=True,
timeout_minutes=15 # Longer timeout
) as session:
pass
Testing CAPTCHA Solving
Test captcha solving on demo sites:
from notte_sdk import NotteClient
client = NotteClient()
test_sites = [
"https://www.google.com/recaptcha/api2/demo",
"https://2captcha.com/demo/recaptcha-v2",
"https://democaptcha.com/demo-form-eng/hcaptcha.html"
]
with client.Session(
browser_type="firefox",
solve_captchas=True,
headless=False
) as session:
page = session.page
for site in test_sites:
print(f"Testing {site}")
page.goto(site)
page.screenshot(path=f"captcha_test_{test_sites.index(site)}.png")
Pricing
CAPTCHA solving incurs additional costs based on the number of captchas solved. Check your plan for details.
Next Steps
