microsoft/playwright · error · Error

Failed to install WebKit via WSL

Error message

Failed to install WebKit via WSL

What it means

Thrown by the webkit-wsl _install routine when install_webkit_wsl.ps1, executed via powershell.exe, exits with a non-zero code. The PowerShell script is responsible for installing WebKit inside the WSL distribution; a failure means the WSL-side setup did not complete.

Source

Thrown at packages/playwright-core/src/server/registry/index.ts:758

      },
      // WebKit is installed inside the WSL distribution by install_webkit_wsl.ps1.
      wslExecutablePath: `/home/pwuser/.cache/ms-playwright/webkit-${webkit.revision}/pw_run.sh`,
      installType: 'download-on-demand',
      title: 'Webkit in WSL',
      _validateHostRequirements: (sdkLanguage: string) => Promise.resolve(),
      _isHermeticInstallation: true,
      _install: async () => {
        if (process.platform !== 'win32')
          throw new Error(`WebKit via WSL is only supported on Windows`);
        const script = path.join(BIN_PATH, 'install_webkit_wsl.ps1');
        const { code } = await spawnAsync('powershell.exe', [
          '-ExecutionPolicy', 'Bypass',
          '-File', script,
        ], {
          stdio: 'inherit',
        });
        if (code !== 0)
          throw new Error(`Failed to install WebKit via WSL`);
      },
    });

    const ffmpeg = descriptors.find(d => d.name === 'ffmpeg')!;
    const ffmpegExecutable = findExecutablePath(ffmpeg.dir, 'ffmpeg');
    this._executables.push({
      name: 'ffmpeg',
      browserName: undefined,
      directory: ffmpeg.dir,
      executablePath: () => ffmpegExecutable,
      executablePathOrDie: (sdkLanguage: string) => executablePathOrDie('ffmpeg', ffmpegExecutable, ffmpeg.installByDefault, sdkLanguage),
      installType: ffmpeg.installByDefault ? 'download-by-default' : 'download-on-demand',
      _validateHostRequirements: () => Promise.resolve(),
      downloadURLs: this._downloadURLs(ffmpeg),
      title: ffmpeg.title,
      revision: ffmpeg.revision,
      _install: force => this._downloadExecutable(ffmpeg, force, ffmpegExecutable),
      _dependencyGroup: 'tools',

View on GitHub (pinned to c8fc3bf8d3)

Solutions

  1. Ensure WSL is installed and a default distribution is set (wsl --install, then wsl --set-default), and reboot if WSL was just enabled.
  2. Re-run the install from an elevated PowerShell session and capture the script's own output to see the underlying failure.
  3. Check network/proxy connectivity from inside WSL, and that the pwuser cache directory is writable; if WSL is unusable, fall back to running webkit on a Linux runner.

Example fix

# elevate, ensure WSL is healthy
wsl --install
wsl --set-default Ubuntu
# then re-run
npx playwright install webkit-wsl
Defensive patterns

Strategy: try-catch

Validate before calling

import { execSync } from 'node:child_process';
try { execSync('wsl --status', { stdio: 'pipe' }); }
catch { throw new Error('WSL not ready; run wsl --install and reboot'); }

Try / catch

try {
  await installWebKitWsl();
} catch (e) {
  if (/Failed to install WebKit via WSL/.test(e.message)) {
    // verify WSL is installed/defaulted, re-run elevated, check proxy in WSL, then retry once
  } else throw e;
}

Prevention

When it happens

Trigger: WSL is not installed or no default distribution is set; the powershell script lacks privileges; the WSL distribution cannot download the webkit revision (network/proxy); the pwuser home/cache path is unwritable; WSL itself is broken or partially installed.

Common situations: Windows CI without WSL pre-installed; corporate proxy blocking downloads inside WSL; WSL2 not enabled at the OS feature level; a corrupted WSL distribution.

Related errors

AI-assisted analysis of microsoft/playwright@c8fc3bf8d3 (2026-08-12). Data as JSON: /api/errors/f86eb9e346a980ce. Report an issue: GitHub.