To solve a Pydoll CAPTCHA, read the sitekey from the page, solve it with CapSkip’s AsyncCapSkip client on the same asyncio event loop, write the token into the g-recaptcha-response box and run the page’s callback or submit the form. Pydoll 3.0 has no reCAPTCHA code of its own, so the token has to come from a solver. CapSkip runs on your own Windows PC, so a crawl that opens many pages has no per-solve cost. This guide builds the whole Pydoll CAPTCHA flow in about 80 lines and covers the traps that cost time on Windows.<\/p>\n
The measurements below come from a mock CapSkip and a mock sign-up page on the same PC, used with the real Pydoll, the real SDK, a real Chrome and Google’s real api.js script. The browser and SDK behaviour holds for your own site too. Solve times and the accept and reject rules of the page are the mock’s own. One solve against a running CapSkip, using Google’s public test sitekey and default settings, took 9.0 seconds and returned a token of 1,764 characters. Solve times vary from run to run. That token was not used anywhere, and no live site was tried.<\/p>\n
Pydoll drives Chrome over the DevTools protocol, with no WebDriver in between. It gives you the browser, the page’s elements and a way to run JavaScript. Its only CAPTCHA code in 3.0.0 is a helper for the Cloudflare Turnstile checkbox. That helper finds the checkbox and clicks it. It never reads a token and it never raises an error when nothing happens. There is no reCAPTCHA handling at all. A reCAPTCHA v2 checkbox is solved by a service that returns a token, and the page then needs that token in the right place. That is the job CapSkip does here, and the rest of this guide is the glue.<\/p>\n
Use a virtual environment in an empty folder. The commands run the environment’s own Python by its path, so you do not need to activate it, and a restricted PowerShell script policy does not get in the way. Run every script below with the environment’s Python, for example .\\.venv\\Scripts\\python.exe solve.py. An older Pydoll install, such as 2.27.0, would fail at the first import of the script below with ImportError: cannot import name ‘Chrome’ from ‘pydoll’. Pydoll 3.0 exports Chrome from the top level.<\/p>\n
# Windows PowerShell, in an empty folder\npython -m venv .venv\n.\\.venv\\Scripts\\python.exe -m pip install pydoll-python capskip<\/pre>\n<\/div>\nStep 2: start Chrome and open the page<\/h2>\n
Save this as solve.py. It is the smallest Pydoll script that opens your page and prints its title. The browser starts inside an async with block, so it closes again when the block ends.<\/p>\n
\n# pip install pydoll-python capskip\nimport asyncio\n\nfrom pydoll import Chrome\nfrom pydoll.browser.options import ChromiumOptions\n\nPAGE = 'https:\/\/example.com\/page-with-recaptcha'\n\n\nasync def main():\n options = ChromiumOptions()\n options.headless = True # set to False to watch the window\n async with Chrome(options=options) as browser:\n tab = await browser.start()\n await tab.go_to(PAGE)\n print(await tab.title())\n\n\nasyncio.run(main())<\/pre>\n<\/div>\nPydoll looks for Chrome in two places only: Program Files and Program Files (x86), under Google, Chrome, Application. A Chrome installed for one user, under AppData, is not found, and the script stops with InvalidBrowserPath. Set options.binary_location to the full path of chrome.exe to fix it. A path that does not exist fails with FailedToStartBrowser instead. The same line points Pydoll at Chrome for Testing, and that worked too. Pydoll does not match browser versions to anything, so 146 and 155 both ran.<\/p>\n
Start-up is slower than you expect on Windows. On the test PC, browser.start() took 2.8 seconds with the default settings and headless Chrome 155. The first go_to took 2.1 seconds more on a page with no outside script, and about 3.1 seconds on the sign-up page, which loads Google’s script. Pydoll connects to localhost, and localhost tries the IPv6 address first. Chrome’s debugging port does not listen on IPv6, and Windows takes about 2 seconds to refuse a loopback connection, so every new connection to Chrome pays about 2 seconds before the IPv4 one works. That means the browser and every extra tab you open. Pydoll has no setting for it. Making localhost resolve to 127.0.0.1 inside the Python process removes the delay in a test, but it patches the standard library, so this guide leaves it alone. Plan for it when you time a run.<\/p>\n
The with block closes Chrome on a normal exit, after an exception inside it and after a cancelled task, and it removes the temporary profile folder. Ending the Python process with taskkill \/F skips that. In the test it left 13 chrome.exe processes running and the profile folder on disk. Ctrl+C at a console was not tested. If you killed a run, look in Task Manager for chrome.exe processes before you start the next one.<\/p>\n
Step 3: check that CapSkip answers<\/h2>\n
Before you add a browser, confirm the solver call works on its own. Save this as first_solve.py. AsyncCapSkip is the async client from the same package. The SDK reads no environment variables, so the host and port are written into the client. The placeholders are literal. YOUR_SITEKEY and the page address must come from a page that really carries a reCAPTCHA v2 widget, or CapSkip answers with an error. Copy the sitekey from the page source, where it is the data-sitekey value. Step 4 reads it from the page for you. Run the file with .\\.venv\\Scripts\\python.exe first_solve.py.<\/p>\n
\n# pip install capskip\nimport asyncio\n\nfrom capskip import AsyncCapSkip\n\n\nasync def main():\n solver = AsyncCapSkip(host='127.0.0.1', port=8080)\n result = await solver.recaptcha(\n sitekey='YOUR_SITEKEY',\n url='https:\/\/example.com\/page-with-recaptcha',\n )\n print(result['code'][:30])\n\n\nasyncio.run(main())<\/pre>\n<\/div>\nStep 4: read the sitekey from the page<\/h2>\n
The sitekey is on the page, and Pydoll can read it. A normal widget is a div with the class g-recaptcha and a data-sitekey attribute. A widget that the page draws with grecaptcha.render() has no such div. It leaves an iframe whose address carries the sitekey in its k parameter. This function handles both with one selector, and the tag name tells it which one it got. Add it to solve.py above async def main().<\/p>\n
\nfrom urllib.parse import parse_qs, urlparse\n\n\nasync def find_sitekey(tab):\n # A normal widget carries data-sitekey. A widget drawn by\n # grecaptcha.render() only leaves its iframe, with k=<sitekey>.\n found = await tab.query(\n '.g-recaptcha[data-sitekey], '\n 'iframe[src*="recaptcha\/api2\/anchor"]',\n timeout=10,\n )\n if found.tag_name == 'iframe':\n src = found.get_attribute('src')\n return parse_qs(urlparse(src).query)['k'][0]\n return found.get_attribute('data-sitekey')<\/pre>\n<\/div>\nTwo Pydoll details matter here. get_attribute is a plain function, not a coroutine, so do not await it, and it returns None for a missing attribute. And query raises ElementNotFound when nothing matches. With a timeout it waits and raises WaitElementTimeout instead, which is the right choice for a widget that appears a moment after the page loads. A widget injected 3 seconds after load was found about 3 seconds later, with the 10 second timeout in find_sitekey.<\/p>\n
Step 5: solve on the same event loop<\/h2>\n
Pydoll runs on asyncio, and your solve call runs on the same loop. That makes the choice of client matter. Add this above async def main() too, and do the same for the function in Step 6.<\/p>\n
\nfrom capskip import AsyncCapSkip\n\nsolver = AsyncCapSkip(host='127.0.0.1', port=8080)\n\n\nasync def solve(sitekey, url):\n result = await solver.recaptcha(sitekey, url)\n return result['code']<\/pre>\n<\/div>\nThe sync CapSkip client would also work, but it blocks the loop for the whole solve, and Pydoll stops answering Chrome while it waits. A mock run counted how often the page answered when asked for the time every 50 milliseconds, while a 3 second mock solve ran. The longest gap is the longest time between two answers:<\/p>\n
\n\n
\n \nClient<\/th>\n Solve time<\/th>\n Counter ticks<\/th>\n Longest gap<\/th>\n<\/tr>\n<\/thead>\n \n The sync CapSkip client, called directly in the async function<\/td>\n 3.76 s<\/td>\n 5<\/td>\n 3.78 s<\/td>\n<\/tr>\n \n CapSkip in asyncio.to_thread<\/td>\n 3.76 s<\/td>\n 65<\/td>\n 0.06 s<\/td>\n<\/tr>\n \n AsyncCapSkip<\/td>\n 5.0 s<\/td>\n 68<\/td>\n 0.3 s<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n The page itself kept running in the first case. Only the Python side froze: Python cannot react to anything the page does until the solve ends, so events from a second tab are handled late. AsyncCapSkip took about a second longer here, but that depends on where its next poll falls after the solve, and with 2, 4 and 8 second mock solves it finished earlier than the thread version. What it always costs is about 0.15 seconds of blocked loop for each request, because it builds a new HTTP client every time. That still beats a frozen loop.<\/p>\n
Step 6: write the token into the page<\/h2>\n
A solved reCAPTCHA is a token. The page expects it in a textarea named g-recaptcha-response, and if the widget has a callback, the page expects the callback to run with the token. This function does both. It uses Pydoll’s execute_script and returns True when it found and ran a callback. Add it above async def main() as well.<\/p>\n
\nimport json\n\nFILL_JS = """\n(function (token) {\n var seen = new Set(), fn = null;\n document.querySelectorAll('textarea[name="g-recaptcha-response"]')\n .forEach(function (box) { box.value = token; });\n (function walk(o, depth) {\n if (!o || typeof o !== 'object' || seen.has(o) || depth > 6) return;\n seen.add(o);\n for (var k in o) {\n var v; try { v = o[k]; } catch (e) { continue; }\n if (k === 'callback' && !fn) {\n fn = typeof v === 'string' ? window[v] : v;\n }\n if (v && typeof v === 'object' && !(v instanceof Node)) {\n walk(v, depth + 1);\n }\n }\n })(window.___grecaptcha_cfg, 0);\n if (typeof fn === 'function') fn(token);\n return typeof fn === 'function';\n})(%s)\n"""\n\n\nasync def fill_token(tab, token):\n reply = await tab.execute_script(\n FILL_JS % json.dumps(token), return_by_value=True)\n outcome = reply['result']\n if 'exceptionDetails' in outcome:\n error = outcome['exceptionDetails']['exception']\n raise RuntimeError(error['description'])\n return outcome['result']['value'] # True if a callback ran<\/pre>\n<\/div>\nThe JavaScript walks Google’s own configuration object to find the callback, because the keys inside it are short names that Google can change. A data-callback attribute is stored there as the name of a function, so the walk looks the name up on window. A callback passed to grecaptcha.render() is stored as the function itself. Both cases ran against Google’s real api.js.<\/p>\n
Pydoll returns the raw DevTools reply from execute_script, so the value sits at reply[‘result’][‘result’][‘value’], and you must await the call. An object comes back as a reference unless you pass return_by_value=True. A JavaScript error does not raise in Python. It adds exceptionDetails to the reply, which is why the function checks for it and raises a RuntimeError of its own.<\/p>\n
Step 7: put it together<\/h2>\n
Delete async def main() and the asyncio.run(main()) line at the bottom of solve.py, keep the functions above them, and paste this in their place. It solves after the page has loaded, because the sitekey comes from the page, and it solves right before the token is used. If a callback ran, the page takes over. If not, the script clicks the form’s submit button and waits for the navigation.<\/p>\n
\nasync def main():\n options = ChromiumOptions()\n options.headless = True # set to False to watch the window\n async with Chrome(options=options) as browser:\n tab = await browser.start()\n await tab.go_to(PAGE)\n sitekey = await find_sitekey(tab)\n token = await solve(sitekey, await tab.current_url())\n if not await fill_token(tab, token):\n button = await tab.query('form button[type="submit"]')\n async with tab.expect_navigation():\n await button.click()\n print(await tab.title())\n\n\nasyncio.run(main())<\/pre>\n<\/div>\nOn a page where a callback does the sending, there is nothing to click. This version replaces main() the same way. What happens next depends on the page, so wait for something the page itself changes. This version waits for a result element on the test page to change from waiting to something else. Change the selector to whatever your page updates.<\/p>\n
\nasync def main():\n options = ChromiumOptions()\n options.headless = True # set to False to watch the window\n async with Chrome(options=options) as browser:\n tab = await browser.start()\n await tab.go_to(PAGE)\n sitekey = await find_sitekey(tab)\n token = await solve(sitekey, await tab.current_url())\n if await fill_token(tab, token):\n # The page's own callback takes over. What it does next is\n # page specific: this page writes its answer into #result.\n await tab.wait_for_script(\n "var r = document.querySelector('#result');"\n "return r && r.textContent !== 'waiting';"\n )\n print(await (await tab.query('#result')).text())\n\n\nasyncio.run(main())<\/pre>\n<\/div>\nThe whole script<\/h2>\n
Here is solve.py in one piece, with every import at the top. It replaces the blocks you added one by one, so delete those first. Run on the plain form page, it printed Welcome and the page accepted the token once. On a page whose callback does the sending, this version can print the old title before the page changes, so use the callback variant above there.<\/p>\n
\n# pip install pydoll-python capskip\nimport asyncio\nimport json\nfrom urllib.parse import parse_qs, urlparse\n\nfrom capskip import AsyncCapSkip\nfrom pydoll import Chrome\nfrom pydoll.browser.options import ChromiumOptions\n\nPAGE = 'https:\/\/example.com\/page-with-recaptcha'\n\nsolver = AsyncCapSkip(host='127.0.0.1', port=8080)\n\n# Put the token in every response box, then run the page's callback.\nFILL_JS = """\n(function (token) {\n var seen = new Set(), fn = null;\n document.querySelectorAll('textarea[name="g-recaptcha-response"]')\n .forEach(function (box) { box.value = token; });\n (function walk(o, depth) {\n if (!o || typeof o !== 'object' || seen.has(o) || depth > 6) return;\n seen.add(o);\n for (var k in o) {\n var v; try { v = o[k]; } catch (e) { continue; }\n if (k === 'callback' && !fn) {\n fn = typeof v === 'string' ? window[v] : v;\n }\n if (v && typeof v === 'object' && !(v instanceof Node)) {\n walk(v, depth + 1);\n }\n }\n })(window.___grecaptcha_cfg, 0);\n if (typeof fn === 'function') fn(token);\n return typeof fn === 'function';\n})(%s)\n"""\n\n\nasync def find_sitekey(tab):\n # A normal widget carries data-sitekey. A widget drawn by\n # grecaptcha.render() only leaves its iframe, with k=<sitekey>.\n found = await tab.query(\n '.g-recaptcha[data-sitekey], '\n 'iframe[src*="recaptcha\/api2\/anchor"]',\n timeout=10,\n )\n if found.tag_name == 'iframe':\n src = found.get_attribute('src')\n return parse_qs(urlparse(src).query)['k'][0]\n return found.get_attribute('data-sitekey')\n\n\nasync def solve(sitekey, url):\n result = await solver.recaptcha(sitekey, url)\n return result['code']\n\n\nasync def fill_token(tab, token):\n reply = await tab.execute_script(\n FILL_JS % json.dumps(token), return_by_value=True)\n outcome = reply['result']\n if 'exceptionDetails' in outcome:\n error = outcome['exceptionDetails']['exception']\n raise RuntimeError(error['description'])\n return outcome['result']['value'] # True if a callback ran\n\n\nasync def main():\n options = ChromiumOptions()\n options.headless = True # set to False to watch the window\n async with Chrome(options=options) as browser:\n tab = await browser.start()\n await tab.go_to(PAGE)\n sitekey = await find_sitekey(tab)\n token = await solve(sitekey, await tab.current_url())\n if not await fill_token(tab, token):\n button = await tab.query('form button[type="submit"]')\n async with tab.expect_navigation():\n await button.click()\n print(await tab.title())\n\n\nasyncio.run(main())<\/pre>\n<\/div>\nSolve two tabs at once<\/h2>\n
Two tabs can solve at the same time with asyncio.gather. Two 3 second solves started together finished together in under 4 seconds, with different tokens. The trap is cookies. Tabs in the default browser context share one cookie jar, so the second page load can replace the session or CSRF cookie that the first tab is about to submit with. The mock site sets a new session cookie on every page load, as some real sites do, so the second load replaced the first tab’s cookie and one of two simultaneous submits was rejected. Giving each tab its own browser context fixed it, and both submits were accepted. This version replaces main() the same way, and it clicks submit, so it suits a plain form.<\/p>\n
\nasync def solve_page(tab):\n sitekey = await find_sitekey(tab)\n token = await solve(sitekey, await tab.current_url())\n await fill_token(tab, token)\n button = await tab.query('form button[type="submit"]')\n async with tab.expect_navigation():\n await button.click()\n return await tab.title()\n\n\nasync def main():\n options = ChromiumOptions()\n options.headless = True\n async with Chrome(options=options) as browser:\n await browser.start()\n # One browser context per tab: tabs in the default context\n # share cookies, and a second page load can replace the first\n # tab's session or CSRF cookie.\n contexts = [await browser.create_browser_context() for _ in range(2)]\n tabs = [\n await browser.new_tab(PAGE, browser_context_id=context)\n for context in contexts\n ]\n print(await asyncio.gather(*[solve_page(tab) for tab in tabs]))\n for context in contexts:\n await browser.delete_browser_context(context)\n\n\nasyncio.run(main())<\/pre>\n<\/div>\nRun Pydoll against CapSkip on another machine<\/h2>\n
Pydoll and the solver do not have to share a PC. Switch CapSkip to Server mode under connection settings, and it listens on your network address or public IP. A static public IP is recommended for stable remote access. Then only the client line changes. The solver is still your own Windows machine, and solves are still unmetered.<\/p>\n
\n# CapSkip on another Windows PC, in Server mode\nsolver = AsyncCapSkip(\n host='192.168.1.50', # that PC's network address\n port=8080,\n apiKey='YOUR_API_KEY', # only if API key validation is on\n)<\/pre>\n<\/div>\nMind two things. The SDK talks to CapSkip over plain HTTP, so the API key travels in clear text. Keep that link on a private network or a VPN, and turn on API key validation. And CapSkip opens its port to every address when Server mode starts, so a Windows Firewall block rule for the addresses you do not expect is the way to narrow it. With AsyncCapSkip, an unreachable address fails after about 5 seconds with a NetworkException that has an empty message. The remote setup was not run for this guide, only the constructor was read.<\/p>\n
Timeouts and what a failure looks like<\/h2>\n
Solve, then submit, quickly. A reCAPTCHA token works once and expires, so solve after the page has loaded and just before you submit. The strict mock site refused a second submit of the same token with a 403, which is the mock’s own rule. The page on reCAPTCHA token expiration<\/a> has the timing. Here is what each failure looked like with AsyncCapSkip and the default settings, against the mock:<\/p>\n