Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
The most reliable fix is not another Alpine package: Playwright’s Docker documentation states that Alpine Linux and other musl-based distributions are unsupported for its browser builds. Run Chromium in a supported Debian/Ubuntu-based image, or keep your Alpine application image and connect to a browser running in a supported Playwright container. Then align the Playwright package, browser binary and image versions, install dependencies with Playwright’s CLI, and debug the remaining launch failure inside the supported environment.
Why Chromium fails in Alpine
Alpine uses the musl C standard library. Playwright’s official Docker guidance says Alpine and other musl-based distributions are not supported for its browser builds: Playwright Docker documentation. That is a support boundary, not a missing-package checklist.
Installing a few shared libraries, copying a browser binary from another image or adding a compatibility shim may occasionally change the error, but none of those approaches makes the Playwright browser build officially supported on Alpine. The documented remedies are to execute the browser in a supported Linux environment or to connect remotely to one.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose the deployment pattern first
| Pattern | Best when | Trade-off |
|---|---|---|
| Playwright and Chromium in one supported image | Your test job or service can use a Debian/Ubuntu-family base image. | You may need to change the current application image, but browser and package alignment is simplest. |
| Alpine application with a remote Playwright browser | The application image must stay Alpine or browser dependencies should be isolated. | You add a browser service and connection step, and both sides must use compatible Playwright versions. |
Do not start by trying to force the first pattern onto Alpine. Decide whether the application needs Alpine or only the browser workload does; that determines the cleanest fix.
#1 Best Overall
1. Record the versions and the complete error
Before changing the image, capture the facts that determine compatibility:
- Docker base image and tag.
- Playwright package and language binding version.
- How browsers were installed (for example, the Playwright CLI or a prebuilt image).
- The complete Chromium launch error, including its first and last lines.
- Whether the failure occurs locally, in CI, or in both.
Playwright warns that an image/package mismatch can leave the package looking for a browser executable that is absent or stored at a different revision. Pin the Playwright Docker image tag rather than relying on a moving latest-style reference, and keep the image version aligned with the package used by your tests. Check the current tag in the official Docker documentation because release examples change.
2. Move browser execution to a supported image
The official build-your-own-image example uses node:20-bookworm. The prebuilt Playwright images are Ubuntu-based. Use a current supported tag and install the same Playwright version your project declares.
Example Dockerfile for a Node.js test image
FROM node:20-bookworm
WORKDIR /app
COPY package*.json ./
RUN npm ci
RUN npx playwright install --with-deps chromium
COPY . .
CMD ["npm", "test"]--with-deps installs Chromium plus the operating-system dependencies required by Playwright on the supported distribution. It is not a supported route for converting Alpine into a supported browser environment.
Use an official Playwright image when it fits
An official image can provide the browser and system libraries in one layer. Select a tag that matches your installed Playwright release, then verify the current naming and version on the Docker guide. A newer image with an older project package, or the reverse, can recreate a “browser executable not found” failure.
3. Install Chromium and system dependencies correctly
On a supported Linux base, the normal Chromium installation command is:
npx playwright install --with-deps chromiumIf the browser download is already handled elsewhere and you only need operating-system packages, use:
npx playwright install-deps chromiumThese commands and their options are documented in the Playwright CLI reference. Browser downloads and executable management are covered in the Playwright browsers guide.
Verify the browser is present
Run the install command in the same image and user context that will launch the test. A browser installed during one Docker build stage or as root may not be visible to a different runtime user if the image layout or cache path changes. If the launch error says the executable cannot be found, first check the Playwright package revision and installation output before changing launch flags.
4. Keep Alpine, but run Chromium remotely
If the application must remain Alpine, isolate browser execution in a supported Playwright container. Playwright documents running its server in a supported container and connecting from the host or another machine. The Alpine process then acts as the client; Chromium itself runs where Playwright supports it.
Rank #3
Operational checklist
- Start a supported Playwright browser container with a pinned image tag.
- Run the server component there, following the connection method in the current Docker documentation.
- Install the same Playwright version in the Alpine client application.
- Connect to the browser endpoint from the Alpine container using the documented API.
- Keep the browser service on a private network and apply the authentication and network controls appropriate to your deployment.
Version matching matters on both sides. A client package that expects a different protocol or browser revision can fail even though the remote container itself starts successfully.
5. Debug the failure inside the supported container
Once Chromium runs on a supported base, turn on Playwright’s browser launch logging:
DEBUG=pw:browser npx playwright testIn CI, set DEBUG=pw:browser as an environment variable for the failing job. The logs can show the executable path, arguments and process exit details. Playwright’s CI guidance includes this diagnostic flow: Playwright Continuous Integration.
Use the bundled browser by default
Playwright’s BrowserType API says Chromium works best with the version bundled by Playwright. Other Chromium versions are not guaranteed to work, and the API describes executablePath as something to use with extreme caution. Remove a custom path while diagnosing unless you have a specific, tested reason to keep it. See the BrowserType API.
Container runtime settings that affect launches
Use an init process
Playwright recommends Docker’s --init option. It provides a proper PID 1 to reap child processes and helps prevent zombie processes during repeated browser launches.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →docker run --init ...Give Chromium adequate shared memory
Chromium can crash when the container’s shared-memory area is too small. Playwright recommends --ipc=host for Chromium:
docker run --init --ipc=host ...Apply this deliberately in your environment, considering your container isolation policy. It addresses resource-related crashes after the browser can already start; it does not make Alpine supported.
Try SYS_ADMIN only as a local diagnostic
The Docker guide says --cap-add=SYS_ADMIN can be tried for otherwise “weird errors” during local development. Treat that as a troubleshooting experiment, not a default production setting. Remove the capability when you have identified the actual cause and use the least privilege your deployment permits.
Common errors and targeted fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Browser executable is missing | Playwright package, image and browser revision do not match, or installation ran in another stage/user context. | Pin matching versions, run npx playwright install --with-deps chromium in the runtime image, and verify the install output. |
| Shared-library or loader errors on Alpine | The browser is being launched on an unsupported musl-based distribution. | Move execution to Debian/Ubuntu-based Playwright image or use a remote supported browser. |
| Browser starts and immediately crashes | Insufficient shared memory or a container process-management problem. | Try --ipc=host and --init; inspect DEBUG=pw:browser logs. |
| Only a custom Chromium path fails | The binary is an untested version or incompatible build. | Remove executablePath and use Playwright’s bundled Chromium. |
| Works locally but fails in CI | Different image tag, user, cache or dependency installation path. | Print the image and Playwright versions, install in the CI runtime image, and compare launch logs. |
| Remote connection fails | Client and server Playwright versions differ, or the endpoint is unreachable. | Align versions, verify container networking and endpoint configuration, then enable browser logging on the server. |
Performance, reliability and cost considerations
- A single supported image usually has fewer moving parts and is easier to reproduce, but it may increase the size of an application image.
- A remote browser service keeps Alpine lean and can be shared by jobs, but introduces network latency, service health checks and another versioned deployment.
- Pinning image and package versions improves repeatability. Update them intentionally and rerun the browser installation when upgrading Playwright.
- Use Docker layer caching for the Playwright package and browser download where your CI policy permits, while ensuring the cache is invalidated when the Playwright version changes.
- Do not infer a measured failure rate or performance advantage from the support statement; the official documentation does not provide such statistics for Alpine launch failures.
Or skip the browser setup
If your goal is simply to obtain a clean webpage screenshot rather than run Playwright code, ScreenshotNeo provides a website screenshot API and MCP server. A single request returns PNG, JPEG, WebP or PDF, without requiring you to maintain a Chromium container.
Recommended Free Tools
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Before capture, it accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and each response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers. Its MCP server includes take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients.
ScreenshotNeo includes full-page capture with lazy-image loading, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF paper and page controls, custom CSS or JavaScript, pre-capture clicks, selector hiding, selector/delay/network-idle waits, request and resource blocking, custom headers, cookies, user agents and authorization, timezone and geolocation, transparent backgrounds, resizing, configurable-TTL caching, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API and an OpenAPI specification. Common parameter names used by other screenshot APIs also work.
Best Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing provides two months free. Create a free ScreenshotNeo account.
Final verification checklist
- The browser executes on Debian/Ubuntu-based supported Linux, not Alpine.
- The Playwright package, browser revision and image tag are intentionally aligned.
- Chromium was installed with
--with-depsor dependencies were installed withinstall-depsin the runtime image. DEBUG=pw:browseroutput has been checked for the remaining failure.--initand an appropriate shared-memory configuration are set for the container runtime.- Any custom
executablePathhas been removed unless its compatibility is known. - If Alpine is retained, the remote browser service is version-matched and reachable.
Frequently Asked Questions
Is there an official package combination that makes Playwright Chromium supported on Alpine?
No. Playwright’s Docker documentation explicitly marks Alpine and other musl-based distributions as unsupported for its browser builds; use a supported image or remote browser execution.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteShould I use a system Chromium package instead of Playwright’s browser?
Playwright recommends its bundled Chromium. Other versions are not guaranteed, and custom executable paths should be used with extreme caution.
Does –with-deps fix an Alpine launch error?
It installs browser dependencies for a supported Linux environment. It does not remove Alpine’s musl-based support limitation.
Can the Alpine container still run the tests?
Yes, if the tests connect to Chromium running in a supported Playwright container and the client and browser service use compatible Playwright versions.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →
