Use puppeteer.launch() when Puppeteer should start and own the browser process; use puppeteer.connect() when a browser is already running. For cleanup, browser.close() shuts down the browser, while browser.disconnect() detaches Puppeteer and leaves the browser running. Use browser contexts to isolate task storage and close each created context when its work is done.
Choose who owns the browser process
Puppeteer offers two ways to get a Browser instance. The choice determines whether Puppeteer starts the browser or connects to one managed elsewhere.
As an Amazon Associate I earn from qualifying purchases.
| Method | Use it when | What it does |
|---|---|---|
puppeteer.launch(options) |
Your application should start the browser. | Launches a browser process and returns a Puppeteer Browser object you can use to create pages and contexts. |
puppeteer.connect(options) |
A browser is already running, such as one started by another service or process. | Connects Puppeteer to that browser; it does not provision a remote browser service. |
The Puppeteer Browser management guide documents both approaches and demonstrates connecting with a WebSocket endpoint: Browser management. Use the endpoint supplied by the environment that actually runs the browser, and protect it as an operational credential.
Recommended Free Tools
Launch and clean up a browser you own
This pattern creates a browser, gives one task its own context, and ensures that both the context and browser are closed if the task succeeds or throws an error:
#1 Best Overall
- 【14" HD Display】The business and leisure activities will undoubtedly benefit from the mesmerizing clarity and brilliance.
- 【Intel Processor N150】Enjoy seamless multitasking, consistent performance, and significant energy conservation, making it an outstanding choice for your everyday computing needs.
- 【4GB DDR4 RAM】Get high-bandwidth performance for resource-intensive tasks. Run multiple applications at once and stay responsive.【128GB UFS】 Delivers blazing boot-up speed and enhanced storage capabilities. Effortlessly access your extensive digital library with ease.
- 【Intel Graphics】Enjoy vibrant colors and sharp details that bring your everyday content to life. 【720p HD Camera】Provides high quality video calls, virtual meetings and online interactions.
- 【Windows 11 S】Unlock endless possibilities with a user-friendly operating system, tailored to your needs.【Dimensions & Weight】12.76 x 8.86 x 0.71 inches, 3.24 lbs.【Ports】1x USB Type-C, 2x USB Type-A, 1x Headphone/microphone combo, 1x Media card reader, 1x HDMI 1.4b, 1x AC Smart pin. Wi-Fi 6, Bluetooth, Webcam.
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');
// Do the task in this isolated context.
} finally {
await context.close(); // closes its pages too
}
} finally {
await browser.close(); // closes browser and associated pages
}Save it as an ES module file such as manage-browser.mjs in a project with Puppeteer installed, then run it with Node.js. The example uses the documented APIs; it is an illustrative lifecycle pattern, not a performance or compatibility test.
Closing a context closes its associated pages. Closing the browser closes the browser and its pages. The default browser context is special: it cannot be closed. Create a separate context for a task when you need a lifecycle boundary you can explicitly clean up.
Use contexts to separate tasks
A browser can hold multiple pages, but pages in the same context share that context’s browser state. A browser context gives tasks a way to keep cookies and local storage separate. Puppeteer’s context documentation also says created contexts do not share cache. This is useful when unrelated jobs must not reuse one another’s site state.
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 →Rank #2
- ULTRA HD 4K CLARITY: Stand out in every video call with breathtaking 4K video at 30fps or smooth 1080p at 60fps. Powered by a premium 1/2.5" CMOS sensor and a wide f/1.78 aperture, this webcam captures every detail with vibrant color and stunning low-light performance-so you always look your best
- FAST AUTOFOCUS & SMART LIGHT CORRECTION: No more blurry moments with this webcam for PC. Advanced Phase Detection Auto Focus (PDAF) locks onto your face instantly and keeps you sharp-even when you move. Built-in light correction adapts to your environment, balancing brightness and contrast for a flawless image in dim rooms or bright spaces
- DUAL NOISE-CANCELING MICS: Speak with confidence using this webcam with microphones. Dual microphones with intelligent noise-canceling tech isolate your voice and reduce background noise-suitable for webinars, live streams, team meetings, and virtual interviews
- WIDE-ANGLE LENS & FLEXIBLE MOUNTING OPTIONS: Capture more of your world with an 80 field of view and full 360 swivel rotation. Whether this streaming webcam is mounted on a laptop, monitor, or tripod, it allows you to find the right angle for any setup
- BUILT-IN PRIVACY COVER & PLUG-AND-PLAY SIMPLICITY: Protect your privacy with a secure sliding lens cover that blocks the camera when not in use. Setup is a breeze-just plug into any USB-A port and start streaming, chatting, or recording instantly. The USB webcam is compatible with Zoom, Microsoft Teams, Skype, OBS Studio, and all major platforms across Windows, macOS, and Linux
- Create a context with
await browser.createBrowserContext(). - Create pages within it with
await context.newPage(). - When the task finishes, call
await context.close(); this closes the context’s pages as well. - Do not try to close the default browser context.
For the API details, see Browser.createBrowserContext() and BrowserContext.close().
Connect to a browser managed elsewhere
When another process or deployment starts the browser, connect with the endpoint it provides rather than launching a second browser. A WebSocket endpoint is one documented connection option:
import puppeteer from 'puppeteer';
const browser = await puppeteer.connect({
browserWSEndpoint: process.env.BROWSER_WS_ENDPOINT,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
// Do the task.
} finally {
await browser.disconnect();
}Set BROWSER_WS_ENDPOINT to the endpoint provided by your browser deployment before running the script. This example uses the default browser context via browser.newPage(); if the task needs isolated storage, create a context and close it before disconnecting. A connected browser may be shared or managed by another owner, so do not assume that your Puppeteer client is responsible for stopping it.
Rank #3
- This Certified Refurbished product is tested and certified to look and work like new. The refurbishing process includes functionality testing, basic cleaning, inspection, and repackaging. The product ships with all relevant accessories, a minimum 90-day warranty, and may arrive in a generic box. Only select sellers who maintain a high performance bar may offer 1Certified Refurbished products on Amazon.com.
- Powerful 10th Gen Intel Core i5: Features a quad-core i5-10210U processor (up to 4.2GHz Turbo Boost) for smooth multitasking and business productivity.
- High-Speed Memory & Storage: 32GB DDR4 RAM ensures seamless performance, while the 1TB M.2 NVMe SSD provides ultra-fast boot-up and file access.
- Stunning 15.6-inch FHD Display: Enjoy crisp visuals with 1920x1080 resolution.
- Enhanced Connectivity: Features Wi-Fi, Bluetooth, Type-C, HDMI, and Thunderbolt for versatile connectivity options.
Close the browser or only disconnect?
| Call | Result | Use it when |
|---|---|---|
await browser.close() |
Shuts down the browser and closes its associated pages. | Puppeteer launched the browser for this task and its process should end. |
await browser.disconnect() |
Ends Puppeteer’s connection without shutting down the browser or closing its pages. | The browser process should keep running or is managed by another component. |
The Puppeteer Browser management guide states: “Unlike browser.close(), browser.disconnect() does not shut down the browser or close any pages.” Check the lifecycle contract of the system that launched a connected browser before choosing cleanup.
Free tools Windows power users keep installed
One-click scans. No signup required.
Configure launch for the runtime
puppeteer.launch() accepts options for selecting a browser, choosing a Chrome channel or executable, setting headless mode, specifying a user data directory, controlling startup timeout and signal handling, and passing additional arguments. These settings are not universally portable across browsers or environments. Consult the options for the Puppeteer release installed in your project: LaunchOptions.
Bundled browser or custom executable
Puppeteer says it is only guaranteed to work with its bundled browser. Set a channel or executable path only when your deployment needs a particular installed browser, and validate that combination in the actual runtime rather than assuming every option behaves identically. The launch documentation explains the compatibility caveat: puppeteer.launch().
Rank #4
- 【Efficient Quad-Core Performance】 Powered by a 1.8GHz Quad-Core processor, this mini laptop ensures smooth multitasking. With 2GB RAM and 64GB ROM (expandable to 1TB), it handles daily work and online tasks with ease.
- 【10.1" HD IPS Display & GMS Support】 Featuring a 1280x800 HD IPS screen, this cheap laptop delivers vibrant visuals. Pre-installed with Android OS and GMS, you get direct access to the Google Play Store for apps.
- 【Ultra-Portable & Lightweight Design】 Weighing only 1.76 lbs, this Blue computer is designed for mobility. Its compact form makes it an ideal companion for students and professionals for home schooling or trips.
- 【Versatile Connectivity Options】 Stay productive with dual USB 2.0 ports, a headphone jack, and a TF card slot. This computer for kids and adults features built-in Wi-Fi and Bluetooth for stable connections.
- 【Complete All-in-One Bundle】 This kid laptop kit includes the laptop, carrying bag, mouse, mouse pad, and power adapter. It is the perfect ready-to-use set for online classes, remote work, and entertainment.
Profile and process settings
A userDataDir selects a browser profile directory, while contexts provide separation for task storage within a browser. Choose deliberately: a shared profile can retain browser state beyond a task, whereas a context can be closed with its pages. Startup timeout, signal behavior, and additional arguments should reflect how your process supervisor and runtime manage the browser. Verify option names and supported values against your installed release; the surfaced API pages carry different version labels.
Or skip the browser setup
If the task is simply to capture a webpage, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns an image or PDF; here is the cURL form, saving a WebP screenshot of example.com:
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 request options. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo free.
Troubleshoot common lifecycle problems
- The browser process remains after the script finishes: If your code called
browser.disconnect(), that is expected—the browser is left running. Callbrowser.close()only when your process owns the browser and should stop it. - Pages disappear when a context closes: That is expected. Context closure closes its associated pages; finish page work before closing the context.
- A context-close call fails on the default context: The default context cannot be closed. Use a context created with
browser.createBrowserContext()when you need explicit context cleanup. - Connection fails or reaches the wrong browser: Check that the endpoint is the actual browser’s WebSocket endpoint and is available to the process running Puppeteer.
connect()attaches to an existing browser; it does not start or locate one for you. - A custom executable behaves differently from the bundled browser: Puppeteer’s compatibility guarantee is for its bundled browser. Test the chosen browser, channel, launch arguments, and runtime together.
- Launch takes too long or fails during startup: Review the startup timeout and runtime-specific launch settings in the LaunchOptions documentation, then verify the installed Puppeteer version’s supported options.
- Data appears to persist between tasks: Confirm whether the tasks use separate browser contexts or the same profile and context. Contexts isolate cookies and local storage; a shared context is not a per-task storage boundary.
Version and operational notes
The official browser-management and launch documentation surfaced as Puppeteer Version 25.12.0. API pages for context closure and disconnection carried different version labels, so signatures and supported options should be checked against the version installed in the application. The documentation cited here does not establish a general performance benchmark for choosing launch versus connect; process ownership and cleanup needs should drive that decision.
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.
