python-rucaptcha
Python 3.9+ library to solve CAPTCHAs automatically using RuCaptcha, 2Captcha, DeathByCaptcha, or CaptchaAI services.
Using CaptchaAI: compatible high-level classes can pass
service_type=ServiceEnm.CAPTCHAAI. CaptchaAI uses the classic multipartin.php/res.phpendpoints.from python_rucaptcha.turnstile import Turnstile from python_rucaptcha.core.enums import ServiceEnm result = Turnstile( rucaptcha_key="CAPTCHAAI_KEY", service_type=ServiceEnm.CAPTCHAAI, websiteURL="https://example.com", websiteKey="0x4AAAAAAA...", userAgent="Mozilla/5.0 ...", ).captcha_handler()Proxy task types require
proxyType,proxyAddress, andproxyPort; credentials are optional:from python_rucaptcha.re_captcha import ReCaptcha from python_rucaptcha.core.enums import ReCaptchaEnm, ServiceEnm result = ReCaptcha( rucaptcha_key="CAPTCHAAI_KEY", service_type=ServiceEnm.CAPTCHAAI, websiteURL="https://example.com/login", websiteKey="SITE_KEY", method=ReCaptchaEnm.RecaptchaV2Task, proxyType="HTTPS", proxyAddress="203.0.113.7", proxyPort=3128, proxyLogin="user", proxyPassword="pass", ).captcha_handler()For every documented CaptchaAI method—or a provider method released after this package—use the native, type-free client.
profilevalidates a packaged documented contract; omit it to pass provider-native fields through unchanged.from python_rucaptcha.captchaai import CaptchaAI, CaptchaAIFile result = CaptchaAI( rucaptcha_key="CAPTCHAAI_KEY", profile="cloudflare-challenge", params={ "pageurl": "https://example.com/protected", "proxy": "user:pass@203.0.113.7:3128", "proxytype": "HTTPS", }, ).captcha_handler() image = CaptchaAI( rucaptcha_key="CAPTCHAAI_KEY", profile="normal-solve-file", files={"file": CaptchaAIFile(b"... PNG bytes ...", "captcha.png", "image/png")}, ).captcha_handler()
What is this?
This library automates CAPTCHA solving by connecting to third-party services. When your code encounters a CAPTCHA, python-rucaptcha sends it to the service, waits for a human to solve it, and returns the solution to your application.
Supports 30+ CAPTCHA types:
- reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile
- Image captchas, Audio captchas
- GeeTest, KeyCaptcha, Amazon WAF, Tencent
- And many more...
Quick Start
1. Install
pip install python-rucaptcha
2. Get an API Key
Sign up at RuCaptcha or 2Captcha, then copy your API key from the dashboard.
3. Solve a CAPTCHA
from python_rucaptcha import HCaptcha
# Your API key
key = "your_api_key_here"
# Solve hCaptcha
result = HCaptcha(aptcha_key=key).captcha_handler(site_url="https://example.com", site_key="abc123")
if result['code'] == 0:
print(f"Solved! Token: {result['token']}")
else:
print(f"Error: {result['message']}")
Solving Different CAPTCHA Types
reCAPTCHA v2:
from python_rucaptcha import ReCaptcha
result = ReCaptcha(api_key).captcha_handler(
site_url="https://example.com",
site_key="your_site_key"
)
Image CAPTCHA:
from python_rucaptcha import ImageCaptcha
result = ImageCaptcha(api_key).captcha_handler(
image_link="https://example.com/captcha.jpg"
)
ALTCHA:
from python_rucaptcha import AltchaCaptcha
from python_rucaptcha.core.enums import AltchaEnm
result = AltchaCaptcha(
rucaptcha_key=api_key,
websiteURL="https://example.com",
challengeURL="https://example.com/altcha/challenge",
method=AltchaEnm.AltchaTaskProxyless,
).captcha_handler()
Using async:
import asyncio
from python_rucaptcha import HCaptcha
async def solve():
result = await HCaptcha(api_key).aio_captcha_handler(
site_url="https://example.com",
site_key="abc123"
)
return result
token = asyncio.run(solve())
Supported CAPTCHA Types
| CAPTCHA | Module | Description |
|---|---|---|
| reCAPTCHA v2/v3 | ReCaptcha |
Google reCAPTCHA |
| hCaptcha | HCaptcha |
hCaptcha challenge |
| Cloudflare Turnstile | Turnstile |
Cloudflare protection |
| Image | ImageCaptcha |
Type the text from image |
| Audio | AudioCaptcha |
Listen and type audio |
| GeeTest | GeeTest |
Chinese geetest puzzles |
| KeyCaptcha | KeyCaptcha |
KeyCAPTCHA service |
| Amazon WAF | AmazonWaf |
AWS WAF challenge |
| ALTCHA | AltchaCaptcha |
ALTCHA challenge |
| TSPD | TSPDCaptcha |
Cookie-based TSPD protection |
| Basilisk | BasiliskCaptcha |
Token-based Basilisk challenge |
| Alibaba | AlibabaCaptcha |
Token-based Alibaba challenge |
| Imperva/Incapsula | IncapsulaCaptcha |
Cookie-based Imperva protection |
| Binance | BinanceCaptcha |
Token-based Binance challenge |
| Grid | GridCaptcha |
Select grid cells |
| Coordinates | CoordinatesCaptcha |
Click on coordinates |
| And 20+ more | ... | See full docs |
Switching Services
Use the same code with different services:
from python_rucaptcha import HCaptcha
from python_rucaptcha.core.enums import ServiceEnm
# Use 2Captcha (default)
result = HCaptcha("2captcha_key").captcha_handler(...)
# Use RuCaptcha
result = HCaptcha("rucaptcha_key", service_type=ServiceEnm.RuCaptcha).captcha_handler(...)
# Use DeathByCaptcha
result = HCaptcha("dbc_user:dbc_pass", service_type=ServiceEnm.DeathByCaptcha).captcha_handler(...)
Testing
# Set your API key
export RUCAPTCHA_KEY="your_key_here"
# Run tests
make tests
Documentation
For advanced usage, configuration options, and all CAPTCHA types, see the full documentation.
Support
- Telegram: pythoncaptcha
- Email: python-captcha@pm.me
- Issues: GitHub Issues
Changelog
See Releases for full changelog.
- v6.0 - Refactored to use msgspec (faster), API v2, dropped Python 3.8
- v5.3 - Added DeathByCaptcha support
- v5.2 - Added audio CAPTCHA solving
Metadata
Release files for python-rucaptcha 6.8.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| python_rucaptcha-6.8.2.tar.gz | 62.0 kB | Without provenance | Details for python_rucaptcha-6.8.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| python_rucaptcha-6.8.2-py3-none-any.whl | Python 3 | none | any | Details for python_rucaptcha-6.8.2-py3-none-any.whl |
Total release size: 136.4 kB
Release files / python_rucaptcha-6.8.2.tar.gz
| Download URL | python_rucaptcha-6.8.2.tar.gz |
|---|---|
| Size | 62.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8143843bb43958e03bfaa80c3893d134d6ce456ad206f0af17040428cfaa3dc3
|
|
BLAKE2b-256 checksum How to use checksums |
529bf1a048c02d9178c71119cd9ee0cb88132a02086622d9359f8b2d0afb3140
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / python_rucaptcha-6.8.2-py3-none-any.whl
| Download URL | python_rucaptcha-6.8.2-py3-none-any.whl |
|---|---|
| Size | 74.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3ddc05f39e690f72272788c5ca20ae8cb70c6e3744048a6c1db5165a418ac68c
|
|
BLAKE2b-256 checksum How to use checksums |
69b070d760700f704b7a38c434419c3e6f298411937d68f2409d4bdc89b6b727
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for python-rucaptcha 6.8.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.