2Captcha Python Client
raw JSON → 2.0.6 verified Tue Apr 14 auth: no python
The 2captcha-python library provides an easy-to-use Python module for integrating with the 2Captcha API. It simplifies the process of automating captcha solving for various types like reCAPTCHA, Arkose, GeeTest, and image-to-text captchas. Currently at version 2.0.6, the library maintains an active release cadence, regularly adding support for new captcha types and enhancing existing features.
pip install 2captcha-python Common errors
error ModuleNotFoundError: No module named 'requests' ↓
cause The 'requests' module is not installed in the current Python environment.
fix
Install the 'requests' module using pip: 'pip install requests'.
error ModuleNotFoundError: No module named 'captcha' ↓
cause The 'captcha' module is not installed or is incorrectly referenced in the code.
fix
Install the 'captcha' module using pip: 'pip install captcha'.
error ModuleNotFoundError: No module named 'hcaptcha' ↓
cause The 'hcaptcha' module is not installed or is incorrectly referenced in the code.
fix
Install the 'hcaptcha' module using pip: 'pip install hcaptcha'.
error ModuleNotFoundError: No module named 'captcha.image'; 'captcha' is not a package ↓
cause A local file named 'captcha.py' is shadowing the 'captcha' package, causing import conflicts.
fix
Rename the local 'captcha.py' file to avoid naming conflicts with the 'captcha' package.
error ModuleNotFoundError: No module named 'captcha.fields' ↓
cause The 'django-simple-captcha' module is not installed, leading to missing 'captcha.fields'.
fix
Install the 'django-simple-captcha' module using pip: 'pip install django-simple-captcha'.
Warnings
breaking Version 2.0.0 introduced asynchronous API support, requiring the use of `AsyncTwoCaptcha` and `await` for async operations. While synchronous methods (`TwoCaptcha`) are still available, users transitioning to async workflows must update their code accordingly. ↓
fix For asynchronous operations, replace `from twocaptcha import TwoCaptcha` with `from twocaptcha import AsyncTwoCaptcha` and ensure all API calls are `await`ed within an `async` function. Synchronous code remains compatible with `TwoCaptcha`.
deprecated The underlying 2Captcha API v1 is deprecated. All new features and improvements are being added exclusively to API v2. While API v1 remains supported for compatibility, migrating to API v2 (which `2captcha-python` v2.x utilizes) is highly recommended to access the latest functionalities and ensure future compatibility. ↓
fix Upgrade to `2captcha-python` version 2.x or later. Review the documentation for specific captcha types as API parameter changes might exist between v1 and v2.
gotcha Using the incorrect captcha type or providing wrong parameters for a specific captcha will lead to failed solutions and wasted funds. 2Captcha supports numerous captcha types, each requiring a specific API method and set of parameters. ↓
fix Always identify the exact captcha type on the target website (e.g., reCAPTCHA V2, hCaptcha, image-to-text) and use the corresponding method in the `TwoCaptcha` or `AsyncTwoCaptcha` client (e.g., `solver.recaptcha`, `solver.hcaptcha`, `solver.normal`). Carefully consult the 2Captcha API documentation for required parameters.
gotcha Inadequate error handling can lead to silent failures or unhandled exceptions. The library throws specific exceptions (`ValidationException`, `NetworkException`, `ApiException`) for different error scenarios from the API or network issues. ↓
fix Always wrap your API calls in `try...except` blocks to catch and handle `ValidationException`, `NetworkException`, and `ApiException`. This allows for robust error recovery, logging, and prevents script crashes.
gotcha Poor account balance management and inefficient polling logic can quickly drain your budget or lead to rate limiting. Polling for results too frequently (e.g., every 100ms) can trigger `MAX_USER_TURN` errors, while not monitoring your balance can lead to service interruptions. ↓
fix Check your 2Captcha account balance regularly. Implement reasonable polling intervals (e.g., 5 seconds as suggested by 2Captcha) for `get_result` calls. Avoid aggressive retries of captchas that consistently fail; review parameters or the captcha itself.
gotcha Hardcoding your 2Captcha API key directly in your scripts poses a security risk. If your code is exposed, your API key can be compromised. ↓
fix Always use environment variables (e.g., `os.environ.get('TWO_CAPTCHA_API_KEY')`) or a secure configuration management system to store and access your API key. Never commit API keys to version control.
Imports
- TwoCaptcha
from twocaptcha import TwoCaptcha - AsyncTwoCaptcha
from twocaptcha import AsyncTwoCaptcha
Quickstart
import os
from twocaptcha import TwoCaptcha
from twocaptcha.solver import ValidationException, NetworkException, ApiException
# Best practice: Load API key from environment variables
API_KEY = os.environ.get('TWO_CAPTCHA_API_KEY', 'YOUR_2CAPTCHA_API_KEY')
solver = TwoCaptcha(API_KEY)
try:
# Example: Solving a normal image-to-text captcha
# Replace 'path/to/captcha.jpg' with your captcha image file path or URL
# You can also pass base64 encoded image data
result = solver.normal('path/to/captcha.jpg')
print(f"Captcha solved: {result['code']}")
# The 'id' field can be used to report incorrect solutions later
# print(f"Captcha ID: {result['id']}")
except ValidationException as e:
print(f"Validation error: {e}")
except NetworkException as e:
print(f"Network error: {e}")
except ApiException as e:
print(f"API error: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")