{"id":5833,"library":"2captcha-python","title":"2Captcha Python Client","description":"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.","status":"active","version":"2.0.6","language":"en","source_language":"en","source_url":"https://github.com/2captcha/2captcha-python/","tags":["captcha","anti-captcha","web automation","reCAPTCHA","FunCaptcha","GeeTest","Cloudflare Turnstile","API client"],"install":[{"cmd":"pip install 2captcha-python","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"For synchronous API calls.","symbol":"TwoCaptcha","correct":"from twocaptcha import TwoCaptcha"},{"note":"For asynchronous API calls (introduced in v2.0.0).","symbol":"AsyncTwoCaptcha","correct":"from twocaptcha import AsyncTwoCaptcha"}],"quickstart":{"code":"import os\nfrom twocaptcha import TwoCaptcha\nfrom twocaptcha.solver import ValidationException, NetworkException, ApiException\n\n# Best practice: Load API key from environment variables\nAPI_KEY = os.environ.get('TWO_CAPTCHA_API_KEY', 'YOUR_2CAPTCHA_API_KEY')\n\nsolver = TwoCaptcha(API_KEY)\n\ntry:\n    # Example: Solving a normal image-to-text captcha\n    # Replace 'path/to/captcha.jpg' with your captcha image file path or URL\n    # You can also pass base64 encoded image data\n    result = solver.normal('path/to/captcha.jpg')\n    print(f\"Captcha solved: {result['code']}\")\n    # The 'id' field can be used to report incorrect solutions later\n    # print(f\"Captcha ID: {result['id']}\")\nexcept ValidationException as e:\n    print(f\"Validation error: {e}\")\nexcept NetworkException as e:\n    print(f\"Network error: {e}\")\nexcept ApiException as e:\n    print(f\"API error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<2.0.0 (for library version using API v1)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Hardcoding your 2Captcha API key directly in your scripts poses a security risk. If your code is exposed, your API key can be compromised.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}