Playwright Downloads: Verify Across Platforms

This guide explains how to handle Playwright’s browser downloads and verify their integrity across Windows, macOS, and Linux. You’ll learn where the browsers are stored, how to confirm they are correctly installed, and how to troubleshoot common issues that arise when downloads fail or become corrupted.

What You’ll Need

• Node.js (version 18 or later) installed on your system
• A terminal or command prompt with internet access
• Playwright installed via npm (or your preferred package manager)
• Administrator or user-level permissions to write to the cache directory

Step-by-Step

1. Install Playwright and its browsers. In your project directory, run npm init -y followed by npm install @playwright/test. Then execute npx playwright install. This downloads the default browser set (Chromium, Firefox, WebKit) to a system-specific cache folder.
2. Identify the browser cache location for your OS. The cache paths are:
   – Windows: %USERPROFILE%\AppData\Local\ms-playwright
   – macOS: ~/Library/Caches/ms-playwright
   – Linux: ~/.cache/ms-playwright
   You can also run npx playwright install --dry-run to see the exact paths without downloading.
3. Check that the expected folders exist. Navigate to the cache directory and list its contents. You should see folders named like chromium-XXXX, firefox-XXXX, and webkit-XXXX, where XXXX is a revision number. If any are missing, the download was incomplete.
4. Verify the integrity of each browser. Run npx playwright install --verify. This command checks that each browser’s executable is present and that the expected files are in place. It does not re-download unless something is broken.
5. Test a simple launch to confirm functionality. Create a minimal script (e.g., test.js) with the following content:
   const { chromium } = require('playwright');
(async () => { const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto('https://example.com'); console.log('Title:', await page.title()); await browser.close(); })();
   Run it with node test.js. If it prints the page title, the download is functional.
6. If using CI or Docker, ensure dependencies are installed. On Linux, run npx playwright install-deps to install system libraries required by the browsers. This is often the cause of launch failures even when the download itself appears correct.
7. Set a custom cache directory if needed. You can override the default location by setting the PLAYWRIGHT_BROWSERS_PATH environment variable to a path of your choice. This is useful in CI environments where the home directory is ephemeral.

Common Mistakes

• Running install without network access: The download requires a stable internet connection. A proxy or firewall may block it; use HTTPS_PROXY environment variables if necessary.
• Mixing versions: If you update Playwright without re-running npx playwright install, the browsers may not match the library version. Always install after upgrading.
• Ignoring Linux dependencies: On Linux, even if the browser files are present, missing system libraries (like libnss3 or libatk) will cause launch errors. Run install-deps to fix this.
• Assuming the cache is in the project folder: The browsers are stored globally in the user cache, not in node_modules. Don’t look for them there.
• Forgetting to reinstall after clearing cache: If you delete the cache manually, you must run npx playwright install again.

Tips

• Use npx playwright install --with-deps on Linux to install browsers and system dependencies in one step.
• In CI, cache the ms-playwright folder to speed up builds. For GitHub Actions, use the actions/cache action with the appropriate path for your OS.
• If you only need one browser, install it individually, e.g., npx playwright install chromium to save disk space.
• Check the Playwright version with npx playwright --version and compare it with the browsers’ revision numbers in the cache to ensure they match.
• Set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 during npm install if you plan to manage browsers separately (e.g., in a Docker image).

Troubleshooting

If the download fails or browsers don’t work, try these steps in order:

1. Re-run the install with verbose output: Use npx playwright install --debug to see detailed logs. This often reveals network timeouts or forbidden URLs.
2. Clear the cache and reinstall: Delete the ms-playwright folder (or the specific browser folder) and run npx playwright install again. This fixes corrupted downloads.
3. Check disk space: Browsers take about 400 MB each. Ensure you have at least 1 GB free.
4. Verify environment variables: If you have PLAYWRIGHT_BROWSERS_PATH set, make sure it points to a writable location. Also check that HOME or USERPROFILE is correct.
5. Test the browser executable directly: Navigate to the cache folder and run the executable (e.g., chrome-win/chrome.exe on Windows) to see if it launches standalone. If it doesn’t, the download is incomplete.
6. For Linux, run ldd on the executable: This shows missing shared libraries. Install them via your package manager or use npx playwright install-deps.
7. If all else fails, reinstall Playwright: Uninstall with npm uninstall @playwright/test, delete node_modules and package-lock.json, then reinstall and run npx playwright install.

Frequently Asked Questions

Q: How do I know which browser version is installed?

Run npx playwright install --dry-run to see the expected revision numbers. Then check the folder names in the cache directory—they include the revision number.

Q: Can I use system-installed browsers instead of Playwright’s downloads?

Yes, you can use the channel option in launch, e.g., chromium.launch({ channel: 'chrome' }), but this is not recommended for CI because it’s less reproducible.

Q: Why does Playwright download browsers again after I update the library?

Each Playwright version pins specific browser revisions. Updating the library requires matching browser builds, so you must re-run npx playwright install.

Q: Is it safe to delete the cache folder?

Yes, but you’ll need to re-download the browsers next time you run tests. It’s a common first step in troubleshooting corrupted installations.

Q: How long does the download take?

It depends on your internet speed. Typically 1-3 minutes for all three browsers, but can be longer on slow connections. Use --only-shell to download a minimal browser for testing quickly.

Q: Can I install browsers for all platforms from one machine?

No, Playwright downloads the binaries for the current OS only. To test on other platforms, use CI services or virtual machines.

Related

• Insightful Strike in Where Winds Meet: Location & Best Uses
• Epic Systems Pauses Product Development for Cybersecurity
• Do You Need Milwaukee or Snap-On Tools for Car Work?