Installation

This guide covers installing nokap and setting up Chrome on your system. You’ll find instructions for installing from PyPI or from source, along with details on how nokap discovers Chrome automatically. If you’re running in a container or CI environment, the platform-specific notes at the end will help you get things working smoothly.

Requirements

nokap requires:

  • Python ≥ 3.10
  • Chrome or Chromium installed on the system

Installing from PyPI

pip install nokap

This installs nokap and its single runtime dependency (websockets).

Installing from Source

git clone https://github.com/posit-dev/nokap.git
cd nokap
pip install -e ".[dev]"

The [dev] extra includes testing and linting tools (pytest, ruff, pyright).

Chrome Setup

nokap needs a system-installed Chrome or Chromium browser. It does not download or bundle a browser.

Automatic Discovery

nokap searches for Chrome in platform-specific locations:

macOS

  • /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
  • /Applications/Chromium.app/Contents/MacOS/Chromium
  • /Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary
  • /Applications/Brave Browser.app/Contents/MacOS/Brave Browser
  • /Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge

Linux

Searches PATH for: google-chrome, google-chrome-stable, chromium-browser, chromium, microsoft-edge

Windows

Searches Program Files, Program Files (x86), and LOCALAPPDATA for:

  • Google\Chrome\Application\chrome.exe
  • Microsoft\Edge\Application\msedge.exe
  • Chromium\Application\chrome.exe

Manual Override

Set the CHROME_PATH environment variable to use a specific browser:

export CHROME_PATH="/usr/bin/chromium-browser"

CI Environments

On Ubuntu CI runners (GitHub Actions), install Chrome with:

- name: Install Chrome
  uses: browser-actions/setup-chrome@v1
  with:
    chrome-version: stable

Verifying the Installation

import nokap

# Check that Chrome can be found
path = nokap.find_chrome()
print(f"Chrome found at: {path}")

Dependencies

Package Role Required?
websockets Async WebSocket client for CDP Yes (runtime)
click CLI framework Yes (runtime)
Pillow Image post-processing (expand/crop) Optional (pip install nokap[extra])

Next Steps

nokap is now installed and Chrome is discoverable on your system. The setup is intentionally lightweight: just one runtime dependency and a system Chrome installation. Everything else (browser launch, WebSocket connection, tab management) is handled internally.

With installation complete, you’re ready to capture your first screenshot. The Quick Start guide walks you through the three main input modes in under a minute.