Puppeteer BrowserContext Options Explained

BrowserContextOptions is an optional object passed to browser.createBrowserContext(options). In Puppeteer 25.12.0, it has three documented properties: downloadBehavior, proxyServer, and proxyBypassList. A new context also isolates its storage, including cookies and local storage, from other contexts. Puppeteer createBrowserContext reference · BrowserContextOptions reference

1. What BrowserContext options are for

A browser context is an independent user session inside a browser. Create one when separate jobs or users should not reuse each other’s cookies or local storage, or when a group of pages needs its own proxy or download policy.

The options configure the context at creation time. They are not page options and do not replace browser launch configuration. The documented call returns a promise for a BrowserContext; create pages from it with context.newPage().

2. The three options

Option	Type	Use
`downloadBehavior`	`DownloadBehavior`	Defines behavior when a file is downloaded. If omitted, Puppeteer uses the default behavior. Consult the type reference for the installed release before choosing values.
`proxyServer`	`string`	Sets a proxy server, optionally including a port, for requests from the context.
`proxyBypassList`	`string[]`	Lists hosts that bypass the configured proxy.

All three are optional. The reference explicitly describes the default only for downloadBehavior; do not infer a particular proxy default from the blank default cells in the interface table. Proxy credentials can be set using Page.authenticate(), according to the interface documentation.

3. Create a context and page

Install Puppeteer in a Node.js project with npm install puppeteer. The following complete ES module example creates an isolated context, uses a proxy endpoint as an illustration, navigates, and closes resources even if navigation fails:

import puppeteer from 'puppeteer';

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

try {
  context = await browser.createBrowserContext({
    proxyServer: 'http://proxy.example:8080',
    proxyBypassList: ['localhost'],
  });

  const page = await context.newPage();
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  console.log(await page.title());
} finally {
  if (context) await context.close();
  await browser.close();
}

The proxy hostname is illustrative, not a real provider or tested endpoint. If no context-level settings are needed, call browser.createBrowserContext() with no argument. Puppeteer documents that newly created contexts do not share cookies or cache with other contexts. See the method reference.

4. Configure proxy routing and authentication

Set proxyServer to the proxy endpoint you intend the context’s requests to use. Add a bypass list only for hosts that should connect outside that proxy. The option is an array of host strings; check the exact matching syntax against your Puppeteer and browser setup if you need patterns beyond simple hosts.

For a proxy requiring credentials, the docs point to Page.authenticate(). Configure authentication on each page that needs it:

const context = await browser.createBrowserContext({
  proxyServer: 'http://proxy.example:8080',
  proxyBypassList: ['localhost'],
});
const page = await context.newPage();

await page.authenticate({
  username: process.env.PROXY_USERNAME,
  password: process.env.PROXY_PASSWORD,
});

await page.goto('https://example.com');

Keep credentials in environment variables or a secret store, not source control. Authentication behavior can depend on the target browser and proxy configuration, so verify it in the environment where the automation runs.

5. Configure downloads

downloadBehavior uses Puppeteer’s DownloadBehavior type. The BrowserContextOptions reference says that omitting it uses the default behavior, but the interface page does not enumerate the type’s values. Avoid copying values from a different Puppeteer release: inspect the DownloadBehavior reference for the version installed in your project.

Downloads may also depend on browser support, the destination environment, permissions, and the page’s own behavior. If you need a particular policy, pin the Puppeteer version and verify the resulting file handling in your deployment environment.

6. Context isolation, pages, and cleanup

Each context has isolated storage such as cookies and local storage. A popup opened by a page—for example, with window.open—belongs to the parent page’s context. In Chrome, non-default contexts are incognito; the default context can also be incognito when Chrome is launched with --incognito. Puppeteer’s BrowserContext reference

Create contexts with browser.createBrowserContext(); the class constructor is internal and should not be called directly.
Create pages within the desired context using context.newPage().
Close a non-default context with await context.close(). This closes its associated pages too.
The default browser context cannot be closed with context.close().
Close the browser after the work is complete when the process owns the browser instance.

Use a fresh context for independent sessions. Reusing one context intentionally reuses that context’s storage among its pages; creating another context provides a separate storage boundary.

7. Choosing the right setup

Need	Configuration	Practical check
Separate user sessions	Create a context per session	Confirm cookies and local storage are not expected to carry between sessions.
Route context traffic through a proxy	`proxyServer`	Check reachability and authentication with the browser process’s network environment.
Let selected hosts bypass the proxy	`proxyBypassList`	Test each bypass host and confirm it is not routed through the proxy.
Control file downloads	`downloadBehavior`	Use the installed version’s `DownloadBehavior` definition and verify output handling.

These properties solve different configuration needs. They are not a ranking of alternatives: select the setting that matches the session’s routing, storage, or download requirements.

8. Performance, reliability, and cost considerations

The cited Puppeteer API references describe behavior, not performance measurements or cost benchmarks. They do not establish a numeric overhead for creating contexts. In practice, create a context at the isolation boundary you need, close it when finished, and measure your own workload if browser resource use matters.

For reliability, use try/finally cleanup so errors during navigation do not leave the context or browser open. Set navigation waits according to the page behavior you need rather than assuming every page becomes network-idle. Keep proxy credentials secret and validate proxy routing in the runtime environment. Puppeteer itself does not specify third-party proxy pricing; account for any proxy service separately.

9. Troubleshooting

Symptom	Likely cause	Fix
TypeScript rejects an option or value	The code targets a different Puppeteer version, or a guessed `DownloadBehavior` value was used.	Check the installed version’s `BrowserContextOptions` and `DownloadBehavior` API references; use only declared properties and values.
Requests do not use the expected proxy	The proxy endpoint is malformed or unreachable, or the destination appears in the bypass list.	Check endpoint and port, remove or adjust the bypass entry, and test from the same host/container as the browser.
Proxy responds with an authentication error	Credentials were not configured for the page or are incorrect.	Call `page.authenticate()` with the correct credentials before navigation; keep them outside source code.
A page is still open after cleanup	Cleanup was skipped on an error path, or the page belongs to another context.	Put context and browser closure in `finally`; close the context that owns the page.
`context.close()` fails for the default context	The default browser context cannot be closed.	Close the browser when finished, or close only a non-default context created with `createBrowserContext()`.
Cookies unexpectedly persist between pages	The pages share the same context.	Create separate contexts for sessions that require isolated storage.

10. Or skip the browser setup

If your task is to capture a website rather than manage Puppeteer sessions, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns an image or PDF; see the API documentation.

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

ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, and failed loads are never billed, and response headers identify the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Read the docs, then sign up for 1,000 free screenshots a month with no card.

11. FAQ

Are BrowserContextOptions required?

No. The options argument is optional; call browser.createBrowserContext() without it when you need only a new isolated context.

No. A popup opened by a page belongs to that page’s browser context.

Can I instantiate BrowserContext directly?

No. Puppeteer marks its constructor internal. Create contexts through the browser API.

Do the options configure every browser feature?

No. This interface lists these three context options. Other behavior may be configured through browser launch or page APIs; consult the documentation for the exact setting and installed version.

Version note: The option names and behavior described here follow Puppeteer’s 25.12.0 API reference. Check the official reference matching your installed version before relying on version-specific configuration.