docs: document automatic downloads (#15109)

README.md

@@ -19,6 +19,20 @@ npm i puppeteer # Downloads compatible Chrome during installation.
 npm i puppeteer-core # Alternatively, install as a library, without downloading Chrome.
 ```
 
+:::note
+
+Modern package managers (including npm (see the [RFC](https://github.com/npm/rfcs/pull/868)), pnpm, Yarn, Bun, and Deno) block dependency install scripts by default. If the install script is blocked, Puppeteer will not download the browser during installation, leading to runtime errors.
+
+You can manually download the required browsers after installation by running:
+
+```bash npm2yarn
+npx puppeteer browsers install
+```
+
+Alternatively, you can configure your package manager to allow the install script to run (for example, with npm, by adding `"puppeteer"` to `"allowScripts"` in your `package.json`).
+
+:::
+
 ## MCP
 
 Install [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp),

docs/guides/installation.md

@@ -12,6 +12,29 @@ work](https://pptr.dev/faq#q-why-doesnt-puppeteer-vxxx-work-with-a-certain-versi
 with Puppeteer. The browser is downloaded to the `$HOME/.cache/puppeteer` folder
 by default (starting with Puppeteer v19.0.0). See [configuration](https://pptr.dev/api/puppeteer.configuration) for configuration options and environmental variables to control the download behavior.
 
+:::caution
+
+### Automatic downloads can be blocked
+
+Many modern package managers (such as npm under the new [RFC](https://github.com/npm/rfcs/pull/868), pnpm, Yarn Berry, Bun, and Deno) block dependency install scripts by default. If your package manager is configured to block these scripts, the automatic download will be skipped, and running Puppeteer will throw an error: `Could not find Chrome (ver. ...).`
+
+To resolve this, you can:
+
+1. **Manually install the browser** after package installation by running:
+   ```bash npm2yarn
+   npx puppeteer browsers install
+   ```
+2. **Opt back in** to running the postinstall scripts for Puppeteer (e.g. for npm, by adding `"puppeteer"` to `"allowScripts"` in your `package.json`):
+   ```json
+   {
+     "allowScripts": {
+       "puppeteer": true
+     }
+   }
+   ```
+
+:::
+
 For every release since v1.7.0 we publish two packages:
 
 - [`puppeteer`](https://www.npmjs.com/package/puppeteer)

docs/index.md

@@ -23,6 +23,20 @@ npm i puppeteer # Downloads compatible Chrome during installation.
 npm i puppeteer-core # Alternatively, install as a library, without downloading Chrome.
 ```
 
+:::note
+
+Modern package managers (including npm (see the [RFC](https://github.com/npm/rfcs/pull/868)), pnpm, Yarn, Bun, and Deno) block dependency install scripts by default. If the install script is blocked, Puppeteer will not download the browser during installation, leading to runtime errors.
+
+You can manually download the required browsers after installation by running:
+
+```bash npm2yarn
+npx puppeteer browsers install
+```
+
+Alternatively, you can configure your package manager to allow the install script to run (for example, with npm, by adding `"puppeteer"` to `"allowScripts"` in your `package.json`).
+
+:::
+
 ## MCP
 
 Install [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp),

docs/troubleshooting.md

@@ -51,6 +51,26 @@ You will need to reinstall `puppeteer` in order for the configuration to take
 effect. See [Configuring Puppeteer](./guides/configuration) for more
 information.
 
+### Blocked install scripts
+
+If you are using a package manager that blocks dependency install scripts by default (such as npm under the new [RFC](https://github.com/npm/rfcs/pull/868), pnpm, Yarn Berry, Bun, or Deno), the postinstall script that automatically downloads the browser will not run.
+
+To manually download the required browsers, run:
+
+```bash npm2yarn
+npx puppeteer browsers install
+```
+
+Alternatively, you can opt back in to running the postinstall scripts by updating your project's `package.json` (for npm):
+
+```json
+{
+  "allowScripts": {
+    "puppeteer": true
+  }
+}
+```
+
 ## `net::ERR_BLOCKED_BY_CLIENT` when navigating to an HTTP URL in Chrome
 
 Chrome is rolling out a feature called `HttpsFirstBalancedModeAutoEnable` that