lightpanda-browser

Quick Start

Get up and running with Lightpanda Browser in minutes. This guide walks you through downloading the browser, running your first page fetch, and connecting automation clients via the Chrome DevTools Protocol (CDP).

Prerequisites: A Linux x86_64, macOS aarch64, or Windows + WSL2 environment. For Docker, any platform with Docker Engine installed.

Installation

Lightpanda ships as a single static binary with no external dependencies at runtime. You can install it from nightly builds or run it via Docker.

Download the Binary

Linux:

curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && \
chmod a+x ./lightpanda

macOS (Apple Silicon):

curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos && \
chmod a+x ./lightpanda

Windows + WSL2: Install from a WSL terminal using the Linux instructions above.

Run with Docker

Lightpanda provides official Docker images for both amd64 and arm64 architectures:

docker run -d --name lightpanda -p 9222:9222 lightpanda/browser:nightly

This starts the CDP server on port 9222, ready to accept automation connections.

For detailed platform-specific instructions, build options, and verification steps, see Installation.

Fetch a Page

The simplest way to verify your installation is to dump a URL. Lightpanda fetches the page, executes JavaScript, and outputs the resulting DOM:

./lightpanda fetch --obey_robots --log_format pretty --log_level info https://example.com

The --obey_robots flag respects the site’s robots.txt rules. This command is useful for quick testing and for scraping scenarios where you need the fully rendered HTML output.

Start the CDP Server

Lightpanda implements the Chrome DevTools Protocol, allowing you to control the browser with standard automation tools like Puppeteer, Playwright, and chromedp.

Start the server:

./lightpanda serve --host 127.0.0.1 --port 9222

The server listens for WebSocket connections on the specified host and port. Once running, any CDP-compatible client can connect.

Connect with Puppeteer 

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: "ws://127.0.0.1:9222",
});

const page = await (await browser.createBrowserContext()).newPage();
await page.goto('https://example.com', { waitUntil: "networkidle0" });
console.log(await page.title());
await browser.disconnect();

Connect with Playwright 

import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP("http://127.0.0.1:9222");
const page = await browser.contexts()[0].newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

For the full list of supported CDP domains, connection options, and troubleshooting, see CDP Server.

Performance at a Glance

Lightpanda is built from scratch in Zig, specifically for headless use cases. Compared to headless Chrome:

Metric Lightpanda Chrome Improvement
Memory per page ~10 MB ~90 MB 9x less
Page execution ~50 ms ~550 ms 11x faster
Startup time Instant ~500 ms Near-zero

These benchmarks were measured using Puppeteer to request 100 pages from a local website on an AWS EC2 m5.large instance. See the benchmark details for methodology.

Telemetry

By default, Lightpanda collects anonymous usage telemetry to help improve the product. To disable it, set an environment variable:

export LIGHTPANDA_DISABLE_TELEMETRY=true

Read the full privacy policy for details on what is collected.

Current Status

Lightpanda is in Beta. The following features are implemented and stable:

Web API coverage continues to expand. If you encounter missing APIs or unexpected behavior, please open an issue.

Next Steps