How to Uninstall Browsers Installed by Puppeteer
Find Puppeteer’s browser cache, inspect its downloads, and remove all or one browser build safely. Includes cache configuration, trimCache, and fixes for common cleanup errors.
Direct answer: To remove all browser binaries managed in Puppeteer’s cache, inspect them with npx @puppeteer/browsers list, then run npx @puppeteer/browsers clear. To remove one browser build, use the @puppeteer/browsers API’s uninstall(options) function with that browser, its build ID, and the cache directory. Puppeteer’s default cache is ~/.cache/puppeteer, but configuration can change it.
This guide removes downloaded browser binaries. It does not uninstall the puppeteer npm package, and the available documentation does not promise that clearing the browser cache also removes browser profiles or other separate data.
1. Check what Puppeteer installed and where
The standard cache location has been ~/.cache/puppeteer since Puppeteer v19.0.0. A project’s Puppeteer configuration or the PUPPETEER_CACHE_DIR environment variable can redirect it. Check those settings first so you inspect and clean the cache that the project actually uses. See the Puppeteer configuration guide and installation guide.
# Print the cache override if one is set
printf 'PUPPETEER_CACHE_DIR=%s\n' "$PUPPETEER_CACHE_DIR"
# Inspect browser downloads in the cache used by the browsers CLI
npx @puppeteer/browsers listIf you use a project configuration file, inspect its cacheDirectory setting as well. The list command is for inspection; it does not delete anything. If you have multiple projects or users sharing one cache directory, note that before choosing a cleanup command.
2. Clear every browser download in the managed cache
Use the browsers CLI’s clear command when you want to remove all installed browser downloads managed in the cache:
npx @puppeteer/browsers clearThis is a broad cleanup. Any project relying on a browser binary in that cache will need it available again before it can launch. The next install or launch may download the configured browser build again. Puppeteer documents the list and clear commands in its browser management guide.
3. Remove only one browser build
For a selective removal, use the uninstall(options) API from @puppeteer/browsers. Provide the browser identifier, exact build ID, and cache directory; a platform can also be supplied where appropriate. The API reference is authoritative for the version installed in your project: uninstall(options) API.
The documented material specifies these required options but does not give a universal, ready-to-run invocation that is safe across package versions. Do not guess a CLI command or build ID. First find the exact browser and build in the listing, then follow the API reference for your installed version’s import and invocation syntax. Conceptually, the call needs:
uninstall({
browser: /* browser identifier from the installed package API */,
buildId: /* exact build ID shown for the cached browser */,
cacheDir: /* exact configured cache directory */
// platform: /* optional platform, if required by your setup */
})This is an option map, not a standalone runnable program: the browser identifier’s import and accepted values depend on the installed @puppeteer/browsers version. Consult that version’s API reference rather than copying a guessed enum or path.
4. Prune old builds with trimCache
puppeteer.trimCache() is a narrower maintenance operation: it removes non-current Firefox and Chrome binaries according to the current Puppeteer configuration. It is not equivalent to clearing the whole cache. It also does not check whether another Puppeteer version sharing the same cache directory still needs one of those binaries. Review shared-cache use before pruning. See the trimCache() API.
5. Know what you are uninstalling
- Browser cache: Downloaded browser binaries managed by Puppeteer. Use the list, clear, targeted uninstall, or trim operation above.
- Puppeteer package: The JavaScript dependency in your project. Removing it is a package-manager operation and is separate from clearing downloaded browsers.
- Browser profiles or other data: The cleanup documentation does not establish that clearing the browser cache removes these. Treat profile cleanup as a separate task and inspect any custom profile location you configured.
The puppeteer package downloads a compatible Chrome for Testing build during installation. puppeteer-core does not download Chrome when installed, so a project using only puppeteer-core may not have a Puppeteer-downloaded browser to remove. Refer to the installation guide.
6. Troubleshoot common cleanup problems
| Symptom | Likely cause | What to do |
|---|---|---|
list shows no browsers |
The command is looking at a different cache than the one used by the project, or the project uses puppeteer-core. |
Check PUPPETEER_CACHE_DIR and the project’s cacheDirectory setting. Confirm which Puppeteer package is installed. |
| The browser still appears after cleanup | You may have listed a different cache, or another project may have downloaded a browser again. | Run list in the same environment and inspect the configured cache directory. Check whether a later install or launch fetched a build. |
| A project can no longer launch Chrome | Its required downloaded build was cleared or pruned. | Run the project’s normal install or browser setup so its configured compatible build is present again. |
| Targeted uninstall fails to find a build | The build ID or cache directory does not match the installed browser entry. | List cached browsers, copy the exact build ID, and supply the exact cache directory. Check the installed API version’s option names. |
| Permission denied while clearing | The current user cannot modify the cache directory, possibly because it was created by another user or process. | Check directory ownership and permissions, then run cleanup as the account that owns the cache or correct the directory permissions according to your system policy. |
| Cleanup appears to have removed profile data you expected to keep | Cache and profile locations can be separate, and cache operations are not documented as profile cleanup. | Identify the configured profile path independently. Back up needed profile data before performing any profile-specific deletion. |
7. Performance, reliability, and disk-space considerations
Clearing the full cache can reclaim the space occupied by all managed browser downloads in that cache, but the space recovered depends on which builds are present. The Puppeteer installation guide’s approximate Chrome download sizes vary by operating system; they are estimates, not a promise of current disk usage. If your goal is to remove only obsolete versions, targeted uninstall or trimCache() can avoid removing a build your current project needs, though trimCache() does not account for other Puppeteer versions sharing the cache.
Cleanup is a local disk operation, but a subsequent browser setup may need to download a binary again. In CI, avoid clearing a cache that later jobs rely on unless those jobs install the expected build. For repeatable builds, keep the configured cache path and browser version aligned with the project’s Puppeteer configuration.
Or skip the browser setup
If the task is to capture a page rather than manage a local Puppeteer browser, ScreenshotNeo returns a screenshot or PDF from one GET request. Its API options cover full-page and element captures, viewport and device settings, waiting, headers and cookies, and more. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpCookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, no card required.
FAQ
Does clearing Puppeteer’s browser cache uninstall Puppeteer?
No. The browser download and the JavaScript package are separate. Clearing the cache removes managed browser downloads; remove the package separately with your package manager if that is your goal.
Can I clear only Chromium from the command line?
The verified CLI commands here list or clear managed browser downloads. For one browser build, use the documented uninstall(options) API with the exact browser, build ID, and cache directory.
Will clearing the cache delete Chrome profiles?
The cited browser-management documentation does not say that it deletes profiles. Treat profiles as separate data and check their configured location independently.
Why did Puppeteer download a browser again?
The puppeteer package downloads a compatible Chrome for Testing build during installation. A later install or setup may therefore repopulate a cleared cache. puppeteer-core does not download Chrome when installed.
