Node.js Captcha Solver Module for Puppeteer
The capguru module solves captchas right on the page your Puppeteer script controls: it clicks images, drags sliders and handles other tasks, and it can detect the captcha type on the page automatically. Starting with version 0.5.0, it also gets reCAPTCHA and Cloudflare Turnstile tokens, recognizes text captchas and works without a browser.
You can test your script on the captcha demo pages. If you work in Python, there is the same Python module for Playwright and Selenium.
Versions
| Module Version | Download | Changes |
|---|---|---|
| 0.5.0 | npm � 0.5 | reCAPTCHA v2/v3 (Enterprise) and Cloudflare Turnstile tokens, text captchas, client without a browser, timeouts and CapGuruSolveError |
| 0.4 | 0.4 | Global update, automatic captcha detection auto(), added AWS WAF |
Installation
The module is published on npm:
npm install capguru puppeteerconst { CaptchaSolver, CapGuruFatalError, CapGuruSolveError } = require('capguru');Update to the latest version:
npm install capguru@latestInstallation without npm
Download the archive from the version table, copy the capguru folder into your project and install Puppeteer:
npm install puppeteerThen import it with a relative path: require('./capguru').
Usage
- Import
CaptchaSolverfrom the package. - Launch the browser as in the example below, create the solver before navigating to the page with the captcha, and call
await solver.setup(). - Open the page and call
await solver.auto(): the module will find the captcha and solve it.
If you know the captcha type in advance, you can call the specific method directly.
const puppeteer = require('puppeteer');
const { CaptchaSolver, CapGuruFatalError } = require('capguru');
(async () => {
const browser = await puppeteer.launch({
headless: false,
ignoreDefaultArgs: ['--enable-automation'],
args: ['--disable-blink-features=AutomationControlled'],
});
const page = await browser.newPage();
const solver = new CaptchaSolver({
page,
apiKey: 'YOUR_CAPGURU_API_KEY',
debug: true,
attempts: 5,
});
await solver.setup();
await page.goto('https://example.com/with-captcha');
try {
const kind = await solver.auto(30);
console.log('Captcha:', kind || 'not found');
} catch (e) {
if (e instanceof CapGuruFatalError) console.log('API key or balance problem:', e.message);
else console.log('Not solved:', e.message);
} finally {
await browser.close();
}
})();Why the solver is created before navigation
When created, the solver starts capturing the captcha images loaded by the browser and switches hCaptcha to English. If you create it after page.goto(), images from the first load will be missed and hCaptcha may stay in the site's language.
Why the browser is launched with these options
With the default Puppeteer launch, sites see that the browser is controlled by a program (navigator.webdriver is true), and Google and GeeTest show harder challenges or refuse. The options in the example turn this off.
Methods
Automatic:
await solver.auto(30); // find and solve the captcha, returns its type or null
await solver.detect(); // only detect the type, without solving
await solver.setup(); // preparation, call before page.goto()auto() does not solve Cloudflare Turnstile and reCAPTCHA v3: use the token methods below for them.
Solving on the page, for a specific type:
await solver.solveRecaptcha2();
await solver.solveHcaptcha();
await solver.solveOther();
await solver.solveGeetest();
await solver.solveFuncaptcha();
await solver.solveTiktok();
await solver.solveAws();Tokens and text captchas (since 0.5.0):
await solver.solveRecaptchaToken(); // reCAPTCHA v2 or v3, detected from the page
await solver.solveRecaptchaToken({ version: 'v3', action: 'login', enterprise: true });
await solver.solveTurnstileToken(); // Cloudflare Turnstile
await solver.solveImageCaptcha('#captcha_img', { fillSelector: '#captcha_input' });
await solver.getBalance(); // account balance
solver.cancel(); // stop the current solvesolveRecaptchaToken()andsolveTurnstileToken()find the sitekey, action and Enterprise flag on the open page and put the token into it: reCAPTCHA v2 intog-recaptcha-responseand the site callback, Turnstile intocf-turnstile-responseanddata-callback. They return{ token, taskId }. For v3,actiondefaults toverify.solveImageCaptcha()sends the image shown on the page (a screenshot of the element) and never downloads it again: many sites return a new captcha on every request. WithfillSelector, it types the answer into the input. It returns{ text, taskId }.
auto() and detect() return the captcha type:
| Value | Captcha |
|---|---|
recaptcha2 | reCAPTCHA v2 |
hcaptcha | hCaptcha |
yandex | Other |
geetest | GeeTest v3 / v4 |
funcaptcha | FunCaptcha (Arkose Labs) |
tiktok | TikTok |
aws | AWS WAF |
null | No captcha found within the timeout |
auto() parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
timeout | number | 30 | How many seconds to wait for a captcha to appear. On slow sites, 45 to 60 is safer |
poll | number | 0.5 | How often to check the page, in seconds |
Without a Browser
You can get tokens and recognize text captchas without Puppeteer, with the API client:
const { CapGuruClient } = require('capguru');
const client = new CapGuruClient('YOUR_KEY'); // https://api2.cap.guru by default, falls back to https://api.cap.guru
await client.getBalance();
await client.recaptchaV2Token({ sitekey, pageurl, invisible: false });
await client.recaptchaV3Token({ sitekey, pageurl, action: 'verify', enterprise: false });
await client.turnstileToken({ sitekey, pageurl });
await client.imageText(bufferOrBase64, { vernet: 0 }); // vernet 22 = arithmetic, the result is calculated
await client.solveTask({ method: 'geetest', gt, challenge, pageurl }); // any other taskToken methods return { token, taskId }, imageText returns { text, taskId } (plus expression for arithmetic). enterprise: true sends enterprise=1 (v3 only).
Supported Captchas
| Captcha | On the page | Token |
|---|---|---|
| reCAPTCHA v2 / v2 Invisible | Yes | Yes |
| reCAPTCHA v3 / v3 Enterprise | Yes | |
| Cloudflare Turnstile | Yes | |
| hCaptcha | Yes | |
| Other | Yes | |
| GeeTest v3 / v4 | Yes | |
| FunCaptcha | Yes | |
| TikTok | Yes | |
| AWS WAF | Yes | |
| Text captchas | Yes |
Constructor Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | Page | none | Puppeteer page instance |
apiKey | string | none | Cap.Guru API key |
server | string | 'https://api.cap.guru' | API server URL. Outside Russia, use 'https://api2.cap.guru' |
attempts | number | 5 | Max number of solving attempts. For GeeTest and FunCaptcha, 8 to 10 work better: they often show several rounds of images in a row |
timeout | number | 300 | How many seconds a captcha solve on the page may take. Can also be set per call: solver.solveGeetest('', { timeout: 120 }) |
debug | boolean | false | Enable debug logging |
selector | string | '' | CSS selector of the captcha container, if the page has several captchas |
For tokens and text captchas, the default wait time is 120 seconds; set it with the timeout option of each method.
Requirements
- Puppeteer 24 or 25
- Node.js 18 or newer (Puppeteer 25 requires Node.js 22.12 or newer)
Error Handling
CapGuruFatalError: an invalid API key or zero balance. The module stops retrying immediately.CapGuruSolveError: the captcha could not be solved after all attempts, or the time ran out. For tokens and text captchas the error includestaskId.
Both classes are subclasses of Error:
const { CapGuruFatalError, CapGuruSolveError } = require('capguru');
try {
const kind = await solver.auto(30);
console.log('Captcha:', kind || 'not found');
} catch (e) {
if (e instanceof CapGuruFatalError) {
console.log('API key or balance problem:', e.message);
} else if (e instanceof CapGuruSolveError) {
console.log('Captcha not solved:', e.message);
} else {
throw e;
}
}What the API error codes mean is explained on the error codes page.