How to install browser dependencies for Playwright screenshots on Ubuntu
Install Playwright browsers and their Ubuntu system dependencies, choose Chromium or all browsers, and troubleshoot common launch failures.
To install Playwright’s browser binaries and the Ubuntu system packages they need, run npx playwright install --with-deps chromium from your project directory. This installs Chromium plus its Linux dependencies. To install dependencies for all default Playwright browsers instead, run npx playwright install --with-deps.
Playwright-managed browser binaries and operating-system packages are separate requirements. The --with-deps option installs both. Use the Playwright CLI associated with your project, because each Playwright release expects specific browser revisions. See the official browser installation guide and CLI reference.
1. Install Playwright and its browser dependencies
For an npm project with a lockfile, install its pinned packages first, then install Chromium and its dependencies:
npm ci
npx playwright install --with-deps chromiumIf you need every browser Playwright installs by default, omit the browser name:
npx playwright install --with-depsRun the command in the project directory so npx resolves the project’s installed Playwright version. On Linux, installing system packages may require apt privileges; if the command cannot acquire them, run it in an environment where your account has the required package-management permissions or ask the machine administrator to install the dependencies.
Choose what to install
| Need | Command | What it installs |
|---|---|---|
| Chromium and its Ubuntu packages | npx playwright install --with-deps chromium |
One browser binary and its system dependencies |
| All default browsers and their packages | npx playwright install --with-deps |
Default browser binaries and their system dependencies |
| Only Chromium’s system packages | npx playwright install-deps chromium |
Operating-system dependencies, without installing the browser binary |
| Only Chromium’s browser binary | npx playwright install chromium |
Browser binary, without installing missing system packages |
Use the combined command when setting up a fresh Ubuntu machine. The separate commands are useful when one half is already present, such as a preinstalled browser binary but missing shared libraries.
2. Create and run a screenshot script
Once Chromium is installed, this minimal Node.js example opens a page and saves a full-page PNG. Save it as screenshot.mjs in the project directory:
import { chromium } from 'playwright';
const browser = await chromium.launch({ headless: true });
try {
const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
await page.goto('https://example.com', { waitUntil: 'networkidle', timeout: 30_000 });
await page.screenshot({ path: 'screenshot.png', fullPage: true });
} finally {
await browser.close();
}Install the package if it is not already in your project with npm install playwright, then run node screenshot.mjs. For pages with ongoing network activity, networkidle may never occur; use domcontentloaded or load and wait for a specific selector before capturing.
3. Check Ubuntu and Playwright compatibility
Playwright’s current installation requirements list Ubuntu 22.04, 24.04, and 26.04 on x86-64 and arm64. Platform support can change, so check the installation requirements for the version in your project, especially when using a different Ubuntu release or architecture.
Playwright pairs each release with particular browser revisions. After upgrading the Playwright package, rerun browser installation so the binaries match:
npm ci
npx playwright install chromiumFor a new machine where system packages may also be missing, use npx playwright install --with-deps chromium again.
4. Set up screenshots in CI
In CI, install JavaScript dependencies from the lockfile, install the browser and Linux packages, then run the screenshot script or tests. For npm, the sequence is:
npm ci
npx playwright install --with-deps chromium
node screenshot.mjsUse npx playwright install --with-deps if the job needs all default browsers. Playwright’s CI guide recommends installing browser dependencies in the job; Linux operating-system dependencies are not cacheable. If you cache browser binaries, key that cache to the Playwright version so a package upgrade does not reuse an incompatible browser revision.
To inspect what the CLI would install without changing the machine, use its dry-run option:
npx playwright install --dry-run --with-deps chromiumOn Linux, the documented dry run simulates installation with apt-get and exits with a nonzero status if required packages are missing. It is a diagnostic, not a substitute for actually installing those packages.
5. Troubleshoot browser installation and launch errors
| Symptom | Likely cause | Fix |
|---|---|---|
| Browser executable does not exist | The project package is installed, but its browser binary has not been downloaded, or the binary is from another Playwright version. | From the project directory, run npx playwright install chromium; on a fresh Linux system use npx playwright install --with-deps chromium. |
| Launch fails with a missing shared library or shared object | Chromium exists, but an Ubuntu system dependency is missing. | Run npx playwright install-deps chromium, or use npx playwright install --with-deps chromium to install both browser and dependencies. |
| Installation fails while using apt | The account may lack package-management privileges, or the environment’s package policy or network access may prevent apt from installing packages. | Check apt access and the environment’s proxy or package mirror configuration. In managed CI or containers, install dependencies through the environment’s approved package setup, then install the Playwright browser. |
| Browser download fails or stalls | A proxy, firewall, or restricted network may block the browser download. | Check Playwright’s browser download and proxy guidance, then retry from an environment that can reach the required download host. |
| Browser launch fails after a Playwright upgrade | The installed browser revision may no longer match the package version. | Run the install command through the project’s current CLI again. In CI, ensure the browser cache key includes the Playwright version. |
| Screenshot script times out waiting for navigation | The page may keep network requests open, making networkidle unsuitable. |
Use domcontentloaded or load, then wait for a page-specific selector or a bounded delay before capture. |
| Dry run reports missing packages | The machine does not have all system dependencies required by the selected browser. | Run the corresponding installation command with --with-deps in an environment with the necessary apt permissions. |
When diagnosing a failure, first confirm which Playwright package the project resolves, then install its browser, then address system libraries. These are distinct layers, and fixing only one may leave launch failures unresolved.
6. Performance, reliability, and cost considerations
- Install only what the job uses. If screenshots run in Chromium, specifying
chromiumavoids installing other browser binaries the job does not need. - Keep package and browser versions aligned. Install browsers after dependency installation, and refresh them when upgrading Playwright. Version-keyed browser caches reduce mismatches.
- Separate setup from captures. Browser and OS dependency installation is machine setup; do it when preparing the runtime or CI image, rather than as part of every individual screenshot operation where your environment allows a prepared image.
- Make capture waits bounded. Set navigation timeouts and wait on a meaningful selector when network-idle behavior is unreliable. Always close the browser in a
finallyblock so failures do not leave browser processes running. - Account for environment costs. Playwright itself is open source, but running screenshots still consumes machine time, storage, and network bandwidth. The dossier does not provide a benchmark or a universal cost figure; actual resource use depends on the page, browser, and runtime.
Or skip the browser setup
If you need a screenshot without installing Chromium and Linux packages, ScreenshotNeo provides a website screenshot API and MCP server. One GET request captures a URL; see the API documentation for parameters and formats.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, with the outcome shown in X-Page-Verdict and X-Billed response headers. Its MCP server gives AI agents tools for screenshots, page information, and PDFs. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up free for 1,000 screenshots a month, with no card required.
Frequently asked questions
Do I need to install all three Playwright browsers to take screenshots?
No. Install the browser your script uses, such as Chromium, with npx playwright install --with-deps chromium.
Does install-deps download the browser?
No. It installs operating-system dependencies. Use playwright install chromium for the browser binary, or combine both steps with playwright install --with-deps chromium.
Can I use this on an Ubuntu release not listed in the requirements?
Check the requirements for your Playwright version. The documented list can change, and a different Ubuntu release may require environment-specific dependency handling.
Will a screenshot script work in a container?
It can, provided the container has the system packages and browser binary required by the Playwright version in use. Install them in the image or runtime setup, following the official browser and CI guidance.
