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 multipart in.php/res.php endpoints.

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, and proxyPort; 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. profile validates 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

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

captcha rucaptcha 2captcha deathbycaptcha recaptcha geetest hcaptcha capypuzzle rotatecaptcha funcaptcha keycaptcha python3 recaptcha captcha security tencent atb_captcha python-library python-rucaptcha rucaptcha-client yandex turnstile amazon amazon_waf vk-captcha fox-captcha temu-captcha friendly-captcha binance-captcha

Metadata

Release files for python-rucaptcha 6.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-rucaptcha 6.8.1
File	Size	Uploaded
python_rucaptcha-6.8.1.tar.gz	62.0 kB	Oct 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for python-rucaptcha 6.8.1
File	Interpreter	ABI	Platform	Reset
python_rucaptcha-6.8.1-py3-none-any.whl 74.4 kB Oct 7, 2026	Python 3	none	any	Details

Total release size: 136.4 kB

Release files / python_rucaptcha-6.8.1.tar.gz

Download URL	python_rucaptcha-6.8.1.tar.gz
Size	62.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`62f184852c6023a6053cdae58363c1d53647098d2c5c249d09144674a705034e`
BLAKE2b-256 checksum How to use checksums	`a834d5ddedfd16de45e379fc9f9eb843a26e63e6552de13c5901a0c119bf63e4`
Upload date	Oct 7, 2026
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.1-py3-none-any.whl

Download URL	python_rucaptcha-6.8.1-py3-none-any.whl
Size	74.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`26bd460e73cd2e029811f2842d814d5be272d4acd6a809f59e4978933dfa38c5`
BLAKE2b-256 checksum How to use checksums	`1e6c975dd7cc528cb7a6071cdcd66149cffec5b2a4dde12d31bdbce67134e152`
Upload date	Oct 7, 2026
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}`