CAPTCHA Solving

Automatically detect and solve captchas during browser automation

Notte can automatically detect and solve captchas including reCAPTCHA v2, reCAPTCHA v3, and hCaptcha during your browser automation.

Quick Start

Enable captcha solving when creating a session:

Python

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(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:

1. Detection - Notte monitors the page for captcha elements
2. Solving - Captchas are solved automatically in the background
3. Continuation - Your automation continues seamlessly

No additional code is needed - captchas are solved automatically when encountered.

Complete Example

Python

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(
    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"]', "[e-mail]")
    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:

Python

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(
    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:

realistic_delays.py

import time

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(solve_captchas=True) as session:
    page = session.page

    # Navigate to page
    page.goto("https://example.com/protected")

    # Wait for page to load
    time.sleep(2)

    # Fill form
    page.fill('input[name="email"]', "[e-mail]")
    time.sleep(1)

    # Submit (captcha will be solved)
    page.click('button[type="submit"]')

2. Monitor for Failures

Check if captcha solving failed:

monitor_failures.py

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(solve_captchas=True) as session:
    page = session.page
    page.goto("https://example.com/protected")

    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:

headless_debug.py

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(
    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:

combine_stealth.py

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(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)
• ❌ Solve custom/proprietary captcha systems
• ❌ Bypass all bot detection (combine with stealth)

Common Issues

Issue: Captchas Not Being Solved

Possible causes:

• solve_captchas=True not set
• Captcha type not supported
• Site has additional bot detection

Solution:

ensure_requirements.py

from notte_sdk import NotteClient

client = NotteClient()

# Ensure all requirements are met
with client.Session(
    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:

timeout_handling.py

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(
    solve_captchas=True,
    idle_timeout_minutes=15,  # Longer timeout
) as session:
    pass

Testing CAPTCHA Solving

Test captcha solving on demo sites:

Python

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(
    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

Browser Types

Learn about Chrome and other browsers

Stealth Mode

Combine with anti-detection features

Proxies

Use proxies with captcha solving

Live View

Watch captcha solving in real-time