Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Playwright cannot open a headed browser on a Linux server or in Docker

ErrorPlaywright will be unable to locate browser executables

Short 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.

  • Applies to Playwright 1.64, Node.js 22, Ubuntu 24.04, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1DISPLAY is empty and xvfb-run is missing; the run fails only with --headedNo display server on the machineFix
    2. 2Playwright will be unable to locate browser executablesThe Docker image tag does not match the Playwright package versionFix
    3. 3The browser starts and then dies, or the page crashes soon after launchChromium crashes in the container without the recommended flagsFix

What does the error look like?

  • Playwright will be unable to locate browser executables
  • npx 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 xvfb

2Fix

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 --headed

3Verify

The run completes and the report shows passed tests.

xvfb-run npx playwright test --headed --reporter=line

Confirmed by playwright.dev

Did this fix it?

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/null

2Fix

Pin the image tag to the same version as the Playwright package.

FROM mcr.microsoft.com/playwright:v1.64.1-noble

3Verify

Rebuild and run the tests inside the container.

docker build -t pw-tests .
docker run --rm --init --ipc=host pw-tests npx playwright test

Confirmed by playwright.dev

Did this fix it?

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_NAME

2Fix

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/bash

3Verify

Run the tests again inside that shell.

npx playwright test

Confirmed by playwright.dev

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.