Registry / http-networking / 2captcha-python

2captcha-python

library2.1.1pypypi✓ verified 20d ago

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.

http-networking auth-security

pip install 2captcha-python

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · 2CAPTCHA-PYTHON

2captcha-python

http-networkingpythonv2.1.1

Install

2.6s avg

Import

555ms

Disk

23MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.592s · 24.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.6s · import 0.518s · 25MB

23MB installed

● package 23MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TwoCaptcha

✓ from twocaptcha import TwoCaptcha

For synchronous API calls.

AsyncTwoCaptcha

✓ from twocaptcha import AsyncTwoCaptcha

For asynchronous API calls (introduced in v2.0.0).

This quickstart demonstrates how to solve a basic image-to-text captcha using the synchronous `TwoCaptcha` client. It emphasizes loading the API key from environment variables for security and includes comprehensive error handling for common API and network issues. Replace `'path/to/captcha.jpg'` with your captcha image file path or URL for a runnable example.

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}")

Debug

Known issues

breakingVersion 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`.

affects: >=2.0.0

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

affects: <2.0.0 (for library version using API v1)

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

affects: All

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

affects: All

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

affects: All

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

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'requests'

The 'requests' module is not installed in the current Python environment.

fix

Install the 'requests' module using pip: 'pip install requests'.

ModuleNotFoundError: No module named 'captcha'

The 'captcha' module is not installed or is incorrectly referenced in the code.

fix

Install the 'captcha' module using pip: 'pip install captcha'.

ModuleNotFoundError: No module named 'hcaptcha'

The 'hcaptcha' module is not installed or is incorrectly referenced in the code.

fix

Install the 'hcaptcha' module using pip: 'pip install hcaptcha'.

ModuleNotFoundError: No module named 'captcha.image'; 'captcha' is not a package

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.

ModuleNotFoundError: No module named 'captcha.fields'

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

Upgrade

Version history

2.1.1latest on PyPI · released Aug 28, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

107 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/2captcha/2captcha-python ↗

packagehttps://pypi.org/project/2captcha-python/ ↗

homepagehttps://2captcha.com ↗