Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.notte.cc/llms.txt

Use this file to discover all available pages before exploring further.

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

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"]', "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(
    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"]', "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:
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: 
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