Playwright Browser Install Guide for Local Setup, CI, and Docker

A surprising amount of Playwright friction comes from environment setup rather than test code. Searches for playwright install browsers usually happen after a missing binary, mismatched version, or broken CI runner blocks the whole suite.

Key Takeaways

Use Playwright-managed browser installs instead of ad hoc system browsers when you want deterministic behavior.
Cache browsers in CI when possible, especially for large suites.
Use --with-deps where the environment needs system packages as well as browser binaries.
Document the install path in the team workflow so local and CI setups stay aligned.

Why This Topic Matters in 2026

Browser installation affects developer onboarding, CI speed, Docker images, and cross-browser coverage.
Version mismatches between the Playwright package and installed browsers are a common source of confusion.
Clear install workflows reduce “works on my machine” failures and make AI-generated setup changes easier to trust.

Practical Workflow

Step 1: Install browsers intentionally, not implicitly

Make browser installation part of setup scripts or CI steps instead of assuming it happened somewhere else.

npx playwright install
npx playwright install chromium
npx playwright install --with-deps

Step 2: Treat CI as a separate install environment

CI runners usually need browser caching and a repeatable dependency step. The best local setup is not automatically the best CI setup.

- name: Install browsers
  run: npx playwright install --with-deps

- name: Run tests
  run: npx playwright test

Step 3: Use the CLI skill when you need quick browser validation outside the full suite

If a new machine or container is misconfigured, a quick playwright-cli open session is often enough to prove whether the browser layer is healthy.

playwright-cli open https://playwright.dev
playwright-cli snapshot
playwright-cli close

Where the Playwright CLI Skill Fits

This is exactly where Playwright CLI Browser Automation adds value. The skill gives your agent stable guidance for snapshots, uploads, downloads, tab handling, tracing, screenshots, PDFs, and fast browser investigation without forcing you to reinvent the command flow every time.

If you are building out a broader QA workflow, keep the skill installed and pair it with the wider QASkills.sh skills directory catalog so your agent can switch between browser automation, API testing, CI, accessibility, and reporting with less context loss.

Common Mistakes to Avoid

Relying on a globally installed browser and assuming it matches the package version in the repo.
Skipping browser cache configuration in CI and paying the full install cost on every run.
Using a Docker image without validating the system dependencies Playwright still needs.
Treating browser installation errors as test failures instead of environment failures.

Conclusion

Reliable Playwright setup starts before the first test executes. Make browser installation explicit, align local and CI workflows, and use quick browser-level checks when you need to isolate environment problems fast.