A nodriver captcha step is the usual three moves: read the sitekey off the page, send it to a solver, write the token back with JavaScript. What changes is that nodriver is asynchronous all the way down. It drives Chrome over an asyncio websocket, so a blocking solve does not just make your script wait, it stalls the socket that carries every DevTools message. Pair it with the async client and the whole thing stays responsive.<\/p>\n
# Both packages, one line.\npip install nodriver capskip<\/pre>\n<\/div>\nWhy nodriver changes the shape of this<\/h2>\n
nodriver is the official successor to undetected-chromedriver, written by the same author, and its headline is that there is no webdriver and no Selenium anywhere in the stack. It speaks the DevTools Protocol to a browser it launched itself. No chromedriver binary to patch, no driver version to keep in step with Chrome.<\/p>\n
The part that matters for CAPTCHA work is the second half of that sentence: it is fully asynchronous. The connection is a websocket handled by asyncio, and a background task reads protocol messages off it. Every element lookup, every navigation and every event handler depends on that task getting scheduled. Call a synchronous solver in the middle and nothing else in the process runs for the length of the solve, which for reCAPTCHA v2 is routinely fifteen to forty-five seconds.<\/p>\n
So the rule for this framework is short. Use the async client, and await it.<\/p>\n
One thing worth being straight about: no webdriver does not mean no detection. Removing the driver removes one signal and leaves the rest of your fingerprint where it was. Solving a challenge and looking like a browser are separate jobs, and this post covers the first.<\/p>\n
Step 1: read the sitekey off the page<\/h2>\n
The sitekey lives on the host document, not inside the widget iframe. Google’s markup puts it on a container as a data-sitekey attribute, and nodriver’s select method finds that container by CSS selector. Watch the bracket access on the last line, because it is the thing that catches people out.<\/p>\n
\n# pip install nodriver\nimport nodriver as uc\n\nasync def main():\n browser = await uc.start()\n page = await browser.get("https:\/\/example.com\/page-with-recaptcha")\n\n # select() retries for 10 seconds by default, so it doubles\n # as a wait condition for a widget that renders late.\n holder = await page.select("div.g-recaptcha")\n sitekey = holder.attrs["data-sitekey"]\n\n print(sitekey) # 6Lxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\nuc.loop().run_until_complete(main())<\/pre>\n<\/div>\nAttribute names are stored on the element exactly as the HTML spelled them, hyphens included, so bracket access is the only reliable way to read one. The dotted shortcut looks like it should work and quietly does not: asking an element for data_sitekey hands back None rather than raising, because that lookup falls through to a default. The None then travels to the solver as an empty key and surfaces much later as ERROR_GOOGLEKEY<\/a>, a long way from the line that caused it. There is exactly one real rename to know about, which is that the class attribute is stored under class_ to keep it off the Python keyword.<\/p>\n
Some sites never expose the sitekey on the host page and only pass it in the widget iframe URL. Read it from the query string instead.<\/p>\n
\n# Fallback: the k= parameter on the anchor iframe.\nfrom urllib.parse import urlparse, parse_qs\n\nframe = await page.select("iframe[src*='recaptcha\/api2\/anchor']")\nsitekey = parse_qs(urlparse(frame.attrs["src"]).query)["k"][0]<\/pre>\n<\/div>\nStep 2: solve it without stalling the socket<\/h2>\n
The Python SDK ships two clients. CapSkip is synchronous and AsyncCapSkip is a genuine asyncio implementation rather than an alias, which is exactly what this framework needs. Both talk to the solver on your own machine on port 8080, and neither bills per solve.<\/p>\n
\n# pip install capskip\nfrom capskip import AsyncCapSkip\n\nsolver = AsyncCapSkip(host="127.0.0.1", port=8080)\n\n# Same call shape for v3 (version="v3") and Enterprise\n# (enterprise=1). Invisible v2 takes invisible=1.\nresult = await solver.recaptcha(sitekey=sitekey, url=PAGE_URL)\n\ntoken = result["code"] # the g-recaptcha-response value<\/pre>\n<\/div>\nBecause the call is awaitable, several tabs can solve at once without any threading. Open the pages, gather the solves, then inject each token into the tab it belongs to. The wider pattern, including how the SDK backs its polling off instead of sleeping on a flat interval, is covered in solving CAPTCHAs in parallel<\/a>.<\/p>\n
\n# Three tabs, three solves, one wait.\nimport asyncio\n\nresults = await asyncio.gather(*[\n solver.recaptcha(sitekey=k, url=u) for k, u in targets\n])<\/pre>\n<\/div>\nTurnstile and GeeTest have their own methods, and both take the same shape as the call above. Full parameter lists for each are in the CapSkip API documentation<\/a>.<\/p>\n
Step 3: inject the token and submit<\/h2>\n
The response textarea is hidden with display:none, so typing into it is not an option in any automation tool. You write it with JavaScript. nodriver’s evaluate method takes an expression string with no way to pass arguments alongside it, so the token has to be embedded in that string, and the safe way to do that is json.dumps rather than an f-string. A JSON string literal is a valid JavaScript string literal, quoting and escaping included.<\/p>\n
\n# json.dumps gives a correctly quoted JS string literal.\nimport json\n\nawait page.evaluate(\n "document.getElementById('g-recaptcha-response').value = "\n + json.dumps(token)\n)\n\n# Then submit the form the way the page expects.\nbutton = await page.select("button[type=submit]")\nawait button.click()<\/pre>\n<\/div>\nChecking that the value landed has a trap of its own, and it is worth ten seconds of your attention. With return_by_value set, evaluate only hands back the plain Python value when that value is truthy. An empty string or a zero falls through and you get a protocol object instead. So do not read the length and test it, because a length of zero is the exact case you are trying to detect. Return something that can never be falsy.<\/p>\n
\n# String() keeps a zero-length answer truthy, so the check\n# reports the real number instead of a protocol object.\nlength = await page.evaluate(\n "String(document.getElementById('g-recaptcha-response').value.length)",\n return_by_value=True,\n)\nprint(length) # "0" means the injection did not land<\/pre>\n<\/div>\nIf the site defines a callback instead of reading the textarea on submit, call it after setting the value. The function name is site-specific, so read it out of the page’s own markup rather than guessing. This is still ordinary reCAPTCHA v2 either way: the callback changes how you hand the token over, not how it gets solved. The reCAPTCHA v2 solver page<\/a> covers both submission styles.<\/p>\n
Full working example<\/h2>\n
Everything above in one script. The solver is created once and reused, and the browser is stopped in a finally block so a failed solve does not leave a Chrome process behind.<\/p>\n
\n# pip install nodriver capskip\nimport json\nimport nodriver as uc\nfrom capskip import AsyncCapSkip\n\nPAGE_URL = "https:\/\/example.com\/page-with-recaptcha"\n\nasync def main():\n solver = AsyncCapSkip(host="127.0.0.1", port=8080)\n browser = await uc.start()\n try:\n page = await browser.get(PAGE_URL)\n\n holder = await page.select("div.g-recaptcha")\n sitekey = holder.attrs["data-sitekey"]\n if not sitekey:\n raise RuntimeError("Widget found but data-sitekey was empty.")\n\n result = await solver.recaptcha(sitekey=sitekey, url=PAGE_URL)\n await page.evaluate(\n "document.getElementById('g-recaptcha-response').value = "\n + json.dumps(result["code"])\n )\n\n button = await page.select("button[type=submit]")\n await button.click()\n await page.sleep(2)\n\n print(page.target.url) # the page you land on after submitting\n finally:\n browser.stop()\n\nuc.loop().run_until_complete(main())<\/pre>\n<\/div>\nRunning the solver on another machine<\/h2>\n
nodriver ends up on a server sooner or later, and it has two needs there: a Chromium binary, and a desktop session for Chrome to draw on. Headless mode is off by default, so a server without one needs headless switched on explicitly. The solver does not have to make that trip with it.<\/p>\n
CapSkip has two connection modes. Local binds to 127.0.0.1 and answers only that device, which is the right setting while you are writing the script. Server binds to your network or public IP, so a scraping VM, a container host or a second workstation calls the same solver over the API. A static public IP keeps that address stable. Nothing in the code changes except the host you pass in, and nothing about the cost changes either, because it is still your hardware.<\/p>\n
\n# Same SDK, same call. Only the host moves.\nsolver = AsyncCapSkip(host="10.0.0.12", port=8080, apiKey="YOUR_API_KEY")<\/pre>\n<\/div>\nTurn on key validation once the solver listens on a network address, and give each machine its own key so one can be revoked without touching the rest. The setup guide<\/a> walks through both modes.<\/p>\n
One naming collision to keep straight while you do that. nodriver’s own start function also accepts a host and a port, and those describe a Chrome debugging endpoint you want to attach to, not the solver. Supply both and nodriver will not launch a browser at all. The solver address belongs to the client constructor and nowhere else.<\/p>\n
Common errors and what they mean<\/h2>\n
\n\n
\n \nWhat you see<\/th>\n Cause<\/th>\n Fix<\/th>\n<\/tr>\n<\/thead>\n \n AttributeError on an attrs lookup<\/td>\n select() found nothing and handed back None<\/td>\n Widen the selector, or raise the select timeout<\/td>\n<\/tr>\n \n Sitekey is None with no error at all<\/td>\n Dotted access cannot reach a hyphenated attribute<\/td>\n Read it from attrs with bracket access<\/td>\n<\/tr>\n \n ERROR_GOOGLEKEY<\/td>\n An empty sitekey reached the solver<\/td>\n Check the value before spending a solve on it<\/td>\n<\/tr>\n \n The script hangs for the whole solve<\/td>\n A synchronous client blocked the event loop<\/td>\n Use AsyncCapSkip and await the call<\/td>\n<\/tr>\n \n NetworkException<\/td>\n CapSkip is not running, or the host is wrong<\/td>\n Start the app, or point host at the server address<\/td>\n<\/tr>\n \n TimeoutException<\/td>\n The solve outlasted recaptchaTimeout<\/td>\n Raise it above the default 300 seconds<\/td>\n<\/tr>\n \n evaluate returns an object, not a string<\/td>\n The value was falsy, so the plain return was skipped<\/td>\n Wrap the length in String(), not the value itself<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n FAQ<\/h2>\n
\n\n
Can I keep the synchronous client if I only solve once?<\/h3>\n<\/summary>\n
You can, and on a short script you may never notice. What you are trading away is every protocol message that arrives during the solve: navigation events, load events, anything an event handler was waiting for. On a long run that shows up as lookups timing out for no visible reason. The async client costs one import and one await, so there is not much reason to take the trade.<\/p>\n<\/details>\n
\n\n
Do I need to enter the reCAPTCHA iframe?<\/h3>\n<\/summary>\n
No, and this is the part people over-engineer. The checkbox lives in an iframe, but the sitekey attribute and the hidden response textarea both belong to the host document. You only touch a frame when the site withholds the sitekey from the page and you have to read it out of the frame’s own URL.<\/p>\n<\/details>\n
\n\n
I am migrating from undetected-chromedriver. What carries over?<\/h3>\n<\/summary>\n
The three moves carry over unchanged, because they were never driver-specific: read the sitekey, solve it, write the token into the textarea. What does not carry over is the API around them, since every call is now awaitable and there is no driver object. nodriver also ships a helper that converts a running undetected-chromedriver instance into a browser object, which lets you move a script in stages. The older approach is written up in the undetected-chromedriver CAPTCHA guide<\/a>.<\/p>\n<\/details>\n
\n\n
My scraper runs on a VPS. Where does the solver go?<\/h3>\n<\/summary>\n
Wherever you like, as long as the two can reach each other. Server mode makes the solver listen on a network address instead of the loopback address, so the VPS calls it over the API exactly as it would any internal service. Point the host argument at that address, enable key validation, and give the VPS its own key. The solver needs no display, which is convenient given that the browser does.<\/p>\n<\/details>\n
The short version<\/h2>\n
Read the sitekey with bracket access on attrs, solve it with AsyncCapSkip on 127.0.0.1:8080, inject the token through evaluate with json.dumps, then submit. Await everything, because a synchronous solve holds the socket that drives the browser. For the wider Python picture, including Selenium and Playwright, see the Python CAPTCHA solver page<\/a>.<\/p>\n