skip to content

What does the --with-deps flag add to npx playwright install on a fresh Linux machine?

level: middleimportance: must knowfreq 61%

answer

  1. Two different missing things
  2. Engine download versus system libraries
  3. Runs the platform package manager
  4. Needs root on Linux
  5. Pointless on macOS

basics

~10 s

It installs the operating-system shared libraries the engine binaries link against, on top of downloading the engines themselves. On Linux it runs the system package manager as root; on macOS it is unnecessary.

solid answer

~40 s

`npx playwright install` only downloads the engine builds. Those binaries then need font, graphics, audio and windowing libraries from the operating system, which a desktop Linux install usually has and a minimal one does not. `--with-deps` adds that second step, shelling out to `apt-get` on Debian and Ubuntu family systems and asking for sudo; `npx playwright install-deps` performs the same half on its own when the engines are already present. Skip it on a bare Linux box and the download succeeds but the first launch fails with `Host system is missing dependencies to run browsers.`, followed by the missing packages. It is kept behind a flag rather than made the default because it modifies the host system-wide, unlike a download into Playwright's own cache.

code

bash · 3 lines
bash
npx playwright install --with-deps chromium
npx playwright install-deps
npx playwright install-deps --dry-run

go deeper

for a junior

Remember that on Linux the engine download alone may not be enough, and that --with-deps also installs the system libraries the browsers need before they will start.

for a middle

Explain the split cleanly: install fetches engine binaries into a cache, the dependency step invokes the platform package manager as root, and install-deps does that half alone.

for a senior

Recognise the signature in the field. A suite-wide failure at browser start-up naming missing packages is an environment gap, not flakiness, and the fix belongs where the machine is provisioned.

for a principal

Decide where host mutation is allowed to happen at all, and keep a step that installs system packages as root out of routine developer commands unless the machine is disposable.

## Two different kinds of missing thing `npx playwright install` fetches the **engine builds** — the Chromium, Firefox and WebKit binaries Playwright pins to its own version — into the `ms-playwright` cache folder. That is a download, and it needs no elevated privileges. Those binaries then link against **shared libraries supplied by the operating system**: font, graphics, audio, X11 and GTK libraries that a desktop install of Linux happens to have and a minimal server or container image does not. Installing the engine does nothing about those. `--with-deps` adds that second step, running the platform's package manager to put the missing libraries in place. ## What each command actually does | Command | Downloads engines | Installs OS libraries | Needs root | |---|---|---|---| | `npx playwright install` | yes | no | no | | `npx playwright install --with-deps` | yes | yes | yes, on Linux | | `npx playwright install-deps` | no | yes | yes, on Linux | - `--with-deps` is a **flag on the install command**; `install-deps` is a separate command that does the dependency half alone, useful when the engines are already present. - Both accept an engine name, so `npx playwright install --with-deps chromium` limits the work to one engine rather than pulling libraries for all three. - On Linux the dependency step shells out to `apt-get update` and `apt-get install`, so it targets Debian and Ubuntu family distributions and will prompt for sudo. On other distributions it warns that it cannot install dependencies for that platform and you provide the libraries yourself. - On macOS nothing is needed, and the flag is effectively a no-op. - `npx playwright install-deps --dry-run` reports what is missing without modifying the system. ## The failure it prevents Skip the dependency half on a bare Linux box and the download succeeds — so `--list` shows the engine present — but the first launch fails with **`Host system is missing dependencies to run browsers.`** followed by the list of missing packages and the command that would install them. The tell is a failure that arrives at browser start-up for *every* test in the hotel-booking suite, identically, rather than at any particular assertion. A missing engine and a missing system library look nothing alike: one complains that an executable does not exist, the other that the host is missing dependencies. ## Where it is worth running 1. **Fresh Linux machines and minimal images** — a slim base has almost none of these libraries, so the flag is what turns a downloaded engine into a launchable one. 2. **A new engine added to an existing box** — WebKit and Firefox need libraries Chromium does not, so adding a WebKit project to the booking suite can need a dependency pass even though Chromium has been running for months. 3. **Never on a developer Mac** — reach for it when the platform is Linux; elsewhere it is noise. ## Why it is not simply the default The dependency half changes the machine outside Playwright's own cache: it invokes the system package manager as root and installs packages system-wide. That is a much heavier and less reversible act than dropping binaries into a cache directory, so Playwright keeps it behind an explicit flag. The engine download is safe to run anywhere; installing system libraries is a decision about the host, and the flag is where you make it.

  • How do you tell a missing engine apart from a missing system library?
    The messages differ. A missing engine throws `Executable doesn't exist at ...` with the path it expected and a box naming the install command. Missing libraries throw `Host system is missing dependencies to run browsers.` with the package list. Both hit every test identically, but only the second is fixed by `install-deps`.
  • Why is the dependency step not simply part of the default install?
    Because it changes the host rather than Playwright's own cache. It runs the system package manager as root and installs packages system-wide, which is heavier and less reversible than dropping binaries into a cache directory. Playwright keeps that decision explicit.

saying these in an interview costs you the question

  • Thinks --with-deps downloads extra browsers
  • Believes it is needed on macOS
  • Assumes plain install also fixes missing system libraries
  • Expects it to work without sudo on Linux
  • Confuses the flag with a Node dependency install