How to bypass captcha using Python

Introduction

Need to add captcha solving to your Python script? The official 2captcha-python library is the fastest and most reliable way to integrate the 2Captcha API without writing HTTP requests manually.

In this guide, we will explain why you should choose this module, how to connect it in a minute, and what possibilities it opens for automating any task.

General Information

2captcha-python is the official Python client for the 2Captcha API. The library provides a simple object-oriented interface for sending recognition tasks and getting results.

Why You Should Use This Module

• Single interface for all captcha types - no need to remember different endpoints and parameters, the library abstracts all the complexity
• Full async/await support - async calls without blocking, ideal for high-load scripts
• Flexible configuration - set timeouts, polling intervals, callback notifications for your scenario
• Built-in error handling - clear exceptions instead of raw server responses
• Proxy support out of the box - pass proxies right in the captcha object
• Up-to-date support - the library evolves with the API, all new captcha types are added promptly

Environment Setup

Minimum requirements:

• Python 3.6 or higher
• API key from your 2Captcha account dashboard

Install in one command via pip:

pip install 2captcha-python

After installation, add the import to your script:

from twocaptcha import TwoCaptcha

For async mode:

from twocaptcha import AsyncTwoCaptcha

How the Module Works

Main Class: TwoCaptcha

All interactions with the service go through an instance of the TwoCaptcha class:

solver = TwoCaptcha('YOUR_API_KEY')

Flexible Behavior Configuration

You can configure the client for your needs via a config dictionary:

config = {
    'server':           '2captcha.com',
    'apiKey':           'YOUR_API_KEY',
    'softId':           123,
    'callback':         'https://your.site/result-receiver',
    'defaultTimeout':   120,
    'recaptchaTimeout': 600,
    'pollingInterval':  10,
    'extendedResponse': True
}
solver = TwoCaptcha(**config)

Configuration Options

Important: if callback is set, methods return only the task ID and do not poll the API. The result will arrive as a separate POST request to the specified URL.

Basic Usage Pattern

Regardless of captcha type, the workflow looks the same:

import os
from twocaptcha import TwoCaptcha

api_key = os.getenv('APIKEY_2CAPTCHA')
solver = TwoCaptcha(api_key)

# 1. Create task of needed type
# 2. Set parameters
# 3. Send and get result

try:
    result = solver.method_name(parameters)
    print('Solution: ' + result['code'])
except Exception as e:
    print('Error: ' + str(e))

This template works for any captcha type, only the method name and parameter set change.

Supported Captcha Types

The module covers all popular formats:

• Text based: Normal, Text, Audio
• Google: reCAPTCHA v2, reCAPTCHA v3, Invisible reCAPTCHA
• Cloudflare: Turnstile, Challenge
• Other providers: GeeTest, FunCaptcha, KeyCaptcha, Capy, Lemin, MTCaptcha, DataDome, Amazon WAF, Tencent, VK Captcha and many more

Full list with parameter examples is in the captcha types documentation.

Advanced Features

Async Mode

The library fully supports async/await for non-blocking operation:

import asyncio
from twocaptcha import AsyncTwoCaptcha

async def solve():
    solver = AsyncTwoCaptcha('YOUR_API_KEY')
    result = await solver.normal('captcha.jpg')
    print('Code:', result['code'])

asyncio.run(solve())

More details with examples: async examples on GitHub

Callback Mode

If you do not want to wait for the result in code, set up a Callback:

solver = TwoCaptcha('YOUR_API_KEY', callback='https://your.site/webhook')
result = solver.normal('captcha.jpg')
# result contains only the task ID, the result will arrive at your server

Manual Flow Control

For complex scenarios, low-level control is available:

task_id = solver.send({'method': 'post', 'body': '...'})
# ... your logic ...
result = solver.get_result(task_id)

Working with Proxies

Many captchas require a request from a specific IP. Pass the proxy right in the method:

result = solver.recaptcha(
    sitekey='6Le-wvkS...',
    pageurl='https://example.com',
    proxy='login:pass@123.123.123.123:8000',
    proxy_type='HTTPS'
)

Additional Captcha Parameters

For text and some other types, you can clarify expectations:

result = solver.normal(
    'captcha.jpg',
    numeric=0,
    minLen=4,
    maxLen=20,
    phrase=0,
    caseSensitive=1,
    lang='en',
    hintText='Enter only uppercase letters'
)

Error Handling

The library throws exceptions with clear messages. Always use try-except:

try:
    result = solver.normal('captcha.jpg')
except Exception as e:
    # Log the error and decide: retry, notify, or fallback
    print(f'Failed: {e}')

Common Error Codes

Integration Tips

• Store keys securely - use os.getenv() or libraries like python-dotenv, do not hardcode your API key
• Set timeouts for your task - complex captchas can take longer, do not set limits that are too short
• Add logging - save task IDs and response times for debugging and auditing
• Test in the sandbox - before production launch, check your integration in a test environment
• Watch your balance - set up low balance notifications to avoid downtime

Additional Resources

• Source code on GitHub - examples, issues, releases
• Async examples - ready snippets for async mode
• Full API documentation - all endpoints and parameters
• Python examples - ready snippets for each captcha type
• Error reference - explanation of all response codes
• Support - if something goes wrong

Pre-Launch Checklist

• Library installed via pip
• API key obtained and saved in an environment variable
• Correct method selected and required parameters configured
• Timeouts and polling interval set for your load
• Exception handling and basic logging implemented
• Solution tested with real parameters from the target site
• Callback or proxy configured if needed

Conclusion

The 2captcha-python module is a reliable and convenient way to add captcha solving to any Python project. It hides API complexity behind a simple interface, supports async operations, is flexible to configure, and covers all popular captcha types.

Start with basic client setup, pick the method you need, and add error handling, that is enough for stable operation. And when your task grows, the library scales with you: callback notifications, manual flow control, proxies, and extended logging are all supported.

Documentation, code examples, and 2Captcha support will help you quickly handle any scenario.

Automate captcha bypass efficiently and with minimal effort using 2captcha-python.