How to Set Up a Headless Browser with Puppeteer

Install puppeteer, let it download its compatible Chrome for Testing browser, then launch it with puppeteer.launch(). Puppeteer runs headless by default, so you can automate a page without opening a visible desktop browser. Use puppeteer-core instead when you manage the browser binary yourself or connect to a remote browser.

Install Puppeteer and its browser

For a new Node.js project, install Puppeteer as a project dependency:

#	Preview	Product	Price
1		UI Testing with Puppeteer: Implement end-to-end testing and browser automation using JavaScript and...	$40.99	Buy on Amazon
2		Luckfox PicoKVM Lightweight IP KVM Remote Management Tool, Supports 1920 × 1080@60fps HDMI Video...	$78.90	Buy on Amazon

npm init -y
npm install puppeteer

The puppeteer package normally downloads a compatible Chrome for Testing browser during installation. Keeping the package and its downloaded browser paired avoids having to locate and configure a separate Chrome executable.

Some package-manager or organization policies block install scripts. If installation completes but no browser was downloaded, run Puppeteer’s documented browser installation command:

#1 Best Overall

UI Testing with Puppeteer: Implement end-to-end testing and browser automation using JavaScript and Node.js

$40.99

Buy on Amazon

npx puppeteer browsers install chrome

Use the Puppeteer installation guide for the exact package-manager behavior and command applicable to the version you install. Browser versions, package-manager policies, and platform dependencies can change, so check the documentation for your project’s pinned version.

When to use puppeteer-core

puppeteer-core does not download Chrome. Choose it when your deployment supplies its own browser, you need a particular managed executable, or you connect to a remote browser. In those cases, configure the browser location or supported channel explicitly; installing puppeteer-core alone does not provide a browser to launch.

Launch a headless browser and visit a page

Save this as index.js in the project where you installed Puppeteer:

const puppeteer = require('puppeteer');

async function main() {
  let browser;

  try {
    browser = await puppeteer.launch();
    const page = await browser.newPage();
    await page.goto('https://example.com');

    console.log(await page.title());
  } finally {
    if (browser) {
      await browser.close();
    }
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Run it with:

node index.js

The script starts the browser, opens a page, navigates to the URL, prints the page title, and closes the browser even if navigation or another operation fails. Closing the browser is important in repeated jobs and services: otherwise, browser processes can remain after the work is done.

Wait for the page state your task needs

page.goto() performs navigation, but a real automation task may need to wait for a particular element or for application-specific work to finish before reading or interacting with the page. Add the appropriate wait for the page state you depend on rather than assuming that every site renders all useful content at the same moment. Puppeteer’s API supports selector-based waits; choose a condition tied to the content your task actually needs.

Choose the right headless mode

Puppeteer currently launches regular Chrome headless mode by default. You can make that explicit with headless: true:

const browser = await puppeteer.launch({ headless: true });

For ordinary automation, leaving the default is usually the simplest choice. Use the alternatives based on what you need to inspect or which browser binary you want:

Older examples can differ: before Puppeteer v22, the old headless mode was the default. If output differs between an old script and a current one, check which mode and Puppeteer version each uses rather than assuming the word “headless” identifies the same Chrome implementation.

Configure browser downloads and executable paths

Puppeteer configuration can control the default browser, executable path, cache directory, and whether browser downloads are skipped. The documented default cache location is ~/.cache/puppeteer. Environment variables include:

These settings are most useful when you have a deliberate browser-management strategy, such as a preinstalled browser in a deployment image. If you skip downloads, make sure that a compatible browser is actually present and that Puppeteer points to it. A download-skipping setting does not make browser management unnecessary.

Run Puppeteer in Docker or Linux deployments

Chrome is a native browser process, not just a JavaScript dependency. A container therefore needs the browser binary, its Linux shared-library dependencies, suitable permissions, writable startup locations, and a way to reap child processes.

Use the published Puppeteer image when it fits

Puppeteer publishes a Docker image with Chrome for Testing, required dependencies, and a preinstalled Puppeteer version. Its documented image runs Chrome in sandbox mode and requires the SYS_ADMIN capability. The Docker guide also recommends an init process, such as Docker’s --init option or an equivalent custom entrypoint, to manage browser child processes.

Rank #2

Luckfox PicoKVM Lightweight IP KVM Remote Management Tool, Supports 1920 × 1080@60fps HDMI Video Input and HID Signal Output for Device Control (Basic Kit,1 piece)

• 【Remote Access from Any Browser】 Access and control your computers or servers directly from a web browser for easy remote troubleshooting and management.
• 【Clear 1080p HD Video & Low Latency】 Get a smooth, real-time view of the remote screen with 1080p HDMI capture and responsive keyboard/mouse control.
• 【WIKI】wiki.luckfox.com/Luckfox-PicoKVM/ If you have any questions, please click on “youyeetoo” to ask them or send an e-mail to am2#youyeetoo.com (#>>@).
• 【All-in-One Control Solution】 A single device handles video, keyboard, mouse, and power control (via GPIO), providing a complete remote management kit.
• 【Cost-Effective & Stable Hardware】Built on open-source technology for reliable performance, offering professional KVM-over-IP features at an accessible price.

$78.90

Buy on Amazon

Check the image documentation for the exact tag and invocation you use. Do not assume that an image tagged for one Puppeteer release will remain aligned with a different package version you install on top of it.

Build from another base image

If you use a different Linux base, use Puppeteer’s project Dockerfile as a reference for the dependencies Chrome needs. The precise shared libraries depend on the base distribution and image. A browser that works on a developer’s workstation can still exit immediately in a slim container if a required library or permission is missing.

Provide writable Chrome startup paths

Chrome writes profile, configuration, and cache files when it starts. In a read-only container or one with narrowly mounted writable paths, direct these locations to writable storage. Otherwise Chrome may fail before Puppeteer can connect, which can look like a launch or browser-crash problem rather than a filesystem-permission issue.

Keep the sandbox for untrusted pages

Chrome’s sandbox is a security boundary for web content. Do not treat --no-sandbox as a general-purpose Docker fix, especially when the browser may visit public or otherwise untrusted pages. Only consider disabling it for content you absolutely trust, and understand that doing so weakens browser isolation. Prefer configuring the container and its capabilities to support sandboxed execution.

Troubleshoot common launch and automation failures

For page-side console logging, add a listener after creating the page:

page.on('console', (message) => {
  console.log('PAGE:', message.text());
});

For browser-process diagnostics, pass dumpio: true to puppeteer.launch(). These are different streams of information: dumpio forwards browser-process output, while the page’s console event reports messages emitted by the page.

Plan for reliability, performance, and cost

• Close every browser: Put browser.close() in a finally block so failures do not leave browser processes behind.
• Manage browser versions intentionally: The puppeteer package’s compatible browser download is convenient for local development and CI. With puppeteer-core, take responsibility for installing and locating the browser, including keeping it compatible with your automation.
• Account for container overhead: Browser binaries, Linux dependencies, writable profiles, and process management all affect deployment setup. A successful Node package installation alone does not prove Chrome can run in the target container.
• Choose shell mode only for a reason: Puppeteer’s guide says chrome-headless-shell can be more performant for automation that does not need the full Chrome feature set, but it does not completely match regular Chrome. Validate that its differences are acceptable for your task.
• Estimate cost from the environment you operate: Puppeteer itself is the automation library; no universal hosting price or performance benchmark is published. Budget for your own compute, storage, and any browser infrastructure rather than relying on an unsupported per-capture cost estimate.

Or skip the browser setup

If your task is simply to get a website screenshot, ScreenshotNeo can return one image or a PDF with a single GET request. Its service accepts cookie/consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response reports the page verdict and billing status in headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.

Example using cURL (see the ScreenshotNeo documentation for options):

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Plans include 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000. Sign up for the free plan.

Frequently Asked Questions

Does Puppeteer require a visible Chrome window?

No. Its default launch is headless; set headless: false when you need a visible window for debugging.

Can Puppeteer connect to a browser it did not install?

Yes. Use puppeteer-core with a separately managed browser and configure the executable path or supported channel, or connect to a remote browser.

Does headless: 'shell' behave exactly like regular Chrome?

No. It selects the separate chrome-headless-shell binary, which Puppeteer’s guide says does not completely match regular Chrome.

Quick Recap

Bestseller No. 1

UI Testing with Puppeteer: Implement end-to-end testing and browser automation using JavaScript and Node.js

$40.99

Bestseller No. 2

Luckfox PicoKVM Lightweight IP KVM Remote Management Tool, Supports 1920 × 1080@60fps HDMI Video Input and HID Signal Output for Device Control (Basic Kit,1 piece)

$78.90

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.