> ## 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.

# CAPTCHA Solving

> Automatically detect and solve captchas during browser automation

<Tip>
  STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).

  Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.

  Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.

  Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.

  SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
</Tip>

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

## Quick Start

Enable captcha solving when creating a session:

<CodeGroup>
  ```python Python theme={null}
  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
  ```
</CodeGroup>

## Supported CAPTCHA Types

Notte automatically detects and solves:

* ✅ **reCAPTCHA v2** - Checkbox and image challenges
* ✅ **reCAPTCHA v3** - Invisible captchas
* ✅ **hCaptcha** - Checkbox and image challenges
* ✅ **Text CAPTCHAs** - Simple "read the characters and type them" challenges
* ✅ **Image CAPTCHAs** - Visual verification 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.

## Captcha + Proxies

Combine captcha solving with proxies for better success rates:

<CodeGroup>
  ```python Python theme={null}
  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
  ```
</CodeGroup>

## Best Practices

### 1. Use Realistic Delays

Add human-like delays before and after captcha-protected actions:

{/* @sniptest testers/sessions/captcha/realistic_delays.py */}

```python realistic_delays.py theme={null}
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:

{/* @sniptest testers/sessions/captcha/monitor_failures.py */}

```python monitor_failures.py theme={null}
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:

{/* @sniptest testers/sessions/captcha/headless_debug.py */}

```python headless_debug.py theme={null}
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:

{/* @sniptest testers/sessions/captcha/combine_stealth.py */}

```python combine_stealth.py theme={null}
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
```

## Examples

### reCAPTCHA

For reCAPTCHA challenges, use the `captcha_solve` action with `captcha_type="recaptcha"`. This example comes from the [reCAPTCHA template](https://www.notte.cc/templates/captcha-bot-handling/basic-recaptcha).

{/* @sniptest testers/sessions/captcha/recaptcha_solve_action.py */}

```python recaptcha_solve_action.py theme={null}
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)
```

### 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](https://www.notte.cc/templates/captcha-bot-handling/basic-text-captcha).

{/* @sniptest testers/sessions/captcha/text_captcha_solve_action.py */}

```python text_captcha_solve_action.py theme={null}
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 reCAPTCHA v3 automatically
* ✅ Solve most hCaptcha challenges
* ✅ Solve simple text and image CAPTCHA challenges
* ✅ Work with residential proxies
* ✅ Work in headless and non-headless mode

### 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=True` not set
* Captcha type not supported
* Site has additional bot detection

**Solution:**

{/* @sniptest testers/sessions/captcha/ensure_requirements.py */}

```python ensure_requirements.py theme={null}
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:

{/* @sniptest testers/sessions/captcha/timeout_handling.py */}

```python timeout_handling.py theme={null}
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:

<CodeGroup>
  ```python Python theme={null}
  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")
  ```
</CodeGroup>

## Pricing

CAPTCHA solving incurs additional costs based on the number of captchas solved. Check your plan for details.

## Next Steps

<CardGroup cols={2}>
  <Card title="Browser Types" icon="browser" href="/features/sessions/browser-types">
    Learn about Chrome and other browsers
  </Card>

  <Card title="Stealth Mode" icon="user-secret" href="/features/sessions/stealth-mode">
    Combine with anti-detection features
  </Card>

  <Card title="Proxies" icon="network-wired" href="/features/sessions/proxies">
    Use proxies with captcha solving
  </Card>

  <Card title="Live View" icon="eye" href="/features/sessions/live-view">
    Watch captcha solving in real-time
  </Card>
</CardGroup>