需要本机已有可用的 Chrome 浏览器,包本身不带浏览器;Docker 部署需另用 cdpdriver/zendriver-docker 模板且仅支持 Linux;按文本查找默认取第一个匹配,需 best_match 才按文本长度择优
zendriver
cdpdriverAGPL-3.0活跃维护基于 Chrome DevTools 协议的异步网页抓取与自动化框架,能绕过 Cloudflare 等反爬检测,适合需要隐蔽采集的场景。
A blazing fast, async-first, undetectable webscraping/web automation framework based on ultrafunkamsterdam/nodriver. Now with Docker support!
pip install zendriverREADME 未说明具体硬件要求;需本机安装 Chrome 浏览器,Docker 方案需 Linux 且可 GPU 加速运行非 headless Chrome
基于 CDP 的异步浏览器自动化框架,绕过 Selenium 检测,几行 Python 完成抓取
基于 Chrome DevTools 协议的异步网页抓取与自动化框架,能绕过 Cloudflare 等反爬检测,适合需要隐蔽采集的场景。
核心能力
- 用 Chrome DevTools Protocol 驱动真实浏览器,不走 WebDriver
- 全异步 Python API,启动和页面操作都基于 asyncio
- 默认每次运行使用全新 profile,退出时自动清理
- 支持按选择器或文本查找元素,可穿透 iframe 内容
- 元素 repr 直接输出 HTML,便于调试
容易踩的坑
- v0.17.1最新正式版2026-10-02 · 2026-10-02 02:07 UTC
Fixed
- The "Failed to connect to browser" error now suggests
sandbox=Falseinstead ofno_sandbox=True, which isn't a real option and was silently ignored Tab.wait_for_ready_statenow respectstimeouteven when adocument.readyStatecheck never gets a response, instead of hanging forever
- The "Failed to connect to browser" error now suggests
- v0.17.02026-09-27 · 2026-09-27 02:34 UTC
查看更新说明
This is quite a large release, including a number of fixes from first-time contributors (thank you!) as well as ports for all
nodriverfeatures and bugfixes that have been added upstream since Zendriver was forked. Additionally, I've managed to remove the last remaining# type: ignorecomments, which uncovered a few additional bugs that have also been fixed in this release.This release marks two years of Zendriver! Huge thanks to everyone that has contributed so far.
Fixed
- Fix
ValueErroron startup when thelangoption is set @bercedev - Fix
verify_cf()never clicking the Turnstile checkbox on Turnstile markup where thecf-turnstile-response/cf_challenge_responseinput is rendered as a document-level sibling of the challenge's shadow-DOM host rather than nested inside it. The lookup was scoped tohost_element, always found nothing, andverify_cf()returned before ever callingmouse_click. Now queries the input from the document (tab.query_selector) instead. @A-Nolan - Fix HTTP method casing to resolve CDP connection issues on some Windows installations @fitudao3788
- Fix
404 Not FoundWebSocket connection error foriframetargets by routing all target connections to/devtools/page/<target_id>inBrowser._handle_target_update. - Fix
Browser.stop()always waiting 3 seconds and then force-killing the browser process, even when the browser had already exited gracefully. The exit check readPopen.returncode, which is only updated bypoll()/wait(). @stephanlensky - Fix
Browser.start()always sleeping forbrowser_connection_timeoutbefore the first connection attempt. It now tries to connect immediately and only waits between retries. @stephanlensky - Fix
Browserinstances never being garbage collected afterBrowser.stop(). The asyncio atexit callback and the global registered instances set kept a reference to every browser, and per-target connections were left open. @stephanlensky - Fix the connection listener crashing with
InvalidStateErrorwhen a response arrived for a command that was already cancelled (for example byasyncio.wait_for), which left later commands hanging forever @stephanlensky - Fix every received CDP event being kept in memory for the lifetime of its connection @stephanlensky
- Fix
Tab.find()raisingProtocolException: No search session with given id foundinstead of retrying when the page's document is replaced during the search @stephanlensky - Fix
await tabraisingValueError: No listener created yeton a tab which no commands were sent to yet, such as one just opened withbrowser.get(url, new_tab=True)@stephanlensky - Fix
browser.get(url, new_tab=True)intermittently raisingStopIterationwhen the new tab was not registered yet, andbrowser.get()returning before the navigation when another target changed in the meantime @stephanlensky - Fix Widevine DRM being unavailable on platforms where Chrome installs it through the component updater, such as Windows. Removed the
--disable-component-update,--disable-background-networking,--disable-backgrounding-occluded-windowsand--disable-renderer-backgroundingdefault browser arguments @stephanlensky - Fix
Browser.start()sometimes returning before the browser's initial tab was registered, which madebrowser.get(url)raiseRuntimeError: coroutine raised StopIteration.browser.get(url)now raises a descriptive error if there is no tab to navigate @stephanlensky - Fix extensions added with
Config.add_extension()not loading on Chrome 137+. The default--disable-featuresswitch was overridden by a second one, since Chrome only uses the last. All--disable-featuresswitches, including user-provided ones, are now merged into one, and--enable-unsafe-extension-debuggingis passed when extensions are added @stephanlensky - Fix commands hanging forever when the browser connection closed while they were waiting for a response, for example because the browser crashed or `Co
- Fix
- v0.16.02026-08-16 · 2026-08-16 23:21 UTC
查看更新说明
Fixed
- Fix
patternargument inCookieJar.save@Lyesbcb
Added
- Add support for Microsoft Edge browser @mokurin000
- Fix
- v0.15.52026-07-15 · 2026-07-15 22:00 UTC
查看更新说明
Fixed
- Fix
SyntaxErroron Python 3.14 inConnection._register_handlers. PEP 765 makescontinue/break/returnthat exits afinallyblock aSyntaxError(was aSyntaxWarningin 3.13), sozendriver/core/connection.pyfailed to import under 3.14. Removed the no-opfinally: continue(the loop already falls through to the next iteration, and the enclosing bareexcept:catches everything, so nothing changed behaviorally). Fixes #252
- Fix
- v0.15.42026-06-27 · 2026-06-27 18:05 UTC
查看更新说明
Fixed
- Fix
query_selector_allandselect_all(include_frames=True)not searching nested iframes. CDP'squerySelectorAllonly queries within a single document boundary, so elements inside nested iframes were never found. Now walks the full DOM tree to collect each iframe'scontent_documentand queries them individually. Also adds a guard for cross-origin iframes wherecontent_documentisNone. @chronoAP - Fix
Connection._register_handlersreenabling already manually enabled domains @S-Tarr - Fix flakey behavior in
api-reponses-tutorial-2tutorial @S-Tarr
Changed
- Updated CDP models @nathanfallet
- Fix
用户点评
登录用户的真实使用记录,可按版本和硬件筛选还没有人点评。第一个说出真实体验的人最有价值。
Zendriver ✌️
This package is a fork of
ultrafunkamsterdam/nodriver, created to add new features, compile unmerged bugfixes, and increase community engagement.
- Documentation: zendriver.dev
- AI-generated wiki: deepwiki.com/cdpdriver/zendriver
Zendriver is a blazing fast, async-first, undetectable webscraping/web automation framework implemented using the Chrome Devtools Protocol. Visit websites, scrape content, and run JavaScript using a real browser (no Selenium/Webdriver) all with just a few lines of Python.
Docker support is here! Check out cdpdriver/zendriver-docker for an example of how to run Zendriver with a real, GPU-accelerated browser (not headless) in a Docker container. (Linux-only)
Features
- Undetectable - Zendriver uses the Chrome Devtools Protocol instead of Selenium/WebDriver, making it (almost) impossible to detect
- Blazing fast - Chrome Devtools Protocol is fast, much faster than previous Selenium/WebDriver solutions. CDP combined with an async Python API makes Zendriver highly performant.
- Feature complete and easy to use - Packed with allowing you to get up and running in just a few lines of code.
- First-class Docker support - Traditionally, browser automation has been incredibly difficult to package with Docker, especially if you want to run real, GPU-accelerated Chrome (not headless). Now, deploying with Docker is easier than ever using the officially supported zendriver-docker project template.
- Automatic cookie and profile management - By default, uses fresh profile on each run, cleaning up on exit. Or, save and load cookies to a file to avoid repeating tedious login steps.
- Smart element lookup - Find elements selector or text, including iframe content. This could also be used as wait condition for a element to appear, since it will retry for the duration of
timeoutuntil found. Single element lookup by text usingtab.find()accepts abest_match flag, which will not naively return the first match, but will match candidates by closest matching text length. - Easy debugging - Descriptive
reprfor elements, which represents the element as HTML, makes debugging much easier.
Installation
To install, simply use pip (or your favorite package manager):
pip install zendriver
# or uv add zendriver, poetry add zendriver, etc.
Usage
Example for visiting https://www.browserscan.net/bot-detection and saving a screenshot of the results:
import asyncio
import zendriver as zd
async def main():
browser = await zd.start()
page = await browser.get("https://www.browserscan.net/bot-detection")
await page.save_screenshot("browserscan.png")
await browser.stop()
if __name__ == "__main__":
asyncio.run(main())
Check out the Quickstart for more information and examples.
Rationale for the fork
Zendriver remains committed to nodriver's goals of staying undetected for all modern anti-bot solutions and also keeps with the batteries-included approach of its predecessor. Unfortunately, contributions to the original nodriver repo are heavily restricted, making it difficult to submit issues or pull requests. At the time of writing, there are several pull requests open to fix critical bugs which have beeen left unaddressed for many months.
Zendriver aims to change this by:
- Including open pull requests in the original
nodriverrepo as part of the initial release - Modernizing the development process to include static analysis tools such as
ruffandmypy, reducing the number of easy-to-catch bugs which make it through in the future - Opening up the issue tracker and pull requests for community contributions, allowing the project to continue to grow along with its community.
With these changes in place, we hope to further development of state-of-the-art open-source web automation tools even further, helping to once again make the web truly open for all.
Contributing
Contributions of all types are always welcome! Please see CONTRIBUTING.md for details on how to contribute.
Getting additional help
If you have a question, bug report, or want to make a general inquiry about the project, please create a new GitHub issue. If you are having a problem with Zendriver, please make sure to include your operating system, Chrome version, code example demonstrating the issue, and any other information that may be relevant.
Questions directed to any personal accounts outside of GitHub will be ignored.