Модуль Python для решения капчи
Модуль capguru решает капчу прямо на странице, которой управляет ваш скрипт на Playwright (или Selenium через Playwright). Он кликает по картинкам, перетаскивает ползунок и проходит другие задания, а тип капчи на странице умеет определять сам.
Подробный разбор с примерами для Playwright и Selenium есть в статье API для решения капчи на Python. Проверить скрипт можно на демо-страницах капч. Если вы работаете с ИИ-ассистентами (Claude, Cursor и другими), посмотрите MCP-сервер: он использует этот же модуль.
Актуальная версия
| Версия | Изменения | Скачать |
|---|---|---|
| 0.4 | Глобальное обновление | PyPI · Скачать |
| 0.3 | Добавили AWS WAF (Amazon) | Скачать |
| 0.2 | Исправлено решение hCaptcha | Скачать |
| 0.1 | Первая версия | Скачать |
Установка
Модуль опубликован на PyPI:
pip install capguru
playwright install chromiumОбновление до последней версии:
pip install -U capguruИмпорт в коде не меняется:
from captcha_solver import CaptchaSolver, CapGuruFatalErrorУстановка без pip
Скачайте архив из таблицы версий и скопируйте папку captcha_solver в свой проект, рядом со скриптом.
Зависимости установите вручную:
pip install playwright httpx Pillow
playwright install chromiumЕсли модуль установлен через pip, не держите рядом со скриптом папку captcha_solver: Python возьмёт её, а не установленную версию.
Как использовать
- Импортируйте
CaptchaSolverиз пакета. - Создайте солвер до перехода на страницу с капчей и вызовите
await solver.setup(). - Откройте страницу и вызовите
await solver.auto(): модуль сам найдёт капчу и решит её.
Если тип капчи известен заранее, можно вызвать нужный метод напрямую.
solver = CaptchaSolver(page=page, api_key='YOUR_KEY', debug=True)
await solver.setup()
await page.goto('https://site.com/cap')
kind = await solver.auto(timeout=30)
print('Captcha:', kind or 'not found')Почему солвер создаётся до перехода на страницу
При создании солвер начинает запоминать картинки капчи, которые загружает браузер, и переключает hCaptcha на английский язык. Если создать его после page.goto(), картинки первой загрузки будут пропущены, а hCaptcha может остаться на языке сайта.
Примеры
# pip install playwright playwright-stealth httpx Pillow
# playwright install chrome
import asyncio
from playwright.async_api import async_playwright
from playwright_stealth import Stealth
from captcha_solver import CaptchaSolver, CapGuruFatalError
async def main():
async with async_playwright() as p:
browser = await p.chromium.launch(
headless=False,
channel="chrome",
args=["--disable-blink-features=AutomationControlled"],
)
page = await browser.new_page()
await Stealth().apply_stealth_async(page)
solver = CaptchaSolver(
page=page,
api_key='YOUR_KEY',
debug=True,
attempts=5,
)
await solver.setup()
await page.goto('https://site.com/cap')
try:
kind = await solver.auto(timeout=30)
print('Captcha:', kind or 'not found')
except CapGuruFatalError as e:
print('API key or balance problem:', e)
await browser.close()
asyncio.run(main())# pip install playwright httpx Pillow
# playwright install chromium
import asyncio
from playwright.async_api import async_playwright
from captcha_solver import CaptchaSolver, CapGuruFatalError
async def main():
async with async_playwright() as p:
browser = await p.chromium.launch(headless=False)
page = await browser.new_page()
solver = CaptchaSolver(
page=page,
api_key='YOUR_KEY',
debug=True,
attempts=5,
)
await solver.setup()
await page.goto('https://site.com/cap')
try:
kind = await solver.auto(timeout=30)
print('Captcha:', kind or 'not found')
except CapGuruFatalError as e:
print('API key or balance problem:', e)
await browser.close()
asyncio.run(main())# pip install playwright httpx Pillow
# playwright install firefox
import asyncio
from playwright.async_api import async_playwright
from captcha_solver import CaptchaSolver, CapGuruFatalError
async def main():
async with async_playwright() as p:
browser = await p.firefox.launch(headless=False)
page = await browser.new_page()
solver = CaptchaSolver(
page=page,
api_key='YOUR_KEY',
debug=True,
attempts=5,
)
await solver.setup()
await page.goto('https://site.com/cap')
try:
kind = await solver.auto(timeout=30)
print('Captcha:', kind or 'not found')
except CapGuruFatalError as e:
print('API key or balance problem:', e)
await browser.close()
asyncio.run(main())# pip install undetected-chromedriver playwright httpx Pillow
# Chrome browser must be installed
import asyncio
import undetected_chromedriver as uc
from playwright.async_api import async_playwright
from captcha_solver import CaptchaSolver, CapGuruFatalError
async def main():
driver = uc.Chrome(headless=False)
try:
address = driver.capabilities['goog:chromeOptions']['debuggerAddress']
async with async_playwright() as p:
browser = await p.chromium.connect_over_cdp(f'http://{address}')
page = browser.contexts[0].pages[0]
solver = CaptchaSolver(
page=page,
api_key='YOUR_KEY',
debug=True,
attempts=5,
)
await solver.setup()
await asyncio.to_thread(driver.get, 'https://site.com/cap')
try:
kind = await solver.auto(timeout=30)
print('Captcha:', kind or 'not found')
except CapGuruFatalError as e:
print('API key or balance problem:', e)
finally:
driver.quit()
asyncio.run(main())# pip install selenium playwright httpx Pillow
# Chrome browser and chromedriver must be installed
import asyncio
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from playwright.async_api import async_playwright
from captcha_solver import CaptchaSolver, CapGuruFatalError
async def main():
options = webdriver.ChromeOptions()
# options.add_argument('--headless=new')
service = Service() # Service('/path/to/chromedriver')
driver = webdriver.Chrome(service=service, options=options)
try:
address = driver.capabilities['goog:chromeOptions']['debuggerAddress']
async with async_playwright() as p:
browser = await p.chromium.connect_over_cdp(f'http://{address}')
page = browser.contexts[0].pages[0]
solver = CaptchaSolver(
page=page,
api_key='YOUR_KEY',
debug=True,
attempts=5,
)
await solver.setup()
await asyncio.to_thread(driver.get, 'https://site.com/cap')
try:
kind = await solver.auto(timeout=30)
print('Captcha:', kind or 'not found')
except CapGuruFatalError as e:
print('API key or balance problem:', e)
finally:
driver.quit()
asyncio.run(main())# pip install selenium-wire undetected-chromedriver playwright httpx Pillow
# Chrome browser must be installed
import asyncio
import seleniumwire.undetected_chromedriver as uc
from playwright.async_api import async_playwright
from captcha_solver import CaptchaSolver, CapGuruFatalError
async def main():
options = uc.ChromeOptions()
# options.add_argument('--headless=new')
driver = uc.Chrome(options=options, headless=False)
try:
address = driver.capabilities['goog:chromeOptions']['debuggerAddress']
async with async_playwright() as p:
browser = await p.chromium.connect_over_cdp(f'http://{address}')
page = browser.contexts[0].pages[0]
solver = CaptchaSolver(
page=page,
api_key='YOUR_KEY',
debug=True,
attempts=5,
)
await solver.setup()
await asyncio.to_thread(driver.get, 'https://site.com/cap')
try:
kind = await solver.auto(timeout=30)
print('Captcha:', kind or 'not found')
except CapGuruFatalError as e:
print('API key or balance problem:', e)
finally:
driver.quit()
asyncio.run(main())Примеры Chrome, Chromedriver и Seleniumwire запускают браузер через Selenium и подключают солвер к этому же браузеру через Playwright. Они работают только с Chrome и требуют Python 3.9 или новее.
Методы
Автоматически:
await solver.auto(timeout=30) # найти капчу и решить, вернёт тип или None
await solver.detect() # только определить тип, не решая
await solver.setup() # подготовка, вызывать до page.goto()Для конкретного типа:
await solver.solve_recaptcha2()
await solver.solve_hcaptcha()
await solver.solve_other()
await solver.solve_geetest()
await solver.solve_funcaptcha()
await solver.solve_tiktok()
await solver.solve_aws()auto() и detect() возвращают тип капчи:
| Значение | Капча |
|---|---|
recaptcha2 | reCAPTCHA v2 |
hcaptcha | hCaptcha |
yandex | Other |
geetest | GeeTest v3 / v4 |
funcaptcha | FunCaptcha (Arkose Labs) |
tiktok | TikTok |
aws | AWS WAF |
None | Капча не найдена за отведённое время |
Поддерживаемые капчи
| reCAPTCHA v2 | FunCaptcha | TikTok | GeeTest | AWS WAF | hCaptcha | Other |
|---|---|---|---|---|---|---|
| Да | Да | Да | Да | Да | Да | Да |
Параметры
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
page | Page | — | Страница с капчей |
api_key | str | — | API-ключ Cap.Guru |
attempts | int | 5 | Максимальное число попыток. Для GeeTest и FunCaptcha лучше 8–10: они часто показывают несколько раундов картинок подряд |
debug | bool | False | Вывод отладочных сообщений |
selector | str | '' | CSS-селектор контейнера капчи, если на странице их несколько |
Параметры auto():
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
timeout | float | 30 | Сколько секунд ждать появления капчи. На медленных сайтах лучше 45–60 |
poll | float | 0.5 | Как часто проверять страницу, в секундах |
Обработка ошибок
При неверном API-ключе или нулевом балансе выбрасывается CapGuruFatalError, и модуль сразу прекращает попытки.
Если капчу не удалось решить за все попытки, выбрасывается RuntimeError.CapGuruFatalError наследуется от RuntimeError, поэтому ловите его первым:
from captcha_solver import CaptchaSolver, CapGuruFatalError
try:
kind = await solver.auto(timeout=30)
print('Captcha:', kind or 'not found')
except CapGuruFatalError as e:
print('API key or balance problem:', e)
except RuntimeError as e:
if 'ERROR_CAPTCHA_UNSOLVABLE' in str(e):
print('Captcha was not solved after all attempts')Что значат коды ошибок API, описано на странице кодов ошибок.