ScreenshotNeo

BlogHow-to

How to Fix Playwright Chromium Launch Errors in Alpine Docker

Alpine uses musl, which Playwright does not support for its browser builds. Learn the supported container and remote-browser fixes, with Dockerfiles and diagnostics.

By the ScreenshotNeo team30 September 20269 min read

How to Fix Playwright Chromium Launch Errors in Alpine Docker

Direct answer: Playwright’s browser builds do not support Alpine Linux or other musl-based distributions. The reliable fix is to run Chromium in a supported Debian or Ubuntu based image, install the browser and matching system dependencies, and keep the Playwright package, browser binary, and image versions aligned. If your application must remain on Alpine, run the browser in a supported Playwright container and connect to it remotely.

Adding random Alpine packages, symlinks, or compatibility layers may make one launch attempt appear to work, but that is not an officially supported configuration. Playwright’s Docker guidance explicitly identifies Alpine and other musl distributions as unsupported for its browser builds. Read the current Playwright Docker documentation before pinning image tags, because release tags change.

1. Confirm what is failing

Before changing the Dockerfile, capture the exact environment. A Chromium launch error can come from an unsupported base image, a missing browser executable, mismatched package and image versions, insufficient shared memory, or a container process problem.

# Run these inside the failing container
cat /etc/os-release
node --version
npm ls @playwright/test playwright 2>/dev/null || true
npx playwright --version
npx playwright install --dry-run chromium 2>/dev/null || true
printenv | grep -E 'PLAYWRIGHT|DEBUG|CI' || true

Record the full error, the Docker base image, how Playwright was installed, and whether the browser is downloaded during the image build or at runtime. Playwright warns that a package and Docker image version mismatch can leave the expected browser executable unavailable.

2. The simplest fix: use a supported browser image

Move the test or browser process to a supported Linux distribution. The following pattern follows Playwright’s documented build-your-own-image approach with a Debian based Node image. Pin the Playwright package and the image tag to versions you have selected together; do not copy a volatile example tag without checking the current documentation.

# Dockerfile
FROM node:20-bookworm

WORKDIR /app
COPY package*.json ./
RUN npm ci

# Installs Chromium and its OS dependencies for this supported image.
RUN npx playwright install --with-deps chromium

COPY . .
CMD ["npx", "playwright", "test"]

A minimal package setup can look like this:

{
  "private": true,
  "devDependencies": {
    "@playwright/test": "1.XX.YY"
  }
}

Replace 1.XX.YY with the exact version you intend to use. The important property is alignment: the installed package must expect the browser revision that is present in the image.

Build and run it

docker build -t pw-chromium:local .
docker run --rm --init --ipc=host pw-chromium:local

--init gives the container an init process that can reap child processes. Playwright recommends it to avoid PID 1 zombie-process problems. --ipc=host gives Chromium more shared memory and reduces out-of-memory crashes during parallel work. Evaluate the shared-memory setting with your security and isolation requirements.

3. Install browsers and dependencies correctly

On a supported distribution, Playwright provides two useful installation forms. The first installs Chromium and the required operating-system packages in one command:

A supported image keeps the Playwright package, browser revision, and operating-system libraries aligned.
A supported image keeps the Playwright package, browser revision, and operating-system libraries aligned.
npx playwright install --with-deps chromium

If the browser is already downloaded and only system packages are missing, install the dependencies separately:

npx playwright install-deps chromium

These commands are documented for supported environments. They do not turn Alpine into a supported Playwright browser environment. The browser download location also matters: install as the same user that will launch the browser, or configure a shared browser path with appropriate permissions.

Use the bundled Chromium

Playwright works best with the Chromium revision bundled for its release. Its BrowserType API cautions that other browser versions are not guaranteed and that executablePath should be used with extreme caution.

import { chromium } from '@playwright/test';

const browser = await chromium.launch({
  headless: true
});
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
await browser.close();

Avoid pointing Playwright at an arbitrary system Chromium binary until the bundled browser works. If you must use one, verify its compatibility and treat the path as an environment-specific override:

const browser = await chromium.launch({
  executablePath: process.env.CHROMIUM_PATH
});

4. Keep Alpine for the app and run Chromium remotely

If the application image must stay Alpine, isolate browser execution in a supported Playwright container. Playwright documents starting its server in a supported container and connecting from another process. This preserves the Alpine application environment while moving browser dependencies to a supported image.

When Alpine must remain, move Chromium into a supported Playwright container and connect remotely.
When Alpine must remain, move Chromium into a supported Playwright container and connect remotely.

Browser service Dockerfile

# Dockerfile.browser
FROM node:20-bookworm
WORKDIR /browser
RUN npm init -y && npm install playwright@1.XX.YY
RUN npx playwright install --with-deps chromium
EXPOSE 3000
CMD ["npx", "playwright", "run-server", "--port", "3000", "--host", "0.0.0.0"]

Start the browser service

docker build -f Dockerfile.browser -t pw-browser:local .
docker run --rm --init --ipc=host --name pw-browser -p 3000:3000 pw-browser:local

Connect from an Alpine Node application

import { chromium } from 'playwright';

const browser = await chromium.connect('ws://pw-browser:3000/');
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
await browser.close();

In Docker Compose, put both services on the same network and use the service name instead of localhost. Keep the client and server Playwright versions compatible. A version mismatch can produce protocol errors even when the network connection succeeds.

services:
  app:
    build: .
    depends_on:
      - browser
  browser:
    build:
      context: .
      dockerfile: Dockerfile.browser
    init: true
    shm_size: 1gb

Do not expose a browser server publicly without access controls and network restrictions. Keep it on a private network whenever possible.

5. A practical diagnostic sequence

  1. Identify musl. Check /etc/os-release and the C library. Alpine is musl based, which is the unsupported case documented by Playwright.
  2. Check versions. Compare the application’s Playwright package, the browser image tag, and the installed browser revision. Pin all three in CI.
  3. Verify the executable. Run npx playwright install --dry-run chromium and inspect the expected cache location. Confirm the runtime user can read and execute it.
  4. Rebuild without stale layers. A cached browser download from another package version can survive a dependency change. Rebuild the image after changing Playwright versions.
  5. Enable browser logs. Set DEBUG=pw:browser for launch diagnostics.
  6. Check container resources. Add Docker --init and --ipc=host; inspect memory limits and shared-memory usage.
  7. Test without custom executable paths. First launch the bundled Chromium. Reintroduce executablePath only when you have a specific compatibility reason.
  8. Separate the browser. If the app must remain Alpine, connect to a supported remote browser container and verify both sides use compatible Playwright versions.
DEBUG=pw:browser npx playwright test --project=chromium

6. Common errors, causes, and fixes

Error pattern Likely cause Fix
Failed to launch chromium immediately on Alpine Unsupported musl based environment Move browser execution to Debian/Ubuntu or use a supported remote browser container.
Executable doesn't exist Browser was not installed, is in another cache, or package/image versions differ Run npx playwright install --with-deps chromium in the image build and align versions.
Missing shared libraries System dependencies were omitted On a supported distribution, run npx playwright install-deps chromium or rebuild with --with-deps.
Browser exits under parallel load Small /dev/shm or memory limit Use --ipc=host, increase container memory, or reduce worker concurrency.
Zombie processes or hanging jobs No init process to reap children Run Docker with --init and ensure tests close contexts and browsers.
Protocol or connection errors with a remote browser Client and server Playwright versions do not match Pin the same compatible version in both images and rebuild both.
Works locally, fails in CI Different base image, user, cache, memory, or browser revision Print OS and Playwright versions, install during the image build, and enable DEBUG=pw:browser.
Custom Chromium crashes or behaves differently Unsupported browser revision or launch flags Return to the bundled Chromium; use a custom executablePath only after compatibility review.

7. Reliability and performance considerations

A single supported image is operationally simplest: browser files, system libraries, and the Playwright client are versioned together. It also makes failures easier to reproduce. The trade-off is a larger image and the need to change an Alpine based build.

Remote execution keeps the application image small and lets a browser service be patched independently. It adds a network hop, service discovery, lifecycle management, and a version-compatibility boundary. Use health checks and retry connection establishment, but do not retry a browser action blindly when it may have side effects.

For throughput, reuse a browser process and create isolated contexts for independent jobs. Limit worker count to the available CPU and memory. Full-page captures, large PDFs, video, and pages with many fonts or images consume more memory than a viewport screenshot. Cache browser layers in CI, but invalidate them when the Playwright package version changes. Keep the browser image tag pinned so a rebuild is deliberate and reviewable.

For security, run as a non-root user where your workload permits, restrict outbound network access, and avoid granting broad capabilities. Playwright’s Docker page mentions --cap-add=SYS_ADMIN as a way to investigate otherwise “weird errors” during local development; treat that as a diagnostic step, not a default production setting.

8. Or skip the browser setup

If your goal is to obtain reliable website screenshots rather than maintain Chromium containers, ScreenshotNeo provides a hosted screenshot API and MCP server. It accepts one GET request and returns PNG, JPEG, WebP, or PDF. Before capture, it accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled.

Only clean shots are billed. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for all options. The basic calls are:

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo includes full-page capture with lazy images loaded, CSS element capture, dark mode, 12 device presets plus custom viewports, retina scale, PDF paper size and margins, custom CSS and JavaScript, clicks, selector and network-idle waits, ad and tracker blocking, custom headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, image resizing, TTL caching, signed image links, asynchronous jobs with signed webhooks, bulk capture for 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs also work to ease migration.

The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free, and every feature is available on every plan. Create a free ScreenshotNeo account to get started.

9. FAQ

Can I make Playwright Chromium officially supported on Alpine by installing more packages?

No. Playwright’s Docker documentation states that Alpine and other musl based distributions are unsupported for its browser builds. Use a supported image or remote browser execution.

Should I use Google Chrome instead of bundled Chromium?

Start with the Chromium revision bundled with your Playwright release. Other browser versions are not guaranteed, and custom executablePath values require careful compatibility checks.

Does --with-deps fix an Alpine launch error?

It installs browser system dependencies for a supported distribution. It does not remove Alpine’s unsupported musl limitation.

Why does a remote browser need matching versions?

The client speaks the Playwright protocol implemented by the browser service. Incompatible releases can fail during connection or command execution even when the service is reachable.

When should I choose one container instead of a remote browser?

Use one supported image when you control the test image and want the shortest debugging path. Keep Alpine for the app and use a remote supported browser when changing the application base is impractical or browser dependencies should be isolated.