How to Fix Playwright "Host system is missing dependencies"

TL;DR

On supported Linux, run npm ci and npx playwright install --with-deps chromium in the actual test runtime. Verify with npx playwright install-deps --dry-run chromium and a browser launch. In Docker, match the official image tag to the project Playwright version.

Key Takeaways

• Run install --with-deps for the browser in the environment that executes tests.
• Use install-deps --dry-run to check Linux packages without changing the host.
• Separate a missing browser binary from missing native libraries.
• Pin official Docker image tags to the project Playwright version.
• Use a supported Debian or Ubuntu base for custom browser containers.
• Verify with a direct browser launch before debugging application tests.

Fix Playwright Host System Is Missing Dependencies by installing the browser's native libraries in the Linux environment that runs your tests. The error appears during Playwright browser installation or launch when that environment lacks required libraries.

Host system is missing dependencies to run browsers.

In a Node.js project, the quickest supported command is npx playwright install --with-deps chromium; replace chromium with the browser you actually run.

The message is about the host, not your locators or assertions. A browser executable can already exist and still fail this check. Follow the decision table below before changing a Dockerfile, a CI job, or a local machine.

TL;DR

From a project that already has @playwright/test installed, run the following on a supported Ubuntu or Debian host:

npm ci
npx playwright install --with-deps chromium
npx playwright install-deps --dry-run chromium
npx playwright test --project=chromium

The third command checks Linux packages without changing them and should exit successfully. Use npx playwright install --with-deps with no browser name if your suite uses Chromium, Firefox, and WebKit. Run the install step inside the container, CI worker, WSL distribution, or remote development environment that actually launches the browser. The Playwright browser installation guide documents both install-deps and --with-deps.

If the test instead says Executable doesn't exist, install the browser binary with npx playwright install chromium and use the missing Playwright executable guide to diagnose its cache path. Installing a binary does not supply native Linux libraries, and installing libraries does not download a binary.

What the Error Actually Means

Playwright downloads browser builds separately from the npm package. Those builds depend on native libraries supplied by the operating system, including graphics, font, audio, and media libraries. At launch, Playwright checks the runtime environment and reports missing shared libraries or packages. The exact package list changes with the browser, Playwright release, and supported Linux distribution, so a copied apt-get install list from an old issue is a weak fix.

You may see the boxed message after browserType.launch, during npx playwright install, or in a CI log labeled Playwright Host validation warning. The first line is stable enough to identify this failure; the later lines can show a suggested install-deps command, missing library names, or a Docker image version warning. Read those later lines before acting. The Playwright source for dependency validation constructs the diagnostic, including its special advice for version mismatched Docker images.

Playwright's CLI targets a browser by name. npx playwright install-deps chromium installs native packages needed for Chromium; npx playwright install chromium downloads its browser build. npx playwright install --with-deps chromium requests both. That distinction matters when a build stage copied a browser cache from elsewhere, or when a CI worker restores npm dependencies but starts with a clean OS. It also explains why clearing node_modules alone rarely repairs a missing .so library.

Start by identifying the runtime. uname -a and cat /etc/os-release describe a Linux runner, while npx playwright --version reports the CLI selected from the project. Keep the package lock in the diagnosis. npx run outside a project can select a different installation from the one your tests import, which changes the required browser builds and package set.

Root-Cause Decision Table

Treat the table as triage, not as a list of commands to run on every machine. A failing WebKit launch does not imply your Chromium setup is broken. A Docker version mismatch can produce the same headline while requiring a different repair from a plain Ubuntu runner.

1. How to Fix Playwright Host System Is Missing Dependencies on Ubuntu or Debian

Install the operating system libraries and browser build together from the locked project. First confirm that the host is a supported Playwright system. Current documentation names supported Ubuntu and Debian releases; package names vary by release. Run the commands in a terminal on the host where tests execute, from the directory containing package-lock.json:

cat /etc/os-release
npm ci
npx playwright --version
npx playwright install --with-deps chromium

npm ci selects the project's locked Playwright CLI. The final command may request root privileges because it invokes the Linux package manager. In a container build or managed CI job, arrange for this step to have the necessary package permissions. Do not guess a list of lib* packages from another distribution. Playwright's installer maintains the dependency set for its browser builds.

Verify the package state with the CLI's non-mutating check, then launch Chromium directly. The direct launch isolates host setup from application startup, test data, and browser project configuration:

npx playwright install-deps --dry-run chromium
node -e "const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch(); console.log('Chromium launched'); await browser.close(); })().catch(error => { console.error(error); process.exitCode = 1; });"

The dry run should exit zero; the Node command should print Chromium launched. If your project uses only @playwright/test, its transitive playwright package normally provides the import used by the one-line probe. Run npm ls playwright @playwright/test if that import cannot be resolved. An import failure is a Node package problem, so keep it separate from host dependency validation.

If install --with-deps succeeds but the dry run still fails, inspect the output for an unavailable package or unsupported OS release. Record cat /etc/os-release, the Playwright version, the targeted browser, and the missing library line. Those facts identify whether the package manager, OS support, or the browser's dependency check is still blocking launch. Do not suppress the warning: it can precede an actual browser launch failure.

2. Install dependencies for the browser your test project really uses

A common partial fix is to install Chromium alone while playwright.config.ts also defines Firefox or WebKit projects. The suite may pass locally when only a Chromium project is selected, then fail in a full CI run. Read the configured projects array, or list projects through the test runner:

npx playwright test --list
npx playwright install-deps --dry-run chromium
npx playwright install-deps --dry-run firefox
npx playwright install-deps --dry-run webkit

A failure in only one dry run points to a browser-specific native package set. Install just the missing target if your CI matrix runs each browser in a separate job:

npx playwright install --with-deps webkit
npx playwright install-deps --dry-run webkit
npx playwright test --project=webkit

The final command verifies the real configured project. It assumes the project is named webkit; use the name shown by your configuration if it differs. For a suite that truly runs all three browser engines on one machine, use npx playwright install --with-deps without a browser argument and then run each project. The CLI reference documents browser arguments and the Linux install-deps --dry-run behavior.

Avoid installing every browser just to quiet a warning from a job that never runs them. Separate jobs can carry smaller images and make one engine's package failure easier to trace. On the other hand, a shared job must provision all engines it actually launches. Changing a project from WebKit to Chromium solely to get a green build would remove coverage, not fix the host.

When the log names a specific missing .so file, preserve that line in your issue report. It can reveal a distribution package mismatch, particularly after an OS upgrade. Still prefer the current CLI's dependencies for the selected engine before manually mapping a library name to an apt package. That mapping is distribution specific, and a package with the same purpose may have a different name on another release.

3. How to Fix Playwright Host System Is Missing Dependencies in Docker

The official Playwright image includes browsers and system dependencies, but the project still needs its npm packages. The image tag must match the Playwright version your test package uses. The official Docker guide warns that a mismatched image may leave the project unable to find its expected browser executables, and Playwright's host diagnostic has specific version mismatch text.

Check the package version before choosing a tag:

npm ci
node -p "require('@playwright/test/package.json').version"

Replace <your-playwright-version> in this Dockerfile with the Playwright version in package.json. Confirm that it matches the installed version printed above; if package.json specifies a version range, use the exact version resolved in package-lock.json for the image tag:

FROM mcr.microsoft.com/playwright:v<your-playwright-version>-noble
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["npx", "playwright", "test", "--project=chromium"]

Build and run from the test project's directory. The commands below verify that the image has the right CLI, that Chromium's native packages pass the dry run, and that the project's tests execute:

docker build -t playwright-host-check .
docker run --rm --init --ipc=host playwright-host-check npx playwright --version
docker run --rm --init --ipc=host playwright-host-check npx playwright install-deps --dry-run chromium
docker run --rm --init --ipc=host playwright-host-check

--init and --ipc=host follow Playwright's Docker recommendations, especially for Chromium. If your test app is another container, connect the two containers through a Docker network and use its service name in the test URL. localhost inside the Playwright container refers to that container, not automatically to the host or sibling service.

Do not assume the official image contains @playwright/test: its documentation says the npm package is installed separately. Also avoid a floating latest image tag. Pinning the image and package together makes the native libraries and browser revisions reviewable during upgrades. See Docker for Playwright tests for the broader image and networking setup, and Docker basics for testers if image layers or container filesystems are unfamiliar.

4. Replace an unsupported or overly minimal Linux base image

Playwright's Firefox and WebKit browser builds rely on glibc; Alpine uses musl and is not a supported base for those builds. A minimal Debian image can also lack the package indexes or libraries that the browsers require. If install-deps cannot resolve packages, verify the actual base distribution before adding ad hoc libraries. The current system requirements list supported Debian and Ubuntu releases, and the Docker docs explicitly call out Alpine's limitation.

For a custom image, start with a supported Debian base and install the project dependencies before downloading browsers. This complete Dockerfile uses an official Node image based on Debian 12. It provisions Chromium in the same image that will run the tests:

FROM node:24-bookworm
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
RUN npx playwright install --with-deps chromium
COPY . .
CMD ["npx", "playwright", "test", "--project=chromium"]

Verify the base release and browser launch inside the built artifact:

docker build -t playwright-debian-check .
docker run --rm --init --ipc=host playwright-debian-check cat /etc/os-release
docker run --rm --init --ipc=host playwright-debian-check npx playwright install-deps --dry-run chromium
docker run --rm --init --ipc=host playwright-debian-check

Use a .dockerignore for node_modules and generated output so COPY . . does not overlay container-installed dependencies with files from your laptop. That note matters because the build can succeed while a later copy replaces Linux modules or cache metadata. If your project runs Firefox or WebKit as well, remove the chromium selector in the installation step and adapt the test command to run the desired projects.

A successful apt-get install on Alpine is not a meaningful outcome because Alpine does not use apt. Likewise, downloading browsers on one base image and copying only their directory into a distroless runtime does not carry their native dependencies. Install into the final runtime image or use the official Playwright image with a matching version. Test the final image, not just a builder stage.

5. Give the dependency installer the package permissions it needs

install-deps invokes the OS package manager. A runner with no root privileges may fail before installing any library, even though npm and browser downloads work. The fix is to run the system-package step where root access is available, such as a Docker build stage, a provisioned machine image, or a CI setup step with package permissions. An npm script running as an unprivileged application user cannot grant itself those capabilities.

On a supported Ubuntu runner where sudo is available, separate the native dependency operation from browser download. This makes permission failures visible:

npm ci
sudo npx playwright install-deps chromium
npx playwright install chromium
npx playwright install-deps --dry-run chromium

The last command verifies the installed package set without requiring another install. Then run npx playwright test --project=chromium to confirm browser launch through the actual suite. If sudo is unavailable, place npx playwright install --with-deps chromium in a root-owned Docker build step as shown above. Do not run tests as root merely to avoid designing an installation phase; separate installation permissions from routine test execution when your environment supports it.

Corporate proxies can make this look like a dependency error when apt fails to fetch packages. Inspect the installer output for apt-get download or repository errors. Playwright's browser docs show that on Linux, proxy variables must reach the package manager when elevation occurs. If your organization uses an HTTPS proxy, configure its approved proxy and CA settings for the root-owned install step, then repeat the dry run. Avoid copying a sample proxy URL into a real workflow.

The verification boundary is precise: install-deps --dry-run chromium returns success, and a Chromium launch succeeds in the same runtime. A successful npm ci proves neither. For a general CI setup checklist, include this OS provisioning stage before the test command rather than hiding it in a retry loop.

6. Install in the CI, WSL, or remote environment that launches the browser

Your laptop and CI agent do not share native libraries. Neither do Windows and its WSL distribution, a remote development container and its host, or a Docker build stage and an unrelated final image. The command must run in the environment where the browser process starts. A local green run is useful evidence about the test code, but it does not prove that a newly created Linux worker has the required packages.

A GitHub Actions workflow for a project with a Chromium Playwright project can provision the job in order. The install --with-deps step comes after npm ci, so it uses the locked CLI version, and before the test run:

name: Playwright
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright install-deps --dry-run chromium
      - run: npx playwright test --project=chromium

A successful dry-run step verifies the OS package portion before test failures can distract the diagnosis. The official Playwright CI guide uses the same package-install, browser-install, test sequence. For a project that runs all configured engines, omit chromium from the install step and use npx playwright test for the final command. Keep the actual --project value aligned with your config.

In WSL, open the Linux shell and run the commands there. Installing a Windows browser or Windows system component will not satisfy Linux shared libraries in WSL. Confirm the distribution and installed CLI from that shell:

cat /etc/os-release
npm ci
npx playwright install --with-deps chromium
npx playwright install-deps --dry-run chromium
npx playwright test --project=chromium

For a self-hosted CI machine, use the same probe on the agent account, not only in an administrator's interactive session. Document how the agent image is rebuilt after Playwright upgrades. If you cache only ~/.cache/ms-playwright, remember that this cache contains browser downloads, not all operating system packages; Playwright's CI documentation does not recommend relying on browser caching to avoid setup.

See GitHub Actions for Playwright for job design and artifact handling. The specific host-dependency guard belongs in the job or image that executes tests, because a separate prepare job cannot install apt packages into another fresh runner.

How to Verify the Fix

Verify in layers. First confirm the target environment and CLI version. Next run the non-mutating package check for every browser you intend to use. Finally launch a browser and run the relevant project. This order tells you which boundary still fails without turning a product test failure into an installation mystery.

cat /etc/os-release
npx playwright --version
npx playwright install-deps --dry-run chromium
npx playwright install --list
node -e "const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch(); console.log('launch OK'); await browser.close(); })().catch(error => { console.error(error); process.exitCode = 1; });"
npx playwright test --project=chromium

install --list reports browser installations, but it does not validate host libraries; pair it with the dry run. A successful direct launch proves the runtime can start Chromium, while the final test command also checks your config and application setup. If your suite has no chromium project, use its actual project name. If the direct launch succeeds and tests fail on a locator or network error, continue with normal test debugging rather than reinstalling system packages.

For Firefox and WebKit, repeat the dry run and launch with their real browser names. Keep the Playwright version and /etc/os-release output with the failure log. If the warning remains after the package check passes, inspect whether the command and test run use different containers, users, images, or Playwright versions. DEBUG=pw:browser npx playwright test --project=chromium can expose launch details; the Playwright CI documentation recommends that debug namespace for browser launch failures.

There is no need to assert that a whole application passes before declaring the host repaired. The direct launch is a clean host-level acceptance test. Application-specific failures deserve their own investigation once the browser process starts. This separation keeps an infrastructure fix from masking a genuine regression.

Prevent It From Coming Back

Put the dependency installation next to the test command in each Linux CI job, or bake it into a versioned image that the job actually runs. Pin the project's Playwright package through its lockfile. When upgrading Playwright, rebuild the image or rerun install --with-deps; a newer Playwright release can require a different browser build and system packages. Review the browser version guidance during those upgrades.

Choose one browser scope deliberately. A Chromium-only job should install and check Chromium. A cross-browser job needs all selected engines. Record the OS release, image tag, Playwright version, and target projects in CI logs so a future failure has enough context. Use the dry-run command as a fast setup gate on Linux, then keep at least one real launch test. The gate checks packages; the launch catches remaining runtime problems.

For Docker, pin the official image to the same Playwright version as the project, or build your own supported Debian or Ubuntu image and run install --with-deps there. Test the final runtime image after all COPY and USER instructions. A dependency installed in a disposable builder stage is not available in the final image unless the relevant system files are intentionally carried over, which is usually more fragile than installing in the final stage.

Avoid solving the warning by setting a skip-validation environment variable or by swallowing launch exceptions. That changes the diagnostic, not the availability of shared libraries. The stable prevention measure is a reproducible install step plus a check executed in the same environment as the browser. Treat infrastructure drift as part of the test framework's maintenance, alongside the Playwright CI setup guide.

Interview Questions and Answers

Q: What does the host-system warning tell you?

It tells me Playwright's browser build cannot find required native dependencies on the machine that launches it. I identify the browser and OS release before installing anything. I also distinguish the warning from a missing browser executable, which needs a browser download.

Q: What is the fastest supported repair on Ubuntu for Chromium?

From the project directory, I run npm ci and npx playwright install --with-deps chromium. I verify with npx playwright install-deps --dry-run chromium and a Chromium launch. That tests the package state and the actual process boundary.

Q: Why might Chromium pass while WebKit fails?

The engines have different native library requirements. A Chromium-scoped install does not prove WebKit's packages are present. I run WebKit's dry run, install its dependencies, and rerun its configured project.

Q: Why can a Playwright Docker image still fail?

The official image supplies browsers and native packages, but the npm dependency is installed by the project. A package version that does not match the image tag can ask for a different browser revision. I compare the locked package version with the image tag and test the final image.

Q: Why does installing on a laptop not repair GitHub Actions?

GitHub Actions starts a separate runner with its own OS packages. I add the install step to the workflow after npm ci, then run a dry check and the test project in that job. I do not assume browser cache restoration supplies system libraries.

Q: When would you reject Alpine for this setup?

I would reject it when using Playwright's supported Firefox or WebKit browser builds, which depend on glibc. I choose a supported Debian or Ubuntu base and install the selected browsers there. That avoids chasing incompatible package names in a musl environment.

Common Mistakes

• Running npm install repeatedly and expecting apt libraries to appear. npm installs JavaScript packages; the browser still needs OS packages.
• Running npx playwright install chromium alone and assuming --with-deps was implied. The browser download and Linux dependency install are separate operations.
• Copying an old list of lib* packages into a current Dockerfile. Use the CLI for the locked Playwright version and supported OS release.
• Installing on the host while tests run in Docker, or installing in WSL while tests run in Windows. Check the process environment that launches the browser.
• Using a mismatched official image tag and project package. Compare the locked Playwright version with the image tag before adding manual packages.
• Treating install --list as a dependency check. It lists browser installations; install-deps --dry-run checks Linux packages.
• Replacing WebKit with Chromium to make CI green without acknowledging the lost browser coverage. Install the intended engine's dependencies and keep the project.
• Silencing the host-validation message without a launch probe. A quiet log is not proof that the browser can start.

Conclusion

To Fix Playwright Host System Is Missing Dependencies, install the selected browser's native packages where that browser actually runs, then prove the fix with install-deps --dry-run and a real launch. Use npx playwright install --with-deps chromium for a supported Chromium-only Linux job, broaden the browser scope when the suite needs it, and keep Docker image versions aligned with the project package.

Once the host check passes, run the relevant project and investigate any remaining test failure on its own merits. If you are preparing a QA automation interview, practice explaining this distinction and the verification sequence in QAJobFit interview practice.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• How to Fix Playwright "Element is not attached to the DOM"
• How to Fix Playwright element is not visible
• How to Fix Playwright element is outside of the viewport
• How to Fix Playwright locator resolved to hidden element
• How to Fix Playwright waiting for element to be visible enabled and stable
• How to Fix "Cannot find module '@playwright/test'" in Playwright