WebCrawler API logoWebCrawler API

How to fix Playwright headless_shell.exe missing DLL error on Windows?

Playwright

Playwright on Windows fails to launch headless_shell.exe with an error about missing DLL files — often vcruntime140.dll, msvcp140.dll, vcruntime140_1.dll, or similar — even when the browser binaries are installed and the file physically exists on disk. This is a Windows-specific root cause: the Chromium binary relies on the Microsoft Visual C++ Redistributable runtime, which is not pre-installed on all Windows machines. The browser binary is present (headless_shell.exe can be found at %LOCALAPPDATA%\ms-playwright\chromium-xxxx), but the Windows operating system cannot start the process because a required system DLL is missing.

Common mistake

# Install Playwright and browsers on Windows
npm install @playwright/test
npx playwright install

# Try to run tests
npx playwright test
# Error: cannot start process C:\Users\...\ms-playwright\chromium-1234\headless_shell.exe
# Cause: vcruntime140.dll not found

Or in CI on a Windows runner:

name: Windows CI
on: [push]
jobs:
  test:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx playwright install
      - run: npx playwright test
      # Fails: "vcruntime140.dll not found"

The issue is not that the browser binary wasn't downloaded — it was — but that the Windows machine lacks the system-level Visual C++ runtime that the binary was compiled against.

The fix

Install the Microsoft Visual C++ Redistributable on your Windows machine or CI runner:

  1. Download the correct redistributable for your system:

  2. Install it:

# Download and install x64 redistributable
curl -L -o vc_redist.x64.exe https://aka.ms/vs/17/release/vc_redist.x64.exe
.\vc_redist.x64.exe /install /quiet /norestart

# Then reinstall Playwright browsers
npx playwright install
npx playwright test

For Windows CI (GitHub Actions):

name: Windows Tests
on: [push]
jobs:
  test:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Visual C++ Redistributable
        run: |
          Invoke-WebRequest -Uri "https://aka.ms/vs/17/release/vc_redist.x64.exe" -OutFile "vc_redist.x64.exe"
          .\vc_redist.x64.exe /install /quiet /norestart

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install

      - name: Run tests
        run: npx playwright test

For Windows CI (other runners like AppVeyor or GitLab CI Windows):

# PowerShell
$url = "https://aka.ms/vs/17/release/vc_redist.x64.exe"
$output = "$env:TEMP\vc_redist.x64.exe"
(New-Object System.Net.WebClient).DownloadFile($url, $output)
& $output /install /quiet /norestart

# Or using choco if available
choco install vcredist140 -y

Local machine fix:

Simply download and run the .exe from Microsoft's site, or use Chocolatey if you have it:

choco install vcredist140

After installing, either restart your shell/IDE or run npx playwright install again to verify the browsers can launch.

Why it works

Chromium (the browser engine Playwright uses) is compiled as a native Windows binary that dynamically links against specific versions of the Microsoft Visual C++ runtime libraries. These are distributed separately as a Windows redistributable package because:

  1. Separation of concerns: Microsoft ships the runtime separately so application developers don't have to bundle it with every app.
  2. Shared system resource: Many applications rely on the same redistributable — installing it once benefits all dependent applications.
  3. Security updates: Microsoft can patch the runtime without requiring app updates.

When headless_shell.exe starts on Windows, the OS loader tries to find and load vcruntime140.dll and msvcp140.dll from standard system directories. If they're missing, the process fails immediately. This is different from Linux systems, where npx playwright install --with-deps can install shared libraries via the package manager during the Playwright install step — Windows requires the VC++ redistributable to be installed at the OS level beforehand.

Tips

  • Check if it's already installed: Open Control Panel > Programs and Features and search for "Visual C++ Redistributable" — you may already have it, or you may have an older version that doesn't match the Chromium binary's requirements.
  • Multiple versions can coexist: You may need multiple VC++ redistributables (e.g., 2015 and 2022) if your machine runs applications compiled against different VC++ versions.
  • x64 vs. x86 matters: If you're running 32-bit Node or Playwright, install the x86 redistributable; for 64-bit (the default on modern Windows), install x64. Mixing them can cause confusing errors.
  • CI image hints: If your Windows CI runner is a base VM image, it may lack the redistributable by default — pin the VC++ install step to every workflow rather than assuming it's pre-installed.
  • Check architecture in CI: Use node -p process.arch to confirm your Node.js is x64 before installing Playwright browsers.
  • Different from "executable does not exist": This error is specifically about missing system DLLs after the binary is downloaded. If headless_shell.exe itself doesn't exist in the cache directory, see how to fix Playwright "Executable doesn't exist" after install.

Related Terms

How to fix Playwright "Executable doesn't exist" after install?

Playwright