Installation #

Download and install Lightpanda Browser on your platform. Lightpanda provides pre-built nightly binaries for Linux and macOS, official Docker images, and the option to build from source.

Parent topic: Quick Start

Prerequisites #

Before installing Lightpanda, ensure you have:

• Linux x86_64 or macOS aarch64 (Apple Silicon) system
• curl available on your system (for binary downloads)
• Docker installed (if using the Docker method)
• For Windows users: WSL2 configured and running

Lightpanda does not require any runtime dependencies beyond the binary itself. There is no need to install a JDK, Node.js, or any browser engine separately.

Installation Methods #

Lightpanda offers three installation paths depending on your environment and requirements:

Install from Nightly Builds #

Nightly builds are pre-compiled binaries published from the latest main branch. They are the fastest way to get started.

Linux x86_64 #

Download the binary, make it executable, and optionally move it to your PATH:

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

To make it available system-wide:

sudo mv ./lightpanda /usr/local/bin/lightpanda

macOS aarch64 (Apple Silicon) #

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

To make it available system-wide:

sudo mv ./lightpanda /usr/local/bin/lightpanda

Note: On macOS, you may need to allow the binary in System Settings > Privacy & Security the first time you run it, since it is not signed with an Apple Developer certificate.

Windows (WSL2) #

Lightpanda runs on Windows inside WSL2. Open a WSL terminal and follow the Linux installation steps above.

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

Tip: Install automation clients (Puppeteer, Playwright) on the Windows host rather than inside WSL. Connect them to the CDP server running in WSL using the WSL IP address.

Install from Docker #

Lightpanda provides official Docker images for both linux/amd64 and linux/arm64 architectures. The Docker image is minimal (based on debian:stable-slim) and starts the CDP server automatically.

Pull and Run #

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

This starts a container with the CDP server listening on port 9222. The default command is:

/bin/lightpanda serve --host 0.0.0.0 --port 9222 --log_level info

Verify the Container is Running #

docker ps --filter name=lightpanda

You should see the container running with port 9222/tcp mapped.

Custom Configuration #

Override the default command to pass additional flags:

docker run -d --name lightpanda -p 9222:9222 \
  lightpanda/browser:nightly \
  /bin/lightpanda serve \
    --host 0.0.0.0 \
    --port 9222 \
    --obey_robots \
    --log_format pretty \
    --log_level info

Stop and Remove #

docker stop lightpanda && docker rm lightpanda

Docker Compose #

For projects that use Docker Compose, add Lightpanda as a service:

services:
  lightpanda:
    image: lightpanda/browser:nightly
    ports:
      - "9222:9222"
    restart: unless-stopped

Verify Your Installation #

After installing via any method, verify that Lightpanda is working correctly.

Check the Version #

Run the binary directly (or via Docker) to confirm it starts:

./lightpanda --help

Fetch a Page #

Use the fetch command to dump the DOM of a test page:

./lightpanda fetch \
  --obey_robots \
  --log_format pretty \
  --log_level info \
  https://demo-browser.lightpanda.io/campfire-commerce/

You should see log output showing the page navigation, JavaScript execution, and HTTP requests, followed by the rendered HTML output:

INFO  telemetry : telemetry status . . . . . . [+0ms]
      disabled = false

INFO  page : navigate . . . . . . . . . . . . [+6ms]
      url = https://demo-browser.lightpanda.io/campfire-commerce/
      method = GET

INFO  browser : executing script . . . . . . . [+118ms]
      src = .../campfire-commerce/script.js

<!DOCTYPE html>
...

This confirms that Lightpanda is correctly installed, can fetch pages over the network, and can execute JavaScript.

Telemetry #

By default, Lightpanda collects and sends anonymous usage telemetry. To disable telemetry, set an environment variable before running the binary:

export LIGHTPANDA_DISABLE_TELEMETRY=true
./lightpanda serve --host 127.0.0.1 --port 9222

For Docker, pass the environment variable with -e:

docker run -d --name lightpanda -p 9222:9222 \
  -e LIGHTPANDA_DISABLE_TELEMETRY=true \
  lightpanda/browser:nightly

You can read Lightpanda’s privacy policy at https://lightpanda.io/privacy-policy.

Platform Support Matrix #

Troubleshooting #

Binary Permission Denied #

If you see permission denied when running the binary:

chmod a+x ./lightpanda

macOS Gatekeeper Warning #

On macOS, unsigned binaries trigger a Gatekeeper warning. Open System Settings > Privacy & Security and click “Allow Anyway”, or run:

xattr -d com.apple.quarantine ./lightpanda

Docker Port Already in Use #

If port 9222 is already occupied:

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

Then connect your CDP client to ws://127.0.0.1:9223.

Connection Refused from CDP Client #

Ensure the server is running and listening on the correct host:

• Local binary: Use --host 127.0.0.1 --port 9222
• Docker: The container uses --host 0.0.0.0 by default, which accepts connections from outside the container
• WSL2: Use the WSL IP address (find it with hostname -I inside WSL)

Build from Source Issues #

If you need to build from source for a platform not covered by nightly builds, see Building from Source for full prerequisites and instructions.

Updating Lightpanda #

Nightly Binary #

Re-download the latest binary to replace the existing one:

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

Docker #

Pull the latest image and recreate the container:

docker pull lightpanda/browser:nightly
docker stop lightpanda && docker rm lightpanda
docker run -d --name lightpanda -p 9222:9222 lightpanda/browser:nightly

Next Steps #

• CDP Server – Start the CDP server and connect with Puppeteer or Playwright
• Architecture – Understand how Lightpanda works under the hood
• Building from Source – Build Lightpanda from source for development or custom platforms