{"id":13832,"library":"puppeteer-core","title":"Puppeteer Core","description":"puppeteer-core is a high-level API for controlling Chrome or Firefox over the DevTools Protocol or WebDriver BiDi. Unlike its sibling `puppeteer`, `puppeteer-core` does *not* download a browser binary during installation, making it suitable for environments where you manage the browser executable yourself (e.g., AWS Lambda, CI/CD, or existing browser installations). The current stable version is 24.41.0, released in April 2026. The project maintains a rapid release cadence, often synchronizing with Chrome and Firefox releases, typically with multiple updates per month to incorporate new browser features, bug fixes, and security patches. It is designed for scenarios requiring fine-grained control over the browser executable or minimal install size, offering the same powerful API for web scraping, test automation, and PDF generation.","status":"active","version":"24.41.0","language":"javascript","source_language":"en","source_url":"https://github.com/puppeteer/puppeteer#main","tags":["javascript","puppeteer","chrome","headless","automation","typescript"],"install":[{"cmd":"npm install puppeteer-core","lang":"bash","label":"npm"},{"cmd":"yarn add puppeteer-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add puppeteer-core","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"puppeteer-core requires a compatible browser executable (e.g., Chrome, Chromium, or Firefox) to be present on the system for its operations, as it does not bundle one itself. The user must provide the path to this executable.","package":"Chrome/Chromium or Firefox","optional":false}],"imports":[{"note":"While CommonJS `require` works, modern applications and the library itself primarily use ES Modules. TypeScript projects should use `import`.","wrong":"const puppeteer = require('puppeteer-core');","symbol":"puppeteer","correct":"import puppeteer from 'puppeteer-core';"},{"note":"These are interfaces/classes from the Puppeteer API. Use named imports for specific types or classes. `type` keyword is only for type-only imports in TypeScript.","wrong":"import type { Browser, Page } from 'puppeteer-core'; // Wrong if you need the runtime values","symbol":"Browser, Page","correct":"import { Browser, Page } from 'puppeteer-core';"},{"note":"`launch` is a method of the default `puppeteer` export, not a direct named export from the package root.","wrong":"import { launch } from 'puppeteer-core'; // Not directly exported from the top-level","symbol":"launch","correct":"const browser = await puppeteer.launch({...});"}],"quickstart":{"code":"import puppeteer from 'puppeteer-core';\nimport { Browser, Page } from 'puppeteer-core';\n\nasync function runAutomation() {\n  // IMPORTANT: For puppeteer-core, you MUST specify the executablePath.\n  // This path needs to point to your installed Chrome/Chromium/Firefox executable.\n  // Example for Linux: '/usr/bin/google-chrome'\n  // Example for macOS: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'\n  // Example for Windows: 'C:\\\\Program Files\\\\Google\\\\Chrome\\\\Application\\\\chrome.exe'\n  const browser: Browser = await puppeteer.launch({\n    executablePath: process.env.CHROME_EXECUTABLE_PATH || '/usr/bin/google-chrome', // Provide actual path or use an env variable\n    headless: true, // Use 'true' for new headless mode (default since Puppeteer v21)\n    args: ['--no-sandbox', '--disable-setuid-sandbox'] // Recommended for CI/Linux environments\n  });\n\n  const page: Page = await browser.newPage();\n\n  await page.goto('https://developer.chrome.com/docs/puppeteer/get-started/');\n\n  await page.setViewport({ width: 1080, height: 1024 });\n\n  await page.keyboard.press('/');\n\n  // Type into search box using accessible input name.\n  await page.waitForSelector('::-p-aria(Search)');\n  await page.locator('::-p-aria(Search)').fill('headless testing');\n\n  // Wait and click on the first search result.\n  await page.waitForSelector('.devsite-result-item-link');\n  await page.locator('.devsite-result-item-link').click();\n\n  // Wait for navigation and then locate the full title on the new page.\n  await page.waitForNavigation();\n  const textSelector = await page\n    .locator('::-p-text(Headless Chrome)')\n    .waitHandle();\n  const fullTitle = await textSelector?.evaluate(el => el.textContent);\n\n  console.log('Found title after search: \"%s\".', fullTitle?.trim());\n\n  await browser.close();\n}\n\nrunAutomation().catch(console.error);","lang":"typescript","description":"This quickstart demonstrates how to launch a browser using `puppeteer-core`, explicitly specifying the browser executable path, navigating to a page, interacting with elements, and logging content. It highlights `executablePath` which is crucial for `puppeteer-core`."},"warnings":[{"fix":"To explicitly use the 'new' headless mode, use `headless: true`. To revert to the 'old' headless mode, use `headless: 'shell'` or `headless: 'old'` (though 'old' is discouraged and may be removed). Review your scripts for compatibility with the new headless environment.","message":"The `headless` option for `puppeteer.launch()` changed behavior in Puppeteer v21. Setting `headless: true` now uses the 'new' headless mode by default, which may behave differently than the 'old' headless mode.","severity":"breaking","affected_versions":">=21.0.0"},{"fix":"Launch Chromium with the `--no-sandbox` argument: `puppeteer.launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'] })`. Be aware of the security implications of disabling sandboxing in production.","message":"When running Puppeteer-core in certain Linux environments (especially Docker or CI/CD), Chromium might fail to launch due to sandboxing issues. This is a common security feature on Linux that prevents a browser from doing harm.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you use Jest with Puppeteer, ensure `jest-circus` (or your preferred test runner) is installed as a direct dependency in your project: `npm install --save-dev jest-circus`. Configure your Jest setup as needed.","message":"The default test runner `jest-circus` was removed as a direct dependency in v19. This primarily impacts users relying on Puppeteer's pre-configured Jest setup.","severity":"breaking","affected_versions":">=19.0.0"},{"fix":"Ensure your `executablePath` for `puppeteer-core` points to a recent, stable Chrome installation that is compatible with the `puppeteer-core` version you are using. Keep `puppeteer-core` updated to match the Chrome release cycle.","message":"Starting with Puppeteer v15, the default browser downloaded (for `puppeteer` package) or expected (for `puppeteer-core`) shifted from a custom Chromium build to the stable Chrome browser, which changes its release cycle and potentially some DevTools Protocol behavior.","severity":"gotcha","affected_versions":">=15.0.0"},{"fix":"Prefer using `page.waitForNavigation()`, `page.waitForSelector()`, or the new Locator API (`page.locator('selector').click()`) for improved reliability and clarity in your automation scripts. Consult the official API documentation for recommended patterns.","message":"Legacy Page event handlers (e.g., `page.on('load', ...)`) and certain methods have been superseded by more robust alternatives like `page.waitForNavigation()` or specific locator APIs.","severity":"deprecated","affected_versions":">=19.0.0"}],"env_vars":null,"search_vec":"'2026':68 '24.41.0':64 'api':11,121 'april':67 'autom':126,134 'aw':52 'bidi':23 'binari':36 'browser':35,48,57,92,111 'bug':94 'cadenc':75 'chrome':14,79,132 'ci/cd':54 'control':13,108 'core':2,5,30 'current':60 'design':101 'devtool':19 'download':33 'e.g':51 'environ':43 'execut':49,112 'exist':56 'featur':93 'fine':106 'fine-grain':105 'firefox':16,81 'fix':95 'generat':129 'grain':107 'headless':133 'high':9 'high-level':8 'incorpor':90 'instal':38,58,115 'javascript':130 'lambda':53 'level':10 'maintain':71 'make':39 'manag':46 'minim':114 'month':88 'multipl':85 'new':91 'offer':117 'often':76 'patch':98 'pdf':128 'per':87 'power':120 'project':70 'protocol':20 'puppet':1,4,27,29,131 'puppeteer-cor':3,28 'rapid':73 'releas':65,74,82 'requir':104 'scenario':103 'scrape':124 'secur':97 'sibl':26 'size':116 'stabl':61 'suitabl':41 'synchron':77 'test':125 'typescript':135 'typic':83 'unlik':24 'updat':86 'version':62 'web':123 'webdriv':22","created_at":"2026-04-20T01:56:32.297442+00:00","updated_at":"2026-04-20T01:56:32.297442+00:00","problems":[{"fix":"Double-check the `executablePath` to ensure it's correct for your operating system and points directly to the browser executable (e.g., `chrome.exe`, `Google Chrome`, `chromium`). Ensure the browser is actually installed at that location.","cause":"The `executablePath` provided to `puppeteer.launch()` does not point to a valid browser executable, or the path is incorrect.","error":"Error: Failed to launch the browser: No browser found at specified executablePath"},{"fix":"Verify the selector is correct and unique. Increase the timeout for `page.waitForSelector({ timeout: 60000 })` or `page.locator().waitHandle({ timeout: 60000 })`. Add `await page.waitForNavigation()` or `await page.waitForLoadState('networkidle')` before trying to find the element if it appears after a navigation or network request.","cause":"Puppeteer could not find the specified DOM element within the default (or specified) timeout period. This can happen if the element is not rendered, the selector is wrong, or the page takes too long to load/render.","error":"TimeoutError: waiting for selector `selector` failed: timeout 30000ms exceeded"},{"fix":"Check the website for client-side errors during navigation. Add error handling around `page.goto()` and other navigation actions. Ensure the browser instance is stable and has sufficient resources. Sometimes, launching with `headless: false` can help debug on-screen errors.","cause":"The browser tab or page closed unexpectedly during navigation, possibly due to a JavaScript error on the page, network issues, or the page itself closing.","error":"Protocol error (Page.navigate): Target closed."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://pptr.dev","github":"https://github.com/puppeteer/puppeteer.git#main","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/puppeteer-core","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","testing","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}