hCaptcha Challenger

0.19.0 verified Fri May 01 auth: no python

A Python library for solving hCaptcha challenges using multimodal large language models. Version 0.19.0 requires Python >=3.10. Development is active with irregular releases.

pip install hcaptcha-challenger

Common errors

error TypeError: solve() got an unexpected keyword argument 'images' ↓

cause In version 0.19.0, the parameter was renamed from images to image_paths.

fix

Use image_paths instead of images.

error ImportError: cannot import name 'Challenger' from 'hcaptcha_challenger' ↓

cause Challenger is not exported from the package if installed an older version or if installed from a non-standard source.

fix

Ensure you have version >=0.10.0 and use 'from hcaptcha_challenger import Challenger'.

Warnings

breaking In version 0.19.0, the solve() method signature changed: 'image_paths' replaces the old 'images' parameter. Old code using 'images' will raise TypeError. ↓

fix Change keyword argument from 'images' to 'image_paths'.

deprecated Direct model file download via challenger.download() is deprecated in favor of auto-download during solve(). ↓

fix Remove explicit download() calls; the library downloads models on demand.

gotcha The library expects specific task strings like "image_label_binary" or "image_area_select". Using an unknown task string raises a KeyError. ↓

fix Check supported tasks in documentation or use a try-except.

Imports

Challenger

wrong

from hcaptcha_challenger.challenger import Challenger

correct

from hcaptcha_challenger import Challenger

Challenger is re-exported at package level in latest versions.

Quickstart

Basic usage: create a Challenger instance and call solve() with image paths and a task type.

from hcaptcha_challenger import Challenger

challenger = Challenger()
# Solve a challenge given image paths
result = challenger.solve(image_paths=["captcha_image.png"], task="image_label_binary")
print(result)