Skip to main content

​
Requirements

Before installing Zendriver, ensure your system meets these requirements:

Python version

Python 3.10 or higher is required

Browser

Chrome or Chromium browser installed
Zendriver automatically detects Chrome or Chromium on your system. No additional browser driver installation is needed.

​
Install with pip

The simplest way to install Zendriver is using pip: 
pip install zendriver
This installs the latest stable version from PyPI.
That’s it! You’re ready to use Zendriver.

​
Install with other package managers

Zendriver works with all modern Python package managers: 
uv add zendriver

​
Install from source

To install the latest development version directly from GitHub: 
pip install git+https://github.com/cdpdriver/zendriver.git
The development version may contain unreleased features and breaking changes. Use it only if you need the absolute latest updates.

​
Verify installation

Verify that Zendriver is installed correctly: 
python -c "import zendriver; print(zendriver.__version__)"
You should see the version number printed, for example: 0.15.2

​
Chrome installation

Zendriver requires Chrome or Chromium to be installed on your system.

​
Check if Chrome is installed

Zendriver will automatically detect Chrome in standard installation locations. To verify Chrome is installed: 
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version

​
Install Chrome

If Chrome is not installed, download it from:

Download Google Chrome

Official Chrome download page
Alternatively, install Chromium: 
sudo apt update
sudo apt install chromium-browser

​
Docker installation

Zendriver provides first-class Docker support for running browser automation in containers.

zendriver-docker

Official Docker project template with GPU-accelerated Chrome support
The zendriver-docker template provides:
  • Real Chrome browser (not headless) in Docker
  • GPU acceleration support (Linux only)
  • Pre-configured environment
  • Easy deployment

​
Quick Docker setup

1

Clone the template

git clone https://github.com/cdpdriver/zendriver-docker.git
cd zendriver-docker
2

Build the image

docker build -t zendriver-app .
3

Run the container

docker run --rm -v $(pwd):/app zendriver-app
For detailed Docker setup instructions and GPU acceleration, see the zendriver-docker repository.

​
Dependencies

Zendriver automatically installs these dependencies:
  • websockets - WebSocket client for CDP communication
  • asyncio-atexit - Async cleanup on exit
  • deprecated - Deprecation warnings
  • emoji - Emoji support for text handling
  • grapheme - Unicode grapheme support
  • mss - Screenshot functionality
You don’t need to install these manually—pip handles all dependencies automatically.

​
Development installation

If you want to contribute to Zendriver or modify the source code:
1

Clone the repository

git clone https://github.com/cdpdriver/zendriver.git
cd zendriver
2

Install in editable mode

pip install -e .
3

Install development dependencies

pip install -e ".[dev]"
This installs additional tools like pytest, mypy, and ruff for development.

Contributing guide

Learn how to contribute to Zendriver

​
Upgrading

To upgrade to the latest version: 
pip install --upgrade zendriver
Always check the changelog before upgrading to see if there are any breaking changes.

​
Uninstall

To remove Zendriver from your system: 
pip uninstall zendriver

​
Next steps

Quickstart

Create your first Zendriver script

Configuration

Learn about browser configuration options

​
Troubleshooting

If installation fails, try:
pip install --upgrade pip
pip install zendriver
Make sure you’re using Python 3.10 or higher:
python --version
If Zendriver can’t find Chrome automatically, you can specify the path when starting the browser:
import zendriver as zd

browser = await zd.start(
    browser_executable_path="/path/to/chrome"
)
On Linux, you might need to make Chrome executable:
sudo chmod +x /usr/bin/google-chrome
If running as root, you may need to disable the sandbox:
browser = await zd.start(sandbox=False)
If you get import errors, ensure you’re in the correct Python environment:
which python
pip list | grep zendriver
If using virtual environments, make sure it’s activated.

Build docs developers (and LLMs) love

Get started for freeTalk to us