README

Lightpanda Browser

The headless browser built from scratch for AI agents and automation.
Not a Chromium fork. Not a WebKit patch. A new browser, written in Zig.
16x lighter and 9x faster than Chromium.















 




 Benchmarks

Requesting 933 real web pages over the network on a AWS EC2 m5.large instance.
See benchmark details.

| Metric | Lightpanda | Headless Chrome | Difference |
| :---- | :---- | :---- | :---- |
| Memory (peak, 100 pages) | 123MB | 2GB | ~16x less |
| Execution time (100 pages) | 5s | 46s | ~9x faster |

 Quick start

 Install

Package Managers

Latest nightly from Homebrew:
console
brew install lightpanda-io/browser/lightpanda


Latest nightly from Arch Linux User Repository:
console
yay -S lightpanda-nightly-bin


Download from the nightly builds

You can download the last binary from the nightly
builds for
Linux and MacOS for both x86_64 and aarch64.

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


Verify the binary before running anything:
console
./lightpanda version


Linux aarch64 is also available

If you use Nix, you can run Lightpanda directly from the flake without downloading a binary:
console
nix run github:lightpanda-io/browser -- --help


Or pin it as an input in your own flake:
nix
{
  inputs.lightpanda.url = "github:lightpanda-io/browser";
}


 Note: The Linux release binaries are linked against glibc. On musl-based Linux distributions (Alpine, etc.) the binary fails with cannot execute: required file not found because the glibc dynamic linker is missing. Use a glibc-based base image: the current release binaries need glibc 2.35 (x86_64) or 2.38 (arm64), so debian:bookworm-slim (2.36) is fine on x86_64 but too old for arm64 — use FROM ubuntu:24.04, FROM debian:trixie-slim, or FROM debian:forky-slim there — or build from sources.

 Android / Termux: there is no native Android build. The Linux aarch64 binary needs the glibc loader (/lib/ld-linux-aarch64.so.1), which Android's Bionic libc does not provide, so it fails with the same cannot execute: required file not found error.

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


MacOS x86_64 is also available

For Windows + WSL2

Lightpanda has no native Windows binary. Install it inside WSL following the Linux steps above.

WSL not installed? Run wsl --install from an administrator shell, restart, then open wsl.
See Microsoft's WSL install guide for details.

Your automation client (Puppeteer, Playwright, etc.) can run either inside WSL or on the Windows host. WSL forwards localhost:9222 automatically.

Install from Docker

Lightpanda provides official Docker
images for both Linux amd64 and
arm64 architectures.
The following command fetches the Docker image and starts a new container exposing Lightpanda's CDP server on port 922

Top issues

Latest release

Behavior changes
- serve: the --http-max-concurrent default now follows --cdp-max-connections (8× it, between 40 and 256). With the default 16 connections it is 128.
- fetch --dump markdown now asks the server for markdown (Accept: text/markdown,...). A text/markdown response is dumped as-is. Not sent with --dump-selector, --wait-selector or --wait-script.
- Accessibility.getPartialAXTree now honors fetchRelatives, as Chrome does: it returns the node and its relatives, no longer the whole subtree. Use getFullAXTree or getChildAXNodes for a subtree.
- DOM.querySelector with no match now ret