Install Playwright Browser Dependencies on Ubuntu

This guide walks you through installing the system libraries that Playwright needs to launch Chromium, Firefox, or WebKit on Ubuntu, specifically so you can take screenshots without errors. You’ll start by installing the Playwright package, then use its built-in command to fetch browsers and their OS-level dependencies. No prior Linux expertise is required, just terminal access and sudo privileges.

What You’ll Need

• An Ubuntu machine (20.04, 22.04, or 24.04 LTS recommended) with internet access.
• A user account with sudo privileges to install system packages.
• Node.js and npm (or Python/pip) already installed, since Playwright is a library for those runtimes.

Step-by-Step

1. Open a terminal. Press Ctrl+Alt+T or search for “Terminal” in your applications menu.
2. Update your package list. Run sudo apt update to refresh the repository indexes. This ensures you get the latest dependency versions.
3. Install Playwright. In your project directory, run one of the following based on your runtime:
   For Node.js: npm init -y then npm install playwright
   For Python: pip install playwright (or pip3 install playwright if needed).
4. Install the browsers. Run npx playwright install (Node.js) or python -m playwright install (Python). This downloads the browser binaries to your user cache (~/.cache/ms-playwright).
5. Install system dependencies. Run npx playwright install-deps (Node.js) or python -m playwright install-deps (Python). This uses sudo to install all required shared libraries and fonts. You may be prompted for your password.
6. Verify the installation. Create a simple test script that launches a browser and takes a screenshot. For Node.js, save this as test.js:

   const { chromium } = require('playwright');
   (async () => {
     const browser = await chromium.launch();
     const page = await browser.newPage();
     await page.goto('https://example.com');
     await page.screenshot({ path: 'example.png' });
     await browser.close();
   })();

   Then run node test.js. For Python, save this as test.py:

   from playwright.sync_api import sync_playwright
   with sync_playwright() as p:
       browser = p.chromium.launch()
       page = browser.new_page()
       page.goto('https://example.com')
       page.screenshot(path='example.png')
       browser.close()

   Then run python test.py.

7. Check the output. If no errors appear and an example.png file is created, your setup is complete. If you get a “missing dependencies” error, proceed to the Troubleshooting section.

Common Mistakes

• Running install-deps without sudo. The command needs root privileges to install system packages. If you see “permission denied”, run it with sudo explicitly or let the command prompt you.
• Forgetting to update apt first. Skipping sudo apt update can lead to installing outdated or missing packages.
• Using the wrong package manager command. Mixing up npm and pip commands can cause confusion. Stick to the one that matches your runtime.
• Ignoring the browser install step. Running install-deps alone doesn’t download the browsers. You must run install first (or both in sequence).
• Assuming it works on all Ubuntu versions. Older versions like 18.04 may need manual dependency installation. Check the official Playwright docs if you’re on an older release.

Tips

• Use npx playwright install --with-deps (Node.js) to install both browsers and dependencies in one command. For Python, it’s python -m playwright install --with-deps.
• If you only need Chromium, use npx playwright install chromium to save time and disk space.
• For headless servers, you can skip the X server by using chromium.launch({ headless: true }) (which is the default) – no GUI needed.
• Set a custom cache directory with PLAYWRIGHT_BROWSERS_PATH if you want to store browsers outside the default location (useful for CI/CD).
• Keep Playwright updated regularly with npm update playwright or pip install --upgrade playwright to get the latest browser versions and fixes.

Troubleshooting

• “Missing dependencies” error when launching. This usually means install-deps didn’t run or failed. Re-run it with sudo and ensure your apt sources are working. If it still fails, manually install the missing libraries listed in the error message via sudo apt install <package-name>.
• Error: “Failed to launch browser: Executable doesn’t exist.” The browser binaries weren’t downloaded. Run npx playwright install (or the Python equivalent) again. Check that the cache directory is writable.
• Error: “/usr/bin/ld: cannot find -lX11” or similar. This is a linker issue, often from missing development packages. Run sudo apt install build-essential libx11-dev libxext-dev libxrender-dev libxtst-dev libxi-dev.
• Sandbox errors on some systems. If you see “Running as root without –no-sandbox is not supported”, launch the browser with chromium.launch({ args: ['--no-sandbox'] }) (only in trusted environments, as it reduces security).
• Font issues in screenshots. If text appears as boxes, install fonts with sudo apt install fonts-liberation fonts-noto-color-emoji.
• Network timeouts during install. If downloads fail, retry after a moment. You can also set PLAYWRIGHT_DOWNLOAD_HOST to a mirror if you’re in a region with slow access.

Frequently Asked Questions

Do I need to run install-deps every time I update Playwright?

Not necessarily. System dependencies rarely change, but it’s safe to run it again after major updates. The command is idempotent, so it won’t hurt.

Can I use Playwright without installing browsers?

No, Playwright requires the browser binaries. You can install them separately, but the easiest way is via playwright install.

Will this work on Ubuntu Server without a GUI?

Yes, Playwright runs headless by default, so no GUI is needed. The dependencies are the same.

How do I uninstall Playwright and its dependencies?

Remove the npm package with npm uninstall playwright or the pip package with pip uninstall playwright. To remove browsers, delete the ~/.cache/ms-playwright folder. System dependencies can be left; they won’t harm anything.

Can I use Playwright with a different browser like Brave or Edge?

Playwright supports Chromium, Firefox, and WebKit. For other Chromium-based browsers, you can use channel: 'chrome' or channel: 'msedge' if those browsers are installed, but the system dependencies are the same.

Why do I get a “libnss3” error even after install-deps?

This can happen on older Ubuntu versions or if the package cache is stale. Run sudo apt update and then sudo apt install libnss3 explicitly. If it persists, check that you’re not mixing 32-bit and 64-bit libraries.

Related

• PS4/PS5 Controller on Touchscreen: How-To
• Find Where Facebook Is Logged In & Secure It
• iOS 16: How to Use the Apple TV Remote App