Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsSome links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To request a visible Chrome window, launch Puppeteer with headless: false. If that still fails, the cause is usually not the setting itself: headed Chrome also needs an accessible graphical display, compatible Linux libraries, and a working sandbox. Match the error and environment to the right fix rather than applying one flag or package command to every Ubuntu setup.
Start with the headed-mode setting
Puppeteer launches headless by default. Set headless: false in the options passed to puppeteer.launch() to request a headed Chrome session. The current Puppeteer headless-mode guide documents this setting: Puppeteer headless modes.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({
headless: false,
});
const page = await browser.newPage();
await page.goto('https://example.com');
// Keep the process alive while you inspect the visible browser.
// Close it when you are finished:
// await browser.close();
})();This only requests headed Chrome. It does not create a desktop session or display server. On a local Ubuntu desktop, the session normally provides a display. On a server, container, or CI worker without one, Chrome has nowhere to draw its window, so address display access separately.
Recommended Free Tools
Use the error and environment to choose a fix
| Observed symptom or setup | First area to check | Next step |
|---|---|---|
No usable sandbox! |
Chrome sandbox configuration; on some Ubuntu 23.10+ systems, AppArmor and user namespaces | Check the sandbox guidance and the specific Ubuntu AppArmor scenario below before considering any security-reducing workaround. |
| A missing shared object or library load error | Chrome’s Linux runtime dependencies | Run ldd against the Chrome executable and install the missing dependencies for that browser. |
| Works on a desktop, fails on a server or in CI | No display accessible to headed Chrome | Provide a graphical session or, in CI, start Xvfb and ensure the Puppeteer process can access its display. |
| Chrome exits with little or no useful output | Hidden browser-process logs | Set dumpio: true and inspect the output from Chrome. |
For an ambiguous launch failure, collect the exact error text, Puppeteer and Chrome versions, Ubuntu release, whether the process runs in a container or CI, and whether a display is available. Those details help distinguish a display problem from a dependency or sandbox failure.
#1 Best Overall
Provide a display for headed Chrome
Headed Chrome requires a graphical display that the process can use. A local desktop session may already provide one; a headless Ubuntu server or CI runner generally does not. In its troubleshooting guide, Puppeteer specifically recommends starting the Xvfb service to run non-headless Chrome in CI. See Puppeteer troubleshooting.
- Determine where the script runs. Check whether it runs inside your logged-in desktop session, a container, a remote VM, or a CI job. A successful launch on your desktop does not establish that the other environment has a display.
- For CI without a physical display, start Xvfb. Make sure the service is running before launching Puppeteer.
- Confirm display access for the Node process. Starting a display service alone is not enough if the browser process cannot connect to it. Check the display configuration and permissions used by that process.
- Retry the minimal launch. Use
headless: falsewith a simple page first, then restore your application logic.
If the browser launches but no window is visible, verify that the display belongs to the session you are watching. A virtual display such as Xvfb is useful for software that needs a display in CI; it is not the same as opening a window on your physical desktop.
Find missing Ubuntu or Debian libraries
Chrome depends on system libraries for graphics, windowing, fonts, and other runtime functions. Puppeteer’s troubleshooting guide lists common Debian and Ubuntu dependencies, including GTK, NSS, GBM, X11, and font-related libraries. The exact requirements can vary with the Chrome build, so inspect the executable actually used by Puppeteer rather than relying on an old package list.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteRank #2
- Locate the Chrome executable. Use the path for the browser installation your script is launching; do not assume a system-installed Chrome and Puppeteer’s downloaded Chrome for Testing are the same binary.
- Check its dynamic dependencies:
ldd /path/to/chrome | grep notIf the command reports a library as not found, that is a dependency to investigate. Replace
/path/to/chromewith the real executable path. - Install dependencies for your actual Ubuntu release and browser. Follow the current Puppeteer and Chrome requirements rather than copying package names from an unrelated or outdated guide.
Puppeteer’s browser CLI documents this command for Chrome on Ubuntu or Debian:
npx puppeteer browsers install chrome --install-depsThe command uses apt-get and requires system-level privileges. Run it only where you have the necessary permissions, and check the current CLI documentation at Puppeteer browser management if the command or your setup differs. The Puppeteer troubleshooting guide also maintains dependency guidance: Linux troubleshooting.
Investigate sandbox errors without disabling protection by default
Chrome’s sandbox is a security boundary that isolates web content. Puppeteer says that the recommended way to run Chrome is with sandboxes and strongly discourages --no-sandbox. Do not treat that flag as a general fix for headed mode: it does not create a display or install missing libraries, and it reduces browser isolation.
There is a documented Ubuntu-specific case to check when the error says No usable sandbox!. On Ubuntu 23.10 and newer, an AppArmor profile for Chrome Stable at /opt/google/chrome/chrome may prevent Chrome for Testing downloaded by Puppeteer from using user namespaces. The browser can then report that no usable sandbox is available. This is a possible cause in that scenario, not the explanation for every sandbox error. Review Puppeteer’s troubleshooting notes and the linked Chromium AppArmor user-namespace guidance, then choose a remedy that fits your host’s security policy.
Before changing sandbox settings, establish which Chrome binary is running, which Ubuntu release is involved, and what the browser logs report. If you are considering --no-sandbox, reserve it for exceptional cases where the content and environment are fully trusted and the security trade-off is understood; it is not the recommended routine configuration.
Expose Chrome’s logs when the cause is unclear
By default, browser-process output may not be visible in the place where you are diagnosing the failure. Set Puppeteer’s dumpio: true option to forward Chrome’s standard output and error streams to the Node process:
const browser = await puppeteer.launch({
headless: false,
dumpio: true,
});Run the script again and inspect the output alongside the exact launch error. A missing library, denied sandbox operation, and unavailable display require different fixes; do not infer the cause from the fact that all three can prevent a window from opening. Puppeteer documents dumpio in its launch options: LaunchOptions API.
Check version, architecture, and container assumptions
Puppeteer’s current system-requirements page lists Debian and Ubuntu on x64 and arm64 for Chrome for Testing and states a Node.js requirement of 22.12 or newer. Requirements can change, so compare your environment with the live Puppeteer system requirements rather than assuming an older Node or Ubuntu combination is supported.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Since Puppeteer 20.0.0, the supported-browsers documentation says Puppeteer downloads and works with Chrome for Testing. Its headless and headful modes use the same browser code path, but a headed launch still depends on the host’s display, libraries, and sandbox setup. See supported browsers.
Best Value
- Used Book in Good Condition
For containers, Puppeteer’s Docker guide describes an image containing Chrome for Testing and its required dependencies. Its documented sandboxed container run requires the SYS_ADMIN capability and recommends an init process to manage browser processes. Those container details do not automatically provide a visible desktop window: the container’s permissions and access to the intended display must still match your workflow. Consult the Puppeteer Docker guide before adapting its setup.
Or skip the browser setup
If your goal is to save a web page as an image or PDF rather than operate a visible browser window, ScreenshotNeo offers a screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF; its clean-shot options accept consent banners and remove more than 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, with the outcome reported in response headers. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf.
Here is a one-call cURL example, using the documented API endpoint and parameter names:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpReplace YOUR_API_KEY with your key and change the target URL as needed. See the ScreenshotNeo API documentation for the request options and response details. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for the free plan.
Quick FAQ
Does headless: false make a window appear on a remote server?
No. It requests headed Chrome, but the process still needs access to a display. In CI, Puppeteer recommends starting Xvfb for non-headless Chrome.
Should I reinstall Puppeteer whenever headed mode fails?
Not automatically. First identify whether the failure is caused by display access, missing libraries, sandbox policy, or hidden Chrome output. Reinstalling does not address a missing display or a host security policy.
Can I run headed Chrome inside a container?
It depends on the container’s browser dependencies, permissions, and display access. Puppeteer’s Docker instructions cover a documented sandboxed setup, but a visible window also requires a display the containerized process can use.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Quick Recap
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.
