If Playwright’s Chromium browser will not launch in an Alpine Docker container, the first fix is usually to move browser execution to a supported Linux distribution. Playwright’s Docker documentation explicitly says Alpine and other musl-based distributions are not supported for its browser builds. You can either run the app and browser in a supported image, or keep the app on Alpine and connect it to a browser running in a supported Playwright container.
Why Chromium fails to launch on Alpine
Alpine uses the musl C library. Playwright’s browser builds target supported Linux environments, and its Docker documentation states that “Alpine Linux and other distributions that are based on the musl standard library are not supported.” This is a platform-support limitation, not simply a missing package that can reliably be fixed by installing a few extra Alpine libraries. Playwright Docker documentation
That does not mean every launch error in an Alpine-based project has exactly the same cause. The exact failure can depend on the Playwright package version, browser installation method, container image, and runtime settings. But if Chromium itself is being launched on Alpine, the unsupported base should be addressed before spending time on speculative dependency lists or compatibility shims.
Choose a supported browser deployment
| Approach | Best fit | Trade-off |
|---|---|---|
| Run Playwright and Chromium together in a supported Linux image | Your test or application job can use a supported base, such as a Debian- or Ubuntu-based image. | Usually the most direct setup to align, but may require changing the existing image. |
| Keep the application on Alpine and run Chromium remotely | The app image must remain Alpine, or you want browser dependencies isolated. | Preserves the app base, but adds a browser container and a remote connection; client and browser Playwright versions need to match. |
Both patterns are covered by Playwright’s Docker guidance. See the official Docker guide for the current connection example and supported image tags.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
Option 1: Run Chromium in a supported image
For the simplest arrangement, put the Playwright package and browser in the same supported Linux container. Playwright’s build-your-own-image example uses a Debian Bookworm Node image. The prebuilt Playwright images are Ubuntu-based. Use an image version that matches the Playwright version installed by your project: a mismatch can leave Playwright looking for a browser executable that is not present. Image tags and current releases change, so verify the tag in the official guide rather than copying an old version number.
Example Dockerfile
This example uses the documented node:20-bookworm base and installs Chromium plus its system dependencies during the image build. Keep your package lockfile in the build context and use it to install the project’s pinned Playwright version.
FROM node:20-bookworm
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
RUN npx playwright install --with-deps chromium
COPY . .
CMD ["npm", "test"]The command npx playwright install --with-deps chromium installs Chromium and the Linux system dependencies required by that browser on a supported distribution. Playwright also documents npx playwright install-deps chromium when you need to install dependencies separately from the browser download. These commands do not make Alpine supported; use them in an appropriate supported environment. Playwright CLI reference · Playwright browser installation guide
Keep the package, image, and browser aligned
- Pin the Playwright package version in your dependency manifest and lockfile.
- Use a Playwright Docker image tag that corresponds to that package version if you choose a prebuilt image.
- Install the browser through the matching Playwright package rather than assuming a system Chromium binary is interchangeable.
- When updating Playwright, rebuild the image and browser installation together, then run the test job in the rebuilt image.
Playwright warns that package/image version mismatches can prevent it from finding the browser executable it expects. Its Docker page recommends pinning the image version. Docker guidance
Option 2: Keep Alpine and connect to a remote browser
If the application must stay on Alpine, separate the browser from the app container. Run Playwright’s browser server in a supported Playwright container, then connect to it from the Alpine-side client using the documented remote connection approach. The browser process, not merely the application, must run in the supported environment.
Use the connection code and container startup command in the current Playwright Docker guide; do not rely on an improvised endpoint or an outdated example. Keep the client-side Playwright package compatible with the Playwright version running alongside the browser. This architecture adds a network hop and another service to start, monitor, and secure, but lets you retain the Alpine app image without asking Chromium to run there.
Diagnose launch errors after moving Chromium
Once Chromium runs in a supported image, check the remaining failure against the actual browser binary and container runtime rather than attributing every error to Alpine.
Verify the browser was installed for this Playwright version
Run the install command from the project that owns the Playwright package:
Rank #3
npx playwright install chromiumFor a supported Linux image where system packages also need installing, use:
npx playwright install --with-deps chromiumCheck that the package version in the running container is the version you expect, and that the container was rebuilt after dependency or image changes. Playwright’s browser management documentation explains browser downloads and executable management. Browser installation and management
Turn on browser launch logs
Set Playwright’s browser debug environment variable on the failing command to expose launch details:
DEBUG=pw:browser npx playwright testIn CI, configure DEBUG=pw:browser as an environment variable for the test step, then inspect the job log for the browser executable path and launch output. This helps distinguish a missing executable from a process startup or runtime problem. Playwright CI documentation
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Check Docker process and shared-memory settings
- Use Docker’s
--initoption to help avoid zombie child processes when the container’s main process manages browser processes. - For Chromium, Playwright recommends
--ipc=hostto reduce out-of-memory crashes associated with shared memory. - For otherwise “weird errors” during local development, Playwright’s Docker guide suggests trying
--cap-add=SYS_ADMINas a diagnostic. Treat this as a troubleshooting experiment, not a default production security setting.
These runtime settings address container process and resource behavior; they do not change Alpine’s unsupported status. Consult the Docker guide before adapting flags to a production deployment.
Common errors and practical fixes
| Symptom | Likely check | What to do |
|---|---|---|
| Chromium launch fails only in an Alpine image | The browser is running on an unsupported musl-based distribution. | Move browser execution to a supported image, or use the documented remote browser setup. |
| Playwright cannot find its browser executable | The browser was not installed, the image was not rebuilt, or package and image versions differ. | Install Chromium with the matching Playwright package; align and pin the package/image versions. |
| Browser starts but crashes or runs out of memory in Docker | Check container shared-memory configuration and process handling. | Try the recommended --ipc=host and --init settings, then inspect browser logs. |
| Failure appears after selecting a custom Chromium executable | The executable may not be the browser version Playwright expects. | Prefer Playwright’s bundled browser. Use executablePath only when you understand and accept the compatibility risk. |
| Remote browser connection fails | Check that the browser service is reachable and that client and server Playwright versions are compatible. | Verify the container startup and connection details against the current official Docker guide. |
Should you use a custom Chromium binary?
Playwright says Chromium works best with the version bundled with Playwright and offers no guarantee for other versions. Its BrowserType API specifically cautions that executablePath should be used with extreme caution. A custom binary may appear to solve a launch issue while introducing a browser/protocol mismatch or a failure that only appears in certain tests. Unless you have a concrete compatibility requirement, install and use the browser version managed by the project’s Playwright package. BrowserType API documentation
Or skip the browser setup
If your goal is to capture website screenshots rather than run Playwright tests or automate browser interactions, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. For example, this cURL request captures Stripe as a WebP image:
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 parameters and response details. ScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month without a card.
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
Cost, reliability, and workflow considerations
For browser automation, the cost of the supported-image approach is the work of maintaining a browser-capable image and keeping its package and browser versions synchronized. The remote-browser approach preserves an Alpine application image but introduces a separate browser service and connection to manage. Neither option is a substitute for pinning versions and rebuilding deliberately.
For screenshot-only jobs, an API can avoid maintaining a local browser container. ScreenshotNeo bills only clean shots; its response includes X-Page-Verdict and X-Billed headers identifying the page outcome and billing status. This is a different workflow from Playwright automation: it does not replace arbitrary test scripts or browser interactions.
Recommended fix in brief
- Record the base image, Playwright package version, browser install method, and full launch error.
- If Chromium currently runs in Alpine, move browser execution to a supported image or use the documented remote-browser architecture.
- Align and pin the Playwright package and container image versions, then install Chromium and its system dependencies in the supported environment.
- If launch still fails, enable
DEBUG=pw:browserand verify the executable, Docker init behavior, and shared-memory configuration. - Avoid treating Alpine package additions or an arbitrary Chromium binary as an officially supported fix.
Frequently Asked Questions
Does Playwright officially support Chromium running in Alpine Docker?
No. Playwright’s Docker documentation says Alpine and other musl-based distributions are unsupported for its browser builds.
Can I keep my Alpine application if I move Chromium elsewhere?
Yes. Run the browser in a supported Playwright container and connect remotely, keeping the client and browser Playwright versions compatible.
Does ScreenshotNeo replace Playwright for browser tests?
No. It is a screenshot API and MCP server for capture workflows, not a replacement for Playwright test scripts or arbitrary browser automation.
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.
