Nodriver

0.48.1 · active · verified Thu Apr 16

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.

Common errors

```
ImportError: cannot import name 'nodriver' from 'nodriver'
```
cause 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>)]
```
cause 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
```
cause 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'
```
cause 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
```
cause 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())`.

Warnings

gotcha Naming 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`).
gotcha Using `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.
breaking Headless 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.
gotcha Nodriver 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.
gotcha The `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()`.

Install

pip install nodriver Install nodriver

Imports

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.

Quickstart

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())

view raw JSON →