> ## Documentation Index
> Fetch the complete documentation index at: https://notte-experiment-visibility-md-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<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

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

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

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

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

{/* @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.md">
    Learn about Chrome and other browsers
  </Card>

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

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

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