Skip to content
BSWEN
Blog

How to Get Started with Lightpanda Browser in 5 Minutes

Cowrie
Cowrie
Dev @ Bswen

Purpose

I needed a lightweight headless browser for web scraping and automation tasks. The traditional options like Puppeteer or Playwright require full Chrome/Chromium installations, which consume significant memory and disk space. Lightpanda caught my attention as a Zig-based headless browser that claims to be much lighter. This post documents how I got it running in under 5 minutes.

Environment

  • macOS (Apple Silicon) and Linux x86_64
  • Node.js for Puppeteer/Playwright integration
  • Docker (optional)

What is Lightpanda?

Lightpanda is a new headless browser written in Zig. Unlike Chromium-based browsers, it is designed from the ground up to be:

  • Lightweight: Single binary, no complex dependencies
  • Fast: Written in Zig for performance
  • CDP-compatible: Works with existing tools like Puppeteer and Playwright

Here is how it fits in the automation ecosystem:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Your Code  │────▶│  CDP Server │────▶│  Lightpanda │
│ (Puppeteer) │     │  (port 9222)│     │   Browser   │
└─────────────┘     └─────────────┘     └─────────────┘
                                                 │
                                                 ▼
                                        ┌─────────────┐
                                        │  Target URL │
                                        └─────────────┘

Installation

I started with the binary approach since it is the fastest way to get started.

For Linux x86_64:

Install Lightpanda on Linux
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux
chmod a+x ./lightpanda

For macOS (Apple Silicon):

Install Lightpanda on macOS
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos
chmod a+x ./lightpanda

I made a mistake initially. I downloaded the x86_64 binary on my Apple Silicon Mac. The error was cryptic:

Error output
zsh: exec format error: ./lightpanda

Make sure to download the correct architecture for your system. Use uname -m to check your architecture:

  • x86_64 - Intel/AMD processors
  • aarch64 or arm64 - Apple Silicon or ARM processors

After downloading the correct version, I verified the installation:

Verify installation
./lightpanda --version

I got this output:

Version output
lightpanda 0.1.0 (nightly)

Option 2: Docker

If you prefer containerized environments, Lightpanda provides official Docker images:

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

I verified the container was running:

Check container status
docker ps

Output:

Docker ps output
CONTAINER ID   IMAGE                      COMMAND                  CREATED         STATUS         PORTS                    NAMES
abc123def456   lightpanda/browser:nightly "lightpanda serve..."    5 seconds ago   Up 4 seconds   0.0.0.0:9222->9222/tcp   lightpanda

First Test: CLI Mode

Lightpanda has two main modes. The first is CLI mode, which lets you fetch and dump web pages without any driver library.

I tested it with a simple example:

Fetch a webpage
./lightpanda fetch --obey_robots https://example.com

The --obey_robots flag is important. Without it, Lightpanda ignores robots.txt, which may violate website terms of service.

I got this output:

Fetch output
<!doctype html>
<html>
<head>
    <title>Example Domain</title>
    <meta charset="utf-8" />
    ...
</head>
<body>
<div>
    <h1>Example Domain</h1>
    <p>This domain is for use in illustrative examples...</p>
</div>
</body>
</html>

This is useful for quick scraping tasks where you just need the HTML content.

CDP Server Mode for Automation

For more complex automation tasks, I needed the CDP (Chrome DevTools Protocol) server mode. This allows integration with Puppeteer, Playwright, and other automation tools.

Starting the CDP Server

I started the server with:

Start CDP server
./lightpanda serve --host 127.0.0.1 --port 9222

Output:

Server startup
CDP server listening on ws://127.0.0.1:9222

To verify the server is accessible, I checked the status endpoint:

Verify CDP server
curl http://localhost:9222/json/version

I got this JSON response:

CDP version response
{
  "Browser": "lightpanda/0.1.0",
  "Protocol-Version": "1.3",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9222"
}

Puppeteer Integration

Now I could connect from Puppeteer. First, I installed Puppeteer:

Install Puppeteer
npm install puppeteer-core

Then I created a simple script:

scrape-example.mjs
import puppeteer from 'puppeteer-core';


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


const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle0' });


// Extract data
const title = await page.title();
const links = await page.evaluate(() =>
  Array.from(document.querySelectorAll('a')).map(a => a.href)
);


console.log('Title:', title);
console.log('Links:', links);


await browser.disconnect();

I ran the script:

Run Puppeteer script
node scrape-example.mjs

Output:

Script output
Title: Example Domain
Links: [ 'https://www.iana.org/domains/example' ]

Playwright Integration

Playwright also works with Lightpanda. I installed it first:

Install Playwright
npm install playwright-core

Then I created a Playwright script:

playwright-example.mjs
import { chromium } from 'playwright-core';


const browser = await chromium.connectOverCDP('http://127.0.0.1:9222');
const page = await browser.newPage();
await page.goto('https://example.com');


const title = await page.title();
console.log('Title:', title);


await browser.close();

Common Issues I Encountered

Issue 1: Connection Refused

When I tried to connect from Puppeteer, I got:

Connection error
Error: connect ECONNREFUSED 127.0.0.1:9222

The CDP server was not running. I forgot to start it with lightpanda serve. After starting the server, the connection worked.

Issue 2: Page Not Loading

Sometimes the page content was empty. I realized I was not waiting for the page to load:

Wait for page load
// WRONG
await page.goto('https://example.com');
const content = await page.content(); // Might be empty


// CORRECT
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
const content = await page.content();

Issue 3: Robots.txt Blocking

Some pages returned empty results. I realized the --obey_robots flag was blocking access. I checked the site’s robots.txt and found it disallowed scraping. For legitimate use cases, I contacted the site owner for API access instead.

When to Use Lightpanda vs Chromium

Lightpanda is ideal for:

  • Simple scraping tasks: When you just need HTML content
  • Resource-constrained environments: Low memory VPS, containers
  • CI/CD pipelines: Fast startup, minimal dependencies
  • AI agent workflows: Lightweight browser for automated browsing

Stick with Chromium for:

  • Complex JavaScript apps: SPAs with heavy client-side rendering
  • Screenshot/PDF generation: Lightpanda may not support all features yet
  • Browser extensions: Not supported in Lightpanda

Summary

In this post, I showed how to get Lightpanda browser running in under 5 minutes. The key points are:

  • Binary installation: Download the correct architecture, make it executable
  • CLI mode: Use lightpanda fetch --obey_robots &lt;url&gt; for quick scraping
  • CDP server mode: Use lightpanda serve for Puppeteer/Playwright integration
  • Docker option: Available for containerized deployments

Lightpanda is still in early development, so expect some rough edges. But for lightweight scraping and automation tasks, it is a promising alternative to full Chromium-based browsers.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: