Playwright cannot open a headed browser on a Linux server or in Docker
Playwright will be unable to locate browser executablesShort answer
A headed browser needs a display, and a Linux server or container has none. Playwright's own CI guide says headed runs on Linux need Xvfb, so install it and start the tests with xvfb-run, or use the official Playwright image which already includes it. Also match the image tag to your Playwright version.
Fix it fast
1Find out which cause you have
Check whether this machine has a display at all. An empty DISPLAY on a server or in a container means a headed browser has nowhere to draw.
echo "DISPLAY=[$DISPLAY]" which xvfb-run || echo "xvfb-run missing"2Match what you see, then jump to its fix
- 1
DISPLAY is empty and xvfb-run is missing; the run fails only with --headedNo display server on the machineFix - 2
Playwright will be unable to locate browser executablesThe Docker image tag does not match the Playwright package versionFix - 3
The browser starts and then dies, or the page crashes soon after launchChromium crashes in the container without the recommended flagsFix
- 1
What does the error look like?
Playwright will be unable to locate browser executablesnpx playwright test --headed shows no window on a Linux server
Cause 1 of 3
No display server on the machine
1Check
Playwright launches browsers headless by default. Headed mode on a Linux agent requires Xvfb to be installed.
npx playwright test --headed
dpkg -s xvfb2Fix
Install Xvfb with the browser system dependencies, then run the tests through xvfb-run. This gives the browser a virtual screen.
npx playwright install --with-deps
sudo apt-get install -y xvfb
xvfb-run npx playwright test --headed3Verify
The run completes and the report shows passed tests.
xvfb-run npx playwright test --headed --reporter=lineConfirmed by playwright.dev
Cause 2 of 3
The Docker image tag does not match the Playwright package version
1Check
Compare the version in package.json with the tag of the mcr.microsoft.com/playwright image used in your Dockerfile or compose file.
npx playwright --version
grep -R "mcr.microsoft.com/playwright" Dockerfile compose.yaml 2>/dev/null2Fix
Pin the image tag to the same version as the Playwright package.
FROM mcr.microsoft.com/playwright:v1.64.1-noble3Verify
Rebuild and run the tests inside the container.
docker build -t pw-tests .
docker run --rm --init --ipc=host pw-tests npx playwright testConfirmed by playwright.dev
Cause 3 of 3
Chromium crashes in the container without the recommended flags
1Check
The Playwright Docker guide recommends --init and --ipc=host. Without --ipc=host, Chromium can run out of memory and crash.
docker inspect --format '{{.HostConfig.IpcMode}}' CONTAINER_NAME2Fix
Start the container with the recommended flags. Add --cap-add=SYS_ADMIN only if Chromium still fails to launch during local development.
docker run -it --rm --init --ipc=host mcr.microsoft.com/playwright:v1.64.1-noble /bin/bash3Verify
Run the tests again inside that shell.
npx playwright testConfirmed by playwright.dev
How do I stop it coming back?
- Run CI headless; use headed only on a developer machine or behind xvfb-run.
- Update the image tag whenever you bump the @playwright/test dependency.
- Use the official image in CI instead of installing browser libraries by hand.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Web apps
npm start runs, but the browser does not refresh when you save a file
Saving a file does nothing while npm start is running
The watcher behind npm start is not seeing your edit.
4 causes, each with a fixWeb apps
django-tailwind cannot find the npm executable (cPanel, Windows, Linux)
CommandError raised by the tailwind management command about npm
django-tailwind runs npm as a subprocess, and Python sometimes cannot find it.
3 causes, each with a fixWeb apps
Node.js fails with uv_cwd ENOENT when its folder is gone
npm, node or next fails at start in a terminal whose folder was removed
uv_cwd is how Node.js asks the operating system for its current working directory.
2 causes, each with a fixWeb apps
Playwright opens a small window instead of a full-size one
page.viewportSize() is 1280x720 on a larger monitor
Playwright gives every page a fixed 1280x720 viewport, so the page never fills the window.
3 causes, each with a fixWeb apps
Playwright says the execution context was destroyed because of a navigation
page.evaluate: Execution context was destroyed, most likely because of a navigation.
The page navigated while your script was running code inside it, so the JavaScript context it was talking to disappeared.
4 causes, each with a fixWeb apps
The shell says pnpm: command not found
npx next dev works, but pnpm dev or pnpm install is not found
The shell cannot find a pnpm executable on PATH.
3 causes, each with a fix