CAPTCHA Solving

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

Notte can automatically detect and solve captchas including reCAPTCHA v2, hCaptcha, Cloudflare Turnstile, press-and-hold challenges, and simple text challenges during your browser automation. Captcha solving is on by default (solve_captchas=True).

Quick Start

Captcha solving is enabled by default. You can set it explicitly 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
✅ hCaptcha - Checkbox and image challenges
✅ Cloudflare Turnstile
✅ Press-and-hold challenges
✅ Text CAPTCHAs - Simple “read the characters and type them” 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.

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 the Live Viewer for Debugging

Watch captcha solving in action:

headless_debug.py

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(
    solve_captchas=True,
    open_viewer=True,
) as session:
    # You can watch captchas being solved
    pass

4. Combine with Stealth

Use stealth features for better success rates:

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

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const session = client.Session({
  solve_captchas: true,
  proxies: true,
  viewport_width: 1920,
  viewport_height: 1080,
});
await session.use(async () => {
  // Maximum captcha success rate
});

Examples

reCAPTCHA

For reCAPTCHA challenges, use the captcha_solve action with captcha_type="recaptcha". This example comes from the reCAPTCHA template.

recaptcha_solve_action.py

from notte_sdk import NotteClient

DEMO_URL = "https://nopecha.com/captcha/recaptcha#easy"
client = NotteClient()

with client.Session(solve_captchas=True, proxies=True, open_viewer=True) as session:
    session.execute(type="goto", url=DEMO_URL)

    result = session.execute(
        type="captcha_solve",
        captcha_type="recaptcha",
        raise_on_failure=False,
    )

    if not result.success:
        raise RuntimeError(f"reCAPTCHA solve failed: {result.message}")

    session.execute(type="wait", time_ms=2000)

Waiting for a solve in Python

The Python SDK polls one ongoing solve through short HTTP requests. Repeated captcha_solve calls join that solve or return its completed result. Configure the total wait separately from ordinary action timeouts:

client = notte.NotteClient(captcha_timeout_seconds=180)
with client.Session(solve_captchas=True) as session:
    session.execute(type="goto", url="https://www.google.com/recaptcha/api2/demo")
    session.execute(type="captcha_solve", captcha_type="recaptcha")

The default CAPTCHA wait is three minutes. A terminal solver failure, page change, or expired wait budget follows the usual raise_on_failure behavior. Polling does not restart the solve or extend the session’s maximum lifetime. SDK actions blocked before execution wait for the CAPTCHA and then retry. If an action already executed and triggered a CAPTCHA, the SDK waits without replaying it. This coordination applies to Python SDK actions; direct Playwright/CDP calls do not participate. It requires a backend version that supports CAPTCHA polling.

Text CAPTCHAs

Text CAPTCHAs are the old-school challenges that show distorted letters, numbers, or a short phrase and ask the user to type the answer into a field. For these challenges, use captcha_type="text". This example comes from the text CAPTCHA template.

text_captcha_solve_action.py

from notte_sdk import NotteClient

DEMO_URL = "https://captcha.com/demos/features/captcha-demo.aspx#"
VALIDATE_SELECTOR = 'internal:role=button[name="Validate"i]'
client = NotteClient()

with client.Session(solve_captchas=True, proxies=True, open_viewer=True) as session:
    session.execute(type="goto", url=DEMO_URL)

    result = session.execute(
        type="captcha_solve",
        captcha_type="text",
        raise_on_failure=False,
    )

    if not result.success:
        raise RuntimeError(f"Text CAPTCHA solve failed: {result.message}")

    session.execute(type="click", selector=VALIDATE_SELECTOR)

Limitations

What CAPTCHA Solving Can Do:

✅ Solve most reCAPTCHA v2 challenges
✅ Solve most hCaptcha challenges
✅ Solve Cloudflare Turnstile and press-and-hold challenges
✅ Solve simple text CAPTCHA challenges
✅ Work with residential proxies
✅ Work in remote browser sessions

What It Cannot Do:

❌ Solve 100% of captchas (some are unsolvable)
❌ Reliably solve heavily distorted or ambiguous text challenges
❌ Solve custom/proprietary captcha systems
❌ Bypass all bot detection (combine with stealth)

Common Issues

Issue: Captchas Not Being Solved

Possible causes:

solve_captchas was set to False
Captcha type not supported
Site has additional bot detection

Solution:

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

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const session = client.Session({
  solve_captchas: true, // Must be enabled
  proxies: true, // Helps with detection
});
await session.use(async () => {
  // Use your session here
});

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,
    open_viewer=True
) 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")

Next Steps

Session Configuration

All session configuration options

Stealth Mode

Combine with anti-detection features

Proxies

Use proxies with captcha solving

Live View

Watch captcha solving in real-time

Getting Started

Sessions

Authentication

Functions

Web API

Guides

CAPTCHA Solving

Quick Start

Supported CAPTCHA Types

How It Works

Captcha + Proxies

Best Practices

1. Use Realistic Delays

2. Monitor for Failures

3. Use the Live Viewer for Debugging

4. Combine with Stealth

Examples

reCAPTCHA

Waiting for a solve in Python

Text CAPTCHAs

Limitations

What CAPTCHA Solving Can Do:

What It Cannot Do:

Common Issues

Issue: Captchas Not Being Solved

Issue: Timeout Waiting for Captcha

Testing CAPTCHA Solving

Next Steps

Session Configuration

Stealth Mode

Proxies

Live View

​Quick Start

​Supported CAPTCHA Types

​How It Works

​Captcha + Proxies

​Best Practices

​1. Use Realistic Delays

​2. Monitor for Failures

​3. Use the Live Viewer for Debugging

​4. Combine with Stealth

​Examples

​reCAPTCHA

​Waiting for a solve in Python

​Text CAPTCHAs

​Limitations

​What CAPTCHA Solving Can Do:

​What It Cannot Do:

​Common Issues

​Issue: Captchas Not Being Solved

​Issue: Timeout Waiting for Captcha

​Testing CAPTCHA Solving

​Next Steps

Session Configuration

Stealth Mode

Proxies

Live View

Quick Start

Supported CAPTCHA Types

How It Works

Captcha + Proxies

Best Practices

1. Use Realistic Delays

2. Monitor for Failures

3. Use the Live Viewer for Debugging

4. Combine with Stealth

Examples

reCAPTCHA

Waiting for a solve in Python

Text CAPTCHAs

Limitations

What CAPTCHA Solving Can Do:

What It Cannot Do:

Common Issues

Issue: Captchas Not Being Solved

Issue: Timeout Waiting for Captcha

Testing CAPTCHA Solving

Next Steps