Skip to main content

​
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:
Required for the tab.cf_verify() method to work:
pip install opencv-python
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:
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.

​
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

If nodriver can’t find your browser, specify the path manually:
browser = await uc.start(
    browser_executable_path="/path/to/chrome"
)
On Linux/Mac, you may need to make the browser executable:
chmod +x /path/to/chrome
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)
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

Build docs developers (and LLMs) love

Get started for freeTalk to us