Introduction

Learn what nokap is, why it exists, and how it works under the hood. This page provides a high-level overview of nokap’s design philosophy and architecture, giving you the foundational context you’ll need before diving into screenshots, PDFs, and the CLI. By the end, you’ll understand how nokap communicates with Chrome and why that approach keeps things fast and dependency-free.

What Is nokap?

nokap is a lightweight Python package that captures screenshots and PDFs from web pages using headless Chrome via the Chrome DevTools Protocol (CDP). It communicates directly with Chrome over WebSockets so no Selenium, no Playwright, or no browser driver binaries needed.

Why Use nokap?

If you need to:

  • Convert HTML tables or reports to images for embedding in documents
  • Generate PDFs from web pages with precise control over page size and margins
  • Capture specific elements using CSS selectors
  • Produce retina-quality (2×, 3×) screenshots
  • Automate web page captures without heavyweight browser automation frameworks

…then nokap is the right tool.

How It Works

nokap’s architecture is intentionally simple:

  1. Launch: Finds and starts headless Chrome with a random debugging port
  2. Connect: Opens a WebSocket to Chrome’s CDP endpoint
  3. Capture: Creates a tab, navigates, waits, then calls Page.captureScreenshot or Page.printToPDF
  4. Cleanup: Closes the tab; Chrome stays running for reuse until nokap.close() or process exit

The entire package has a single runtime dependency: websockets.

Key Features

Feature Details
Image formats PNG, JPEG, WebP
PDF generation Configurable page size, margins, orientation
CSS selectors Capture specific elements (or union of multiple)
Zoom/scale Produce retina-quality (2×, 3×) images
Expand/padding Add whitespace around captured elements
Local HTML Render HTML strings or local .html files
Viewport control Set width/height for responsive layouts
Custom User-Agent Override the browser UA string
CLI nokap webshot and nokap from-html commands
Auto-cleanup Chrome process managed via atexit
Jupyter-safe Works in notebooks (no event loop conflicts)

Next Steps

You now have a clear picture of what nokap is, how it communicates with Chrome, and what it can do. The architecture is intentionally minimal (a direct WebSocket connection to Chrome’s DevTools Protocol) which keeps things fast, predictable, and free of heavyweight dependencies.

Once nokap is installed and Chrome is discoverable on your system, you’ll be ready to capture your first screenshot in just a few lines of code.