Playwright でブラウザが起動できない（Executable doesn't exist）

「Executable doesn't exist」は、npm パッケージとは別に管理されるブラウザバイナリが未取得なのが原因。
npx playwright install で取得する。
バージョン更新直後や CI のキャッシュ不整合でも起きる。

#playwright #install #browser #chromium #ci

公開: 2026-06-13更新: 2026-09-25

実行例あり（2026-09-18 に実環境で検証）

要約

browserType.launch: Executable doesn't exist at /home/user/.cache/ms-playwright/... が出てブラウザが起動できないのは、npm パッケージとは別に管理されるブラウザバイナリが取得されていない ことが原因。npx playwright install を一度実行すれば解決する。
Playwright をバージョンアップした直後や、CI でキャッシュを部分的にしか復元していない場合にも同じエラーが出る。

実行例

パッケージを入れただけの状態でテストを走らせると、Executable doesn't exist at /root/.cache/ms-playwright/... と npx playwright install を促す枠が出て終了コード 1 になる。npx playwright install chromium でキャッシュディレクトリにバイナリが並ぶとテストは通り、PLAYWRIGHT_BROWSERS_PATH を実行時だけ別の場所に向けると同じエラーに戻る。

$ npx playwright test --reporter=line
Running 1 test using 1 worker
 
[1/1] example.spec.js:3:1 › 見出しが表示される
  1) example.spec.js:3:1 › 見出しが表示される ───────────────────────────────────────────────────────────────
 
    Error: browserType.launch: Executable doesn't exist at /root/.cache/ms-playwright/chromium_headless_shell-1243/chrome-headless-shell-linux64/chrome-headless-shell
    ╔════════════════════════════════════════════════════════════╗
    ║ Looks like Playwright was just installed or updated.       ║
    ║ Please run the following command to download new browsers: ║
    ║                                                            ║
    ║     npx playwright install                                 ║
    ║                                                            ║
    ║ <3 Playwright Team                                         ║
    ╚════════════════════════════════════════════════════════════╝
 
    Error Context: test-results/example-見出しが表示される/error-context.md
 
  1 failed
    example.spec.js:3:1 › 見出しが表示される ────────────────────────────────────────────────────────────────
終了コード: 1

$ npx playwright install chromium 2>&1 | grep -v '^|'
Downloading Chrome for Testing 153.0.8010.12 (playwright chromium v1243) from https://cdn.playwright.dev/builds/cft/153.0.8010.12/linux64/chrome-linux64.zip
Chrome for Testing 153.0.8010.12 (playwright chromium v1243) downloaded to /root/.cache/ms-playwright/chromium-1243
Downloading FFmpeg (playwright ffmpeg v1011) from https://cdn.playwright.dev/dbazure/download/playwright/builds/ffmpeg/1011/ffmpeg-linux.zip
FFmpeg (playwright ffmpeg v1011) downloaded to /root/.cache/ms-playwright/ffmpeg-1011
Downloading Chrome Headless Shell 153.0.8010.12 (playwright chromium-headless-shell v1243) from https://cdn.playwright.dev/builds/cft/153.0.8010.12/linux64/chrome-headless-shell-linux64.zip
Chrome Headless Shell 153.0.8010.12 (playwright chromium-headless-shell v1243) downloaded to /root/.cache/ms-playwright/chromium_headless_shell-1243

$ ls /root/.cache/ms-playwright
chromium-1243
chromium_headless_shell-1243
ffmpeg-1011

$ npx playwright test --reporter=line
Running 1 test using 1 worker
 
[1/1] example.spec.js:3:1 › 見出しが表示される
  1 passed (478ms)
終了コード: 0

$ PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers npx playwright test --reporter=line
Running 1 test using 1 worker
 
[1/1] example.spec.js:3:1 › 見出しが表示される
  1) example.spec.js:3:1 › 見出しが表示される ───────────────────────────────────────────────────────────────
 
    Error: browserType.launch: Executable doesn't exist at /opt/pw-browsers/chromium_headless_shell-1243/chrome-headless-shell-linux64/chrome-headless-shell
    ╔════════════════════════════════════════════════════════════╗
    ║ Looks like Playwright was just installed or updated.       ║
    ║ Please run the following command to download new browsers: ║
    ║                                                            ║
    ║     npx playwright install                                 ║
    ║                                                            ║
    ║ <3 Playwright Team                                         ║
    ╚════════════════════════════════════════════════════════════╝
 
    Error Context: test-results/example-見出しが表示される/error-context.md
 
  1 failed
    example.spec.js:3:1 › 見出しが表示される ────────────────────────────────────────────────────────────────
終了コード: 1

$ PLAYWRIGHT_BROWSERS_PATH=/root/.cache/ms-playwright npx playwright test --reporter=line
Running 1 test using 1 worker
 
[1/1] example.spec.js:3:1 › 見出しが表示される
  1 passed (430ms)
終了コード: 0

— 2026-09-18 時点の出力

検証環境

検証日

2026-09-18

実行環境

node:20Debian GNU/Linux 12 (bookworm)

バージョン

Node.js 20.20.2
npm 10.8.2
Python 3.11.2
Git 2.39.5

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

よくある原因

ブラウザ未インストール: npm install は @playwright/test 本体しか入れず、Chromium などの実体は別途取得が必要
バージョン更新後の再取得漏れ: Playwright は各バージョンが特定リビジョンのブラウザ（例: chromium-1148）に紐づくため、更新すると既存バイナリでは起動できない
CI のキャッシュ不整合: node_modules だけ復元し、ブラウザの置き場所（Linux では ~/.cache/ms-playwright）を復元していない
PLAYWRIGHT_BROWSERS_PATH の食い違い: インストール時と実行時で参照先ディレクトリが異なる

解決策

1. ブラウザをインストールする

npx playwright install
# Chromium だけで十分な場合
npx playwright install chromium

取得先やリビジョンの仕組みは公式ドキュメントの Browsers（新しいタブで開く）に詳しい。

2. バージョン更新時に再実行する

npm install -D @playwright/test@latest
npx playwright install

package.json の更新とブラウザの再取得は 必ずセット で行う。

3. CI では --with-deps を使う

- run: npx playwright install --with-deps

Linux ランナーではブラウザ本体に加えて OS の依存ライブラリも必要なため、--with-deps を付けるか、すべて同梱済みの公式 Docker イメージ（mcr.microsoft.com/playwright）を使う。
設定例は公式の CI ガイド（新しいタブで開く）を参照。

4. PLAYWRIGHT_BROWSERS_PATH を揃える

ブラウザの置き場所を PLAYWRIGHT_BROWSERS_PATH で変えている場合、インストール時と実行時の両方で同じ値を設定する。
片方だけ設定されていると、取得済みでも「Executable doesn't exist」になる。

要約

実行例