Use browser.createBrowserContext() to create a separate Puppeteer session, open its pages with context.newPage(), and call context.close() when that session is finished. Puppeteer documents that contexts do not share cookies or cache; its BrowserContext reference also describes cookies and localStorage as isolated between contexts. This is storage isolation, not a promise of complete browser-resource or security isolation.
Create a context and run a session
A launched browser has a default browser context. Create another context when a task needs separate documented storage, such as cookies and localStorage, or a cache separate from other contexts. The API reference for Puppeteer 25.12.0 documents browser.createBrowserContext(); the browser-management guide is under Puppeteer’s /next documentation path.
- Launch the browser. Import Puppeteer and call
puppeteer.launch(). - Create a context. Call
browser.createBrowserContext(). - Open pages in it. Call
context.newPage(), notbrowser.newPage(), then navigate as needed. - Close the session. Call
context.close()to close that context and its associated pages. Close the browser separately withbrowser.close()when the overall browser work is done.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const context = await browser.createBrowserContext();
try {
const page = await context.newPage();
await page.goto('https://example.com');
// Work with this session's pages and context-scoped state.
} finally {
await context.close();
}
} finally {
await browser.close();
}The nested try/finally blocks ensure the context is closed even if page work fails, and the browser is then closed even if context cleanup runs into an error. The call sequence combines documented API methods into a cleanup-safe pattern.
What is isolated—and what is not established
Puppeteer describes a BrowserContext as an individual user context. Its documentation says cookies and localStorage are isolated, and the context-creation method says contexts do not share cookies or cache. Use a separate context when those distinctions are needed between automation sessions.
#1 Best Overall
- Cookies: one context’s cookies are not shared with other browser contexts.
- localStorage: the BrowserContext reference identifies it as isolated between contexts.
- Cache:
createBrowserContext()documents that it is not shared across contexts. - Other browser resources: the cited documentation does not establish that every resource is isolated.
- Security boundaries: do not treat contexts as a guarantee of process isolation or as a security boundary for untrusted tenants; the cited statements establish storage isolation, not that broader assurance.
In Chrome, Puppeteer documents all non-default contexts as incognito. The default context may also be incognito if the browser was launched with --incognito. Incognito status does not expand the documented isolation guarantees.
Keep pages and popups in the right session
A page belongs to the context used to create it. Create every page that should share that session with context.newPage(). Puppeteer also documents that a popup opened from a page—for example, through window.open()—belongs to the parent page’s context. That means the popup stays with the session rather than becoming a separate context automatically.
Use one context for pages that should share a session’s state and lifecycle. Use separate contexts when you need the documented cookie, localStorage, and cache separation. Closing one context closes its associated pages; it does not close the entire browser.
Rank #2
Manage cookies at context level
For cookies belonging to a session, use the BrowserContext cookie methods, including cookies(), setCookie(), and the context’s cookie-deletion methods. Puppeteer’s Page API marks page-level cookie methods deprecated and points users to browser- or context-level methods instead.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →const contextCookies = await context.cookies();
console.log(contextCookies);
// Set or delete cookies using the BrowserContext cookie methods
// documented for the Puppeteer version installed in your project.The first call retrieves cookies for the context. Consult the BrowserContext API reference for the exact signatures of setCookie() and cookie-deletion methods for your installed version; do not assume the deprecated Page methods remain the right interface.
Close one session or the whole browser
context.close() closes the context and all pages associated with it. The default browser context cannot be closed. If you only need to end one isolated session while continuing to use other contexts, close that non-default context. If all browser work is finished, call browser.close() to close the browser.
- Call
context.close()to discard the context’s pages together. - Do not call it expecting to shut down the complete browser.
- Do not try to close the default context; Puppeteer documents that it cannot be closed.
When to choose separate contexts
| Need | Approach | Reason |
|---|---|---|
| Pages should use the same session state | Create those pages from one context | The pages belong to that context; its popups remain there too. |
| Separate documented cookies, localStorage, and cache | Create another context with browser.createBrowserContext() |
Puppeteer documents these storage distinctions across contexts. |
| End a session and its pages together | Call context.close() |
Closing the context closes its associated pages. |
| Need to guarantee isolation of every browser resource or protect untrusted tenants | Do not rely on BrowserContext alone for that guarantee | The cited Puppeteer documentation does not establish complete resource or security isolation. |
Puppeteer’s browser-management guide says to use BrowserContexts when automation tasks need isolation. The documentation provides no performance benchmark comparing a context per task with a page per task, so choose based on the required state separation and lifecycle rather than an assumed speed advantage.
Troubleshooting context issues
Cookies appear in the wrong session
Check how the page was created. A page opened with browser.newPage() is not created through your new context. Use context.newPage() for pages that should belong to that context, and use its context-level cookie methods for session cookies.
Recommended Free Tools
A popup is not a separate session
This is expected: Puppeteer places a popup opened by a page in the parent page’s context. If it needs separately isolated documented storage, create a separate context for the work rather than expecting window.open() to create one.
Rank #4
Closing the context does not close the browser
This is expected. context.close() closes the context’s associated pages; call browser.close() separately when the browser itself should shut down.
Attempting to close the default context fails
Puppeteer documents that the default context cannot be closed. Create and close a non-default context for a disposable session, or close the browser if the entire browser run should end.
Page cookie methods are deprecated
Move cookie handling to the browser- or context-level API. For a session-specific operation, consult the installed version’s BrowserContext reference for method signatures.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Or skip the browser setup
If the task is simply to capture a website rather than automate a browser session, ScreenshotNeo provides a screenshot API and MCP server. One GET request can return an image or PDF. For example, using cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo documentation for API options. It accepts cookie or consent banners and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up free for 1,000 screenshots a month, with no card required.
Frequently Asked Questions
Does Puppeteer create a BrowserContext automatically?
A launched browser has at least one default browser context; create additional contexts with browser.createBrowserContext().
Free tools Windows power users keep installed
One-click scans. No signup required.
Do Puppeteer contexts share localStorage?
Puppeteer’s BrowserContext reference describes localStorage as isolated between contexts.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
