Playwright: Host system is missing dependencies to run browsers
Last verified
Host system is missing dependencies to run browsers.
Please install them with the following command:
sudo npx playwright install-depsWhat it means
The browser binaries downloaded fine, but the operating system lacks the shared libraries they link against (fonts, GTK, NSS, audio, GBM and similar packages). Playwright checks for these before launching and stops with this message instead of letting the browser crash with a cryptic loader error. It is almost always seen on Linux: minimal Docker images, WSL, CI runners and servers that have never run a desktop browser.
The message tailors its advice. On supported Ubuntu and Debian versions it prints the exact install-deps command or apt-get install list. Inside a Playwright Docker image whose version does not match the library, it says the image version does not match and recommends the matching image. On unsupported distributions it lists the missing .so files instead.
What is not wrong: your test code and your browser download. This is purely an OS package issue.
What it looks like
# Dockerfile using the matching official image
FROM mcr.microsoft.com/playwright:v1.56.0-noble
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npx", "playwright", "test"]
# Or on a plain Ubuntu host
npx playwright install --with-deps chromiumWhy it happens
- Running on a slim base image (node:slim, python:slim, alpine) that does not include browser libraries.
- Using a Playwright Docker image built for a different Playwright version than the one installed in the project.
- Running on a Linux distribution Playwright does not officially support, so install-deps cannot map libraries to packages.
- A new Playwright release requires a library that an older environment never installed.
How to fix it
- Run the command from the message: sudo npx playwright install-deps (Node.js) or sudo playwright install-deps (Python).
- Combine both steps in one: npx playwright install --with-deps chromium.
- In Docker, switch to the official image mcr.microsoft.com/playwright:v1.xx.x-noble with the same version as your package.
- On unsupported distributions, install each listed .so file with your package manager, or move to Ubuntu or Debian.
- Re-run the launch to confirm; the check runs every time a browser starts.
How to stop it recurring
Build automation images from the official Playwright image or run install --with-deps during image build, never at run time. Keep the image tag and the Playwright package version in lockstep, ideally updated by the same dependency bot. Stay on a supported Ubuntu or Debian release for runners that launch browsers.
Official documentation: playwright.dev/docs/browsers#install-system-dependencies. See all Playwright error messages.
Related errors
Definitions
- PlaywrightPlaywright is Microsoft's open-source browser automation framework that provides a single API to control Chrom
- Chrome DevTools Protocol (CDP)The Chrome DevTools Protocol (CDP) is the JSON-over-WebSocket interface Chrome exposes for inspecting and cont
- CSS SelectorA CSS selector is a pattern used to identify and target specific HTML elements on a web page, widely used in b
- Headless ChromeHeadless Chrome is Google Chrome running without a visible window. It renders pages and runs JavaScript like n
- IframeAn iframe (inline frame) is an HTML element that embeds a separate web page within a parent page, creating an
- Web ElementA web element is any individual component rendered on a web page — buttons, links, input fields, images, text
Quick answers
What does "Host system is missing dependencies to run browsers" mean in Playwright?
The browser binaries downloaded fine, but the operating system lacks the shared libraries they link against (fonts, GTK, NSS, audio, GBM and similar packages). Playwright checks for these before launching and stops with this message instead of letting the browser crash with a cryptic loader error.
How do I fix "Host system is missing dependencies to run browsers"?
1. Run the command from the message: sudo npx playwright install-deps (Node.js) or sudo playwright install-deps (Python). 2. Combine both steps in one: npx playwright install --with-deps chromium. 3. In Docker, switch to the official image mcr.microsoft.com/playwright:v1.xx.x-noble with the same version as your package. 4. On unsupported distributions, install each listed .so file with your package manager, or move to Ubuntu or Debian. 5. Re-run the launch to confirm; the check runs every time a browser starts.
Run browser automation you can watch and take over
Autonoly runs each job in a real cloud Chromium browser driven by Playwright. Timeouts and detached elements still happen; the difference is that you can watch the run live, see the step that failed, and take control of the browser to finish it.
Also see Live browser control.