Installation

Install nodriver and set up your environment for browser automation

Prerequisites

Before installing nodriver, ensure you have:

1. Python 3.9 or higher

   nodriver requires Python 3.9 or later. Check your version:

   python --version
   
2. A Chromium-based browser

   You need Chrome, Chromium, Edge, or Brave installed on your system, preferably in the default location.

   nodriver will automatically locate your browser in most cases. You can specify a custom path if needed.

Install with pip

The easiest way to install nodriver is using pip:

pip install nodriver

It’s recommended to use a virtual environment to avoid dependency conflicts:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install nodriver

Update to the latest version

To update nodriver to the latest version:

pip install -U nodriver

Dependencies

nodriver has minimal dependencies that will be installed automatically:

• mss - For screen capture functionality
• websockets (>=14) - For CDP communication
• deprecated - For deprecation warnings

Optional dependencies

For additional features, you may want to install:

opencv-python (for Cloudflare verification)

Required for the tab.cf_verify() method to work:

pip install opencv-python

Development dependencies

If you’re contributing to nodriver:

pip install nodriver[dev]

This includes: black, build, isort, sphinx, and other development tools.

Installation for headless environments

If you’re running nodriver on a server or in a Docker container without a display, you have two options:

Headless mode

Run nodriver in headless mode (no visible browser window):

import nodriver as uc

async def main():
    browser = await uc.start(headless=True)
    # Your code here

uc.loop().run_until_complete(main())

Headless mode may be more detectable by anti-bot systems. Use with caution.

Virtual display (Xvfb)

Use Xvfb to emulate a screen on headless servers:

Install Xvfb:

# Debian/Ubuntu
apt-get install xvfb

# Red Hat/CentOS
yum install xorg-x11-server-Xvfb

Run your script with Xvfb:

xvfb-run python your_script.py

Or in Python:

from xvfbwrapper import Xvfb

with Xvfb():
    # Your nodriver code here
    pass

Docker installation

For Docker environments, here’s a sample Dockerfile:

FROM python:3.11-slim

# Install Chrome
RUN apt-get update && apt-get install -y \
    wget \
    gnupg \
    && wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
    && echo "deb http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list \
    && apt-get update \
    && apt-get install -y google-chrome-stable \
    && rm -rf /var/lib/apt/lists/*

# Install nodriver
RUN pip install nodriver

# Copy your script
COPY your_script.py .

CMD ["python", "your_script.py"]

Verify installation

Verify that nodriver is installed correctly:

import nodriver as uc

print(f"nodriver version: {uc.__version__}")

Or run a quick test:

import nodriver as uc

async def test():
    browser = await uc.start()
    tab = await browser.get('https://www.google.com')
    print(f"Page title: {await tab.get_title()}")
    browser.stop()

uc.loop().run_until_complete(test())

If this runs without errors and prints a page title, you’re all set!

Troubleshooting

Browser not found

If nodriver can’t find your browser, specify the path manually:

browser = await uc.start(
    browser_executable_path="/path/to/chrome"
)

Permission errors

On Linux/Mac, you may need to make the browser executable:

chmod +x /path/to/chrome

Port already in use

If you get a port conflict error, nodriver will usually find another port automatically. If issues persist, you can specify a port:

from nodriver import Config

config = Config()
config.port = 9223  # Use a different port
browser = await uc.start(config=config)

Websockets connection failed

Ensure you have websockets version 14 or higher:

pip install --upgrade websockets

Next steps

Quickstart guide

Now that you have nodriver installed, learn how to build your first automation script