What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
If Puppeteer says it “Could not find Chrome” in Docker, it usually cannot see the browser binary it expects. Install a compatible browser in the image, ensure it survives into the final image and is visible to the runtime user, or point Puppeteer to the real path of a browser installed by the image. If Puppeteer can find the binary but Chrome will not start, investigate missing Linux libraries as a separate issue.
What the error means
Puppeteer and its browser are related but distinct parts of a working setup. The puppeteer package normally downloads a compatible Chrome for Testing browser during installation. That download can be skipped—for example, if a package manager blocks install scripts—or the browser can be installed somewhere the running container cannot see.
The message Could not find Chrome (ver. ...) means Puppeteer could not resolve the browser it expects. It does not establish that Chrome is absent everywhere in the container: a system Chrome package might be present at a different path, or a browser cache might exist under a different user’s home directory. A subsequent process-spawn or shared-library error points to a different stage: Puppeteer found a binary but could not launch it.
Diagnose the container in order
-
Confirm the package and version
Check the dependency declared by your application and the version resolved in its lockfile.
puppeteernormally manages a compatible Chrome for Testing download.puppeteer-coredoes not download Chrome; your application must install or otherwise provide a browser and select it explicitly.PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, 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 minuteSpecial offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Check whether installation scripts were skipped
If the package manager suppresses dependency install scripts, Puppeteer’s automatic browser download may not run even though the Node package installed successfully. In the Docker build, from the application directory and after installing dependencies, add:
RUN npx puppeteer browsers installThat is Puppeteer’s documented manual browser-install command. Make sure the relevant Puppeteer dependency and configuration are available to the command. Alternatively, allow Puppeteer’s postinstall script under your package manager’s policy.
-
Check the cache and runtime user
By default, Puppeteer stores downloaded browsers in
~/.cache/puppeteer. The tilde refers to the home directory of the user running the command. If the image installs the browser as one user but starts the application as another, Puppeteer may look in a different cache.Compare the effective user and home directory at build and runtime. In a multi-stage Docker build, copy the browser cache into the final stage; a browser installed only in a discarded stage is unavailable to the running container. If you intentionally change the cache location using
PUPPETEER_CACHE_DIRor Puppeteer configuration, use the same setting when installing and when running the application.Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.Rank #2
-
Check that the browser made it into the final image
Inspect the final image—not just the build stage—for the expected browser and cache. Confirm the runtime user has permission to read and execute the browser files. A successful install command in an earlier layer or stage does not prove the final container can access its output.
Install Puppeteer’s managed browser in a Docker image
For a custom image that uses Puppeteer’s managed browser, install the package and then explicitly install the browser during the image build. A minimal pattern is:
FROM node:22-bookworm-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci
RUN npx puppeteer browsers install
COPY . .
CMD ["node", "index.js"]This pattern assumes your project’s lockfile and package manifests are copied before npm ci, and that puppeteer is in the installed dependencies. Keep the install command in the final image’s build path so the browser is present when the container runs. If you later change the runtime user or cache directory, ensure the browser remains accessible under that configuration.
For reproducible builds, pin your application dependencies and use a deliberate browser-install strategy. Do not rely on a mutable tag or an implicit cache location without checking what the final image contains.
Rank #3
Use a system Chrome or Chromium deliberately
If your image owns browser installation—for example, it installs Chromium through its Linux distribution—tell Puppeteer where the executable actually is inside the container. Do not assume Puppeteer will discover an arbitrary system installation.
const puppeteer = require('puppeteer');
async function main() {
const browser = await puppeteer.launch({
executablePath: '/path/to/browser',
headless: true,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
} finally {
await browser.close();
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});Replace /path/to/browser with the executable’s real path in your image. Puppeteer’s installation guidance also allows a channel when Chrome is installed in a standard location. The installed browser version still needs to work with the Puppeteer version your application uses; specifying a path fixes discovery, not compatibility.
With puppeteer-core, browser selection is your responsibility: provide executablePath or another supported browser-management approach rather than expecting an automatic Chrome download.
Choose between a managed browser, a system browser, and the official image
| Approach | Use it when | What you must verify |
|---|---|---|
| Puppeteer-managed browser | You want the browser version Puppeteer expects and its managed defaults. | Install scripts were not blocked, or you ran the explicit browser-install command; the cache is in the final image and visible to the runtime user. |
| System-managed Chrome or Chromium | Your image deliberately manages browser installation or uses a separately managed browser setup. | The executable path or standard channel is correct, the browser is compatible with Puppeteer, and required operating-system libraries are installed. |
| Official Puppeteer Docker image | You want an image that bundles Chrome for Testing, required dependencies, and a pre-installed Puppeteer version. | Choose a tag compatible with your application’s Puppeteer version; follow the image guide’s sandbox and init-process requirements. |
The official Puppeteer Docker guide says its image runs Chrome in sandbox mode and requires the SYS_ADMIN capability. It also recommends an init process, using --init or a custom entrypoint, to manage child processes. Consult the official Docker guide for the image’s current details and invocation guidance.
Free tools Windows power users keep installed
One-click scans. No signup required.
The guide says image tags follow Puppeteer versions. Pin a compatible tag and application version for reproducibility rather than assuming a mutable latest tag will always match. A user report about one 2025 rebuild of ghcr.io/puppeteer/puppeteer:latest describes a particular mismatch resolved by pinning that case to 24.31.0; that report is an anecdote, not evidence that latest is generally broken.
If Chrome exists but will not launch
Once the error changes from “could not find Chrome” to a process-spawn or launch failure, treat it as a new diagnosis. Linux browser binaries need shared libraries supplied by the image’s distribution. Puppeteer’s troubleshooting guidance suggests checking dependencies with:
ldd chrome | grep notRun the check against the browser executable in your image. Any reported missing libraries need to be installed for that image’s distribution. The exact package names depend on the distribution and version, so use its package manager and verify the final image again after installing dependencies.
Keep this separate from browser discovery: adding libraries will not fix a wrong executable path or missing browser cache, while installing Chrome will not supply every library a minimal base image may omit.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Best Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
Common failures and fixes
| Symptom | Likely cause | What to do |
|---|---|---|
Could not find Chrome (ver. ...) after installing puppeteer |
Browser download was skipped, or Puppeteer is looking in a cache that is absent. | Run npx puppeteer browsers install during the image build; confirm its output reaches the final image and matches the runtime cache and user. |
| Chrome is installed by the image, but Puppeteer still says it cannot find it | Puppeteer does not automatically discover that system installation, or the configured path is wrong. | Verify the path inside the container and pass it as executablePath; check the browser and Puppeteer versions for compatibility. |
| Works during build but not when the container runs | Build-time and runtime users, home directories, cache settings, or image stages differ. | Align the user and cache configuration, or make the browser available at the runtime path; copy the cache into the final stage. |
| Browser is found, then spawn or shared-library errors appear | Chrome starts unsuccessfully because required Linux dependencies may be missing. | Run ldd chrome | grep not against the in-container binary and install the missing libraries for the image’s distribution. |
| Official image behaves differently after a tag change | The selected image and application may no longer use compatible Puppeteer versions. | Pin a compatible image tag and application dependency; check the official image guide for current sandbox and init requirements. |
Or skip the browser setup
If your goal is to capture website screenshots rather than run a browser inside your own container, ScreenshotNeo offers a one-request screenshot API. It returns a PNG, JPEG, WebP, or PDF from a URL. Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents.
Example using cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up free for 1,000 screenshots a month—no card required.
Frequently Asked Questions
Does Puppeteer include Chrome when I install it?
The puppeteer package normally downloads a compatible Chrome for Testing browser, but install-script policies can prevent that download. puppeteer-core does not download Chrome.
Where does Puppeteer look for its downloaded browser?
By default, its browser cache is under ~/.cache/puppeteer for the effective user. The install-time and runtime user or cache settings must line up.
Can I use a different Chrome version?
You can manage another browser and set its actual in-container executablePath (or a standard channel where appropriate), but confirm it is compatible with your Puppeteer version.
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.
