WebCrawler API logoWebCrawler API

Playwright chromium install failing on Ubuntu 26.04 (OS detection)

Playwright

npx playwright install --with-deps chromium fails on Ubuntu 26.04 with something like Unsupported platform: ubuntu26.04-x64 or a system dependency install that silently skips packages. This isn't a broken browser download — it's the Playwright CLI's OS-detection step failing to recognize a release it was shipped before. Older @playwright/test versions ship a hardcoded map of known Linux distros to their apt package lists, and a newer Ubuntu release simply isn't in that map yet.

Common mistake

# playwright.config.ts uses @playwright/test 1.44 or older
npm install -D @playwright/test@1.44.0
npx playwright install --with-deps chromium

Error: Failed to install browser dependencies
Unsupported platform: ubuntu26.04-x64

Pinning an old Playwright version (common in projects that haven't bumped dependencies in a while) means the installer's distro table stops at whatever Ubuntu LTS existed when that version shipped. When it reads /etc/os-release and sees 26.04, it has no matching entry, so it can't decide which apt packages Chromium needs and bails instead of guessing.

The fix

The most durable fix is upgrading Playwright so its distro table actually includes Ubuntu 26.04:

npm install -D @playwright/test@latest
npx playwright install --with-deps chromium

If you can't upgrade yet (locked dependency tree, CI image pinned for other reasons), tell Playwright to treat the host as the nearest release it does know about:

PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04 npx playwright install --with-deps chromium

This skips the OS-detection step entirely and uses Ubuntu 24.04's dependency list, which is close enough for Chromium's runtime libraries in practice.

If neither option is available, install the system dependencies yourself and skip --with-deps:

sudo apt-get update
sudo apt-get install -y \
  libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
  libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
  libxrandr2 libgbm1 libasound2t64 libpango-1.0-0 libcairo2 \
  fonts-liberation fonts-noto-color-emoji

npx playwright install chromium

For CI, the cleanest option is to stop detecting the host OS at all and run inside Playwright's official image, which already has every dependency baked in for a known Ubuntu base:

FROM mcr.microsoft.com/playwright:v1.48.0-jammy

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .

CMD ["npx", "playwright", "test"]

Why it works

playwright install --with-deps doesn't ask the OS for its own dependency list — it maps /etc/os-release to a table Playwright's own team maintains and ships inside the package. That table is only ever as current as the Playwright version installed, so a release the maintainers hadn't cut a version for yet reads as "unsupported" even though the underlying Ubuntu is perfectly capable of running Chromium. Upgrading Playwright pulls in an updated table. PLAYWRIGHT_HOST_PLATFORM_OVERRIDE bypasses the lookup and forces a specific, known entry instead of failing on a miss. Installing the apt packages directly removes Playwright's detection step from the equation completely — playwright install chromium (no --with-deps) only downloads the browser binary and never inspects the OS. The Docker image sidesteps the whole problem because the OS inside the container is fixed and already validated by Playwright's own release process — nothing to detect, nothing to fall through.

Tips

  • Check npx playwright --version and compare it against Playwright's release notes before assuming this is a hard blocker — newer Ubuntu support is often added within a few point releases.
  • PLAYWRIGHT_HOST_PLATFORM_OVERRIDE is a stopgap for local dev and short-lived CI runners, not a permanent fix — it can drift as glibc and system library versions diverge from the overridden release.
  • If your CI already builds a custom base image, layer apt-get install for the exact packages playwright install --with-deps would have run, then cache that image — it's faster than re-resolving dependencies on every run anyway.
  • Missing system libraries and missing fonts produce different failure modes (a crash on launch vs. broken emoji/CJK rendering in screenshots) — see how to fix Playwright CI missing OS deps and fonts if your failure looks more like a rendering issue than an install-time error.