nodriver

library0.50.3pypypi✓ verified 84d ago

Nodriver is a Python library for browser automation and web scraping, acting as the official successor to Undetected-Chromedriver. It communicates directly with browsers using the Chrome DevTools Protocol, eliminating the need for Selenium or WebDriver binaries, which significantly boosts performance and resistance against anti-bot systems. It is fully asynchronous and focuses on usability and quick prototyping. The current version is 0.48.1, and it seems to have a regular update cadence given the recent articles and version number.

http-networking web-framework

pip install nodriver

github ↗package ↗

INSTALL

IMPORT

SIG · NODRIVER

nodriver

http-networkingpythonv0.50.3

Install

2.5s avg

Import

1631ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.50.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.356s · 23.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.5s · import 1.254s · 24MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

nodriver

✓ import nodriver

The common alias 'uc' (from undetected-chromedriver) is also frequently used: `import nodriver as uc`.

ProtocolException

✓ from nodriver import ProtocolException

Used for handling errors specific to the Chrome DevTools Protocol.

Config

✓ from nodriver import Config

For custom browser configurations, such as executable path or user data directory.

cdp

✓ from nodriver import cdp

For direct interaction with Chrome DevTools Protocol domains and methods.

This quickstart demonstrates how to launch a headless browser, navigate to a URL, retrieve the page title, and then close the page and browser instance. Nodriver operations are asynchronous and require `async`/`await`.

import nodriver import asyncio async def main(): browser = await nodriver.start(headless=True) page = await browser.get('https://example.com') print(f"Page title: {await page.get_title()}") await page.close() await browser.stop() if __name__ == '__main__': nodriver.loop().run_until_complete(main())

Debug

Known issues

gotchaNaming your Python script `nodriver.py` can cause an `ImportError` because Python may try to import your local file instead of the installed package.

fix

Rename your Python script file to something other than `nodriver.py` (e.g., `my_scraper.py`).

affects: All versions

gotchaUsing `asyncio.run()` directly to execute your main asynchronous function can sometimes lead to unexpected behavior with `nodriver`'s event loop management.

fix

It is recommended to use `nodriver.loop().run_until_complete(main())` to ensure proper event loop handling and browser lifecycle management.

affects: All versions

breakingHeadless mode (`headless=True`) can sometimes trigger anti-bot detection or lead to `ERR_HTTP2_PROTOCOL_ERROR` on certain websites, especially compared to headed mode.

fix

If encountering issues in headless mode, try running with `headless=False`. Also, consider adjusting browser arguments via `nodriver.Config` to better mimic human browsing patterns if stealth is critical.

affects: All versions

gotchaNodriver can fail to connect to Chrome (e.g., `ClientConnectorError`) if the Chrome profile is locked by another process or if the debugging port is slow to open, particularly on macOS or when using existing profiles.

fix

Use a dedicated `user_data_dir` for `nodriver` (e.g., `Config(user_data_dir='path/to/nodriver_profile')`), increase the startup timeout for `nodriver.start(timeout=...)`, and ensure no orphaned Chrome processes are running before starting the script.

affects: All versions

gotchaThe `tab.cf_verify()` method for Cloudflare bypass only works when the browser is NOT started in 'expert' mode and requires the `opencv-python` package to be installed.

fix

Ensure `opencv-python` is installed (`pip install opencv-python`) and avoid setting `expert=True` in `nodriver.start()` if you intend to use `cf_verify()`.

affects: All versions

Errors

Common errors & fixes

ImportError: cannot import name 'nodriver' from 'nodriver'

Your Python script file is named `nodriver.py`, causing a conflict with the installed package.

fix

Rename your Python script file to anything other than `nodriver.py` (e.g., `main.py`, `scraper.py`).

aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host localhost:<port> [Connect call failed ('127.0.0.1', <port>)]

Nodriver failed to establish a connection to the Chrome DevTools Protocol. This often occurs if Chrome is already running and locking its profile, if Chrome takes too long to launch, or if background Chrome processes are interfering.

fix

Try killing any lingering Chrome processes, increase the startup timeout for `nodriver.start(timeout=...)`, or configure a dedicated user data directory for `nodriver` to prevent profile locking issues via `nodriver.Config(user_data_dir='path/to/new_profile')`.

nodriver.ProtocolException: No node with given id found

A Chrome DevTools Protocol command failed because a specified element (node_id, selector) could not be found or was invalid at the time of the command execution.

fix

Ensure that the element you are trying to interact with exists on the page when the command is called. Use `await page.wait_for_selector('selector')` or appropriate waits before interaction, and double-check your selectors or node IDs.

FileNotFoundError: [Errno 2] No such file or directory: '/invalid/path/to/chrome'

Nodriver could not find the Chrome/Chromium executable at the specified `browser_executable_path` in `Config` or in common system locations.

fix

Verify that Chrome/Chromium is installed and accessible. If you've provided a custom path, ensure it's correct. If not provided, ensure Chrome is installed in a default location `nodriver` can detect.

RuntimeError: Cannot run Browser.get() outside of async context

Nodriver functions that involve browser interaction (like `browser.get()` or `uc.start()`) must be called within an `async` function and executed via an `asyncio` event loop.

fix

Ensure all `nodriver` calls are correctly `await`ed within `async` functions, and the main entry point is executed using `nodriver.loop().run_until_complete(main())`.

Upgrade

Version history

0.50.3latest on PyPI · released May 13, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.9 or higher.

chrome-based browserrequiredRequires a local installation of Chrome, Chromium, or Brave for automation.

opencv-pythonoptionalRequired for the `tab.cf_verify()` method to bypass Cloudflare Captchas.

Agent activity

73 hits · last 30 days

node

Resources

githubhttps://github.com/UltrafunkAmsterdam/nodriver ↗

packagehttps://pypi.org/project/nodriver/ ↗