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.

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:

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.

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
- Identify musl. Check
/etc/os-releaseand the C library. Alpine is musl based, which is the unsupported case documented by Playwright. - Check versions. Compare the application’s Playwright package, the browser image tag, and the installed browser revision. Pin all three in CI.
- Verify the executable. Run
npx playwright install --dry-run chromiumand inspect the expected cache location. Confirm the runtime user can read and execute it. - Rebuild without stale layers. A cached browser download from another package version can survive a dependency change. Rebuild the image after changing Playwright versions.
- Enable browser logs. Set
DEBUG=pw:browserfor launch diagnostics. - Check container resources. Add Docker
--initand--ipc=host; inspect memory limits and shared-memory usage. - Test without custom executable paths. First launch the bundled Chromium. Reintroduce
executablePathonly when you have a specific compatibility reason. - 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.


