Puppeteer defaultBrowser(): Get the Default Browser

defaultBrowser and browser.defaultBrowserContext() refer to different things in Puppeteer:

defaultBrowser is a configuration property that selects which browser Puppeteer uses. The current configuration reference lists chrome as its default. The PUPPETEER_BROWSER environment variable can override the setting.
browser.defaultBrowserContext() is a method on a launched or connected Browser. It returns that browser’s default BrowserContext.

If you are looking for defaultBrowser() as a method to retrieve the browser itself, that is not the API described by the current Puppeteer references. Use the configuration property to choose a browser, or call defaultBrowserContext() on a Browser when you need its default session context.

1. Browser selection and browser context are different

What you need	Use	Where
Select the browser Puppeteer uses	`defaultBrowser`	Puppeteer configuration; can be overridden by `PUPPETEER_BROWSER`
Get the default session context of a running browser	`browser.defaultBrowserContext()`	On a `Browser` instance
Get the context that owns an existing page	`page.browserContext()`	On a `Page` instance
Make a separate session	`browser.createBrowserContext()`	On a `Browser` instance

A browser has at least one default context. A Browser can have multiple Page objects, and each page belongs to a browser context. Contexts isolate storage such as cookies and localStorage.

2. Get the default browser context

Install Puppeteer in a Node.js project if it is not already installed:

npm install puppeteer

Save this as contexts.mjs and run it with node contexts.mjs:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();

try {
  // This returns the default BrowserContext for this Browser.
  const defaultContext = browser.defaultBrowserContext();
  const defaultPage = await defaultContext.newPage();
  await defaultPage.goto('https://example.com', {
    waitUntil: 'domcontentloaded',
  });
  console.log('Default context page title:', await defaultPage.title());
} finally {
  // Close the browser to close its pages and contexts.
  await browser.close();
}

The default context cannot be closed directly. Close the browser when the whole browser session is finished.

3. Create an isolated browser context

Use a new context when work needs a separate session, for example, when you want one workflow’s cookies and cache kept apart from another’s. Puppeteer documents that a newly created context does not share cookies or cache with other browser contexts.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
let isolatedContext;

try {
  const defaultContext = browser.defaultBrowserContext();
  const defaultPage = await defaultContext.newPage();
  await defaultPage.goto('https://example.com');

  isolatedContext = await browser.createBrowserContext();
  const isolatedPage = await isolatedContext.newPage();
  await isolatedPage.goto('https://example.com');

  console.log('Default page context:', defaultPage.browserContext() === defaultContext);
  console.log('Isolated page context:', isolatedPage.browserContext() === isolatedContext);
} finally {
  // A created context can be closed when its pages are no longer needed.
  if (isolatedContext) {
    await isolatedContext.close();
  }
  await browser.close();
}

In Chrome, non-default contexts are incognito. Chrome’s default context can also be incognito when Chrome is launched with --incognito. Context isolation concerns browser storage; it does not by itself guarantee that a site will treat requests as unrelated users.

4. Choose the right API for the situation

Set which browser Puppeteer uses

Configure the defaultBrowser property in Puppeteer’s configuration when you want to select the browser implementation. Its documented default is chrome, and PUPPETEER_BROWSER can override the configuration. This property is not called on a browser instance. Check the configuration reference for the supported browser values for the Puppeteer version in your project.

Get the context for an existing page

If a function receives a page and needs the session that owns it, call page.browserContext() rather than creating another context:

async function inspectPageContext(page) {
  const context = page.browserContext();
  console.log('Page belongs to a BrowserContext:', Boolean(context));
  return context;
}

Use the default context or an isolated context?

Use browser.defaultBrowserContext() when the page should use the browser’s default session.
Use browser.createBrowserContext() when you need storage isolated from other contexts in the same browser.
Use page.browserContext() when you already have a page and need to inspect or operate on its owning context.

5. Cleanup, performance, and reliability

Keep browser and context lifetimes explicit. Close a context you created when its pages are done, and close the browser when the job is over. Do not call close() on the default browser context; the API documentation says it cannot be closed.

Reuse: If several pages should share a session, create them from the same context. Creating a separate context gives storage isolation, but it also means the new context will not share cookies or cache with the others.
Cleanup: Put browser shutdown in a finally block so navigation or page errors do not skip cleanup.
Navigation: Choose a waitUntil condition that fits the page. Waiting for domcontentloaded can be more appropriate than waiting for every network connection on pages with long-running requests; it does not guarantee that all client-rendered content is ready.
Cost: Puppeteer itself does not define a per-context price in these API references. Runtime and infrastructure cost depend on how and where you run the browser; no benchmark or cost estimate is implied here.

6. Troubleshooting

Symptom	Likely cause	Fix
`defaultBrowser is not a function`	`defaultBrowser` is being treated as an instance method.	Use it as a configuration property to select a browser, or use `browser.defaultBrowserContext()` to retrieve the default context.
`browser.defaultBrowserContext is not a function`	The value called `browser` may not be a Puppeteer `Browser` instance, or the code may be using an incompatible API/version.	Check how the browser was launched or connected and consult the API reference for the installed Puppeteer version.
Cannot close the default context	The default context is not closable.	Close the browser to end the session, or close a context created with `createBrowserContext()`.
Cookies appear missing in a new context	Each context isolates storage, and a created context does not share cookies or cache with other contexts.	Use the same context when shared session state is intended, or establish the required state separately in the new context.
The configuration seems ignored	`PUPPETEER_BROWSER` may override the configured browser choice.	Check the environment for that variable and confirm the configuration applies to the Puppeteer process being launched.
A page loads but expected content is absent	The chosen navigation wait condition may finish before client-side content appears.	Wait for the relevant selector or application-specific ready state after navigation rather than assuming a navigation event means the page is fully rendered.

7. Frequently asked questions

Does `defaultBrowser()` return a Browser?

No. The current API reference describes defaultBrowser as a configuration property. The similarly named method browser.defaultBrowserContext() returns a BrowserContext.

Can I close the default browser context?

No. Close the browser when you want to end its session. A separately created context can be closed independently.

No. Puppeteer documents that a context created with createBrowserContext() does not share cookies or cache with other contexts.

How can I find which context owns a page?

Call page.browserContext().

8. Or skip the browser setup

If your goal is to capture a website screenshot rather than manage Puppeteer contexts, ScreenshotNeo provides a screenshot API and MCP server for developers. One GET request can return PNG, JPEG, WebP, or PDF. Cookie and consent banners, newsletter popups, and chat widgets are handled before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. AI agents can use its MCP tools, including take_screenshot, get_page_info, and capture_pdf.

cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(({ writeFile }) => writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

See the ScreenshotNeo API documentation for request options and setup. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up free and get 1,000 screenshots a month with no card.