Pass an on-disk directory as userDataDir in Puppeteer’s launch() options to start Chrome with that user data directory. Use a separate BrowserContext instead when you only need isolated cookies and local storage for tasks inside one browser process.
Set a browser profile directory with userDataDir
Puppeteer’s userDataDir launch option takes a string path to a browser user data directory. Choose a directory that the process running Chrome can write to.
As an Amazon Associate I earn from qualifying purchases.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
userDataDir: '/path/to/profile',
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
// Use the browser profile for the task.
} finally {
await browser.close();
}Replace /path/to/profile with a suitable writable path for your environment. The option selects a user data directory; it is not a Chrome profile-management interface.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose between a directory and a browser context
These mechanisms solve different storage needs and should not be treated as interchangeable.
#1 Best Overall
| Need | Use | What to know |
|---|---|---|
| Start Puppeteer with a specific on-disk user data directory | userDataDir in launch() |
The browser process must be able to write to the directory. |
| Separate cookies and local storage among tasks in one browser | Separate BrowserContext instances |
Contexts isolate storage. In Chrome, non-default contexts are incognito. |
For context-level isolation, create a context, open a page in it, and close the context when finished:
const context = await browser.createBrowserContext();
try {
const page = await context.newPage();
await page.goto('https://example.com');
} finally {
await context.close();
}A context is an in-browser isolation boundary, not a named desktop profile directory.
Rank #2
Make sure Chrome can write to the profile
At startup, Chrome writes profile, configuration, and cache files. A directory that exists but is read-only may therefore fail just as a missing or otherwise inaccessible directory can. This is especially relevant in containers with constrained filesystems.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Puppeteer’s troubleshooting guide gives /tmp/.puppeteer-profile as an example for a read-only-container setup where /tmp is writable. Use a writable location appropriate to your runtime; the example is not a universal default.
Close the browser or detach deliberately
browser.close()gracefully closes a browser launched by Puppeteer.browser.disconnect()detaches Puppeteer from an independently running browser. It leaves the browser and its pages running.
Use the lifecycle operation that matches your intent. If the launched browser should stop when the task is done, close it rather than disconnecting.
Troubleshoot profile problems
Chrome fails to start or cannot use the user data directory
Check that the path is valid in the environment where Chrome runs and that the process has write access. In a constrained container, direct profile files to a writable location such as /tmp/.puppeteer-profile if that location is writable in your setup.
Separate tasks are seeing the same cookies or local storage
If the tasks share one browser process and need isolated storage, use separate BrowserContext instances rather than relying on a single shared context. Each context isolates cookies and local storage.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →The browser remains open after Puppeteer stops controlling it
That is the expected result of browser.disconnect(). It detaches without closing the browser or its pages. Call browser.close() when Puppeteer launched the browser and the process should end.
Best Value
- Used Book in Good Condition
The installed browser and Puppeteer versions do not match expectations
Check the supported-browser table for the Puppeteer version actually installed; browser mappings change over time. The Puppeteer documentation version checked on October 3, 2026, lists Puppeteer v25.12.0 with Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. Treat those as versioned documentation facts, not timeless requirements.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is to capture a website rather than manage a Puppeteer browser profile, ScreenshotNeo offers a one-request screenshot API. It can return PNG, JPEG, WebP, or PDF.
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 API documentation for options and response details. Before capture, it can accept cookie/consent banners and remove known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides screenshot tools for AI agents. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month with no card.
Version note
The Puppeteer launch-options reference surfaced for version 25.12.0. Consult the supported-browser table for the release you install, since the compatible browser versions can change.
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.
