How to Set Cookies with Puppeteer Cookie Parameters

Use BrowserContext.setCookie() for a specific Puppeteer browser context, or Browser.setCookie() for the default context. Pass cookie objects as separate arguments, with name and value required. Set the cookie in the same context as the page that will use it, and do so before navigation when the first request needs the cookie. The older Page.setCookie() API is obsolete; use the browser or context API instead.

Set a cookie before navigating

This runnable ES module example creates an isolated context, adds a cookie, opens a page in that context, and then navigates:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const context = await browser.createBrowserContext();

  await context.setCookie({
    name: 'session',
    value: 'example-value',
    domain: 'example.com',
    path: '/',
    httpOnly: true,
    secure: true,
    sameSite: 'Lax',
  });

  const page = await context.newPage();
  await page.goto('https://example.com');

  console.log(await context.cookies());
} finally {
  await browser.close();
}

Install Puppeteer in your project with npm install puppeteer. If your project uses CommonJS, replace the import with const puppeteer = require('puppeteer'); and run the code inside an async function. The example uses createBrowserContext() to make the cookie’s storage scope explicit.

Default context versus an isolated context

Use the context that owns the page. Browser contexts isolate their storage, including cookies and local storage.

// Default browser context
await browser.setCookie({ name: 'theme', value: 'dark', domain: 'example.com', path: '/' });
const page = await browser.newPage();

// A separate context
const context = await browser.createBrowserContext();
await context.setCookie({ name: 'theme', value: 'dark', domain: 'example.com', path: '/' });
const isolatedPage = await context.newPage();

Both setters take one or more cookie objects as arguments. To set multiple cookies, pass them separately; do not pass one array argument:

await context.setCookie(
  { name: 'region', value: 'us', domain: 'example.com', path: '/' },
  { name: 'consent', value: 'accepted', domain: 'example.com', path: '/' },
);

Cookie parameters explained

The current browser and context setter input is CookieData. Its required fields are name and value. Optional fields documented by Puppeteer include:

Field	What it controls	Practical guidance
domain	The cookie’s domain scope.	Set the scope deliberately for the host or domain that should receive the cookie.
path	The URL path scope.	Use / when the cookie should apply across the site’s paths.
expires	Expiration date as a numeric value.	Omit it for a session cookie. Confirm the expected numeric representation for your installed Puppeteer and browser version.
httpOnly	Whether client-side JavaScript can read the cookie.	Set it when page scripts should not access the cookie.
secure	Whether the cookie is restricted to secure connections.	Set it for cookies intended for HTTPS.
sameSite	Same-site request behavior.	Choose a value that matches the site’s navigation and request needs; no one setting is right for every flow.
priority	Cookie priority.	Documented as Chrome-only; check compatibility before depending on it.
sourceScheme	The cookie’s source scheme.	Documented as Chrome-only; check compatibility before depending on it.
partitionKey	Partitioned-cookie key information.	Semantics vary by browser: the reference describes a top-level site in Chrome and source-origin matching for Firefox.

For example, omit expires for a session cookie, or supply it when persistence is needed:

await context.setCookie({
  name: 'session',
  value: 'example-value',
  domain: 'example.com',
  path: '/',
  secure: true,
  httpOnly: true,
  sameSite: 'Lax',
  // expires: numeric expiration date, when required
});

Cookie fields express scope and behavior, but the right choices depend on the site. The Puppeteer reference documents available fields; it does not prescribe a universal security policy. Browser-specific fields should be checked against the browser and Puppeteer version installed in your project.

Read and remove cookies

Read cookies from the browser or context whose storage you need to inspect:

const cookies = await context.cookies();
console.log(cookies);

The context API also exposes deleteCookie() and deleteMatchingCookies(). Use these when a test must clear one or more cookies, and verify the result by reading cookies again:

await context.deleteMatchingCookies({ name: 'session' });
console.log(await context.cookies());

Check the installed Puppeteer API reference for the accepted matching fields and signatures before using a deletion filter. The older page-level cookie APIs are deprecated in favor of Browser and BrowserContext methods.

CookieParam and the deprecated page API

You may encounter CookieParam in older examples and type references. It is associated with the page-level cookie API and includes a url field, which can influence default domain, path, and source-scheme values. The current browser-level setter uses CookieData, and Puppeteer marks Page.setCookie() obsolete. For new code, use Browser.setCookie() or BrowserContext.setCookie().

Common problems and fixes

Symptom	Likely cause	Fix
The page does not send the cookie.	The cookie was written to a different browser context than the page uses.	Set it through the page’s owning context, or use browser.setCookie() and a page in the default context.
The first navigation misses the cookie.	The cookie was set after navigation began.	Set it before calling page.goto(), then navigate in the same context.
Puppeteer rejects the cookie input.	A required field is missing, an unsupported field or value is used, or an array was passed as a single argument.	Provide name and value, check optional fields against the installed API, and pass multiple cookie objects as separate arguments.
The cookie is absent on a particular route or host.	Its domain or path scope does not match the target URL.	Review domain and path; use a scope that includes the URL being tested.
A secure cookie is not sent over an insecure URL.	secure: true restricts it to secure connections.	Test through HTTPS when that is the intended cookie policy.
A browser-specific option behaves differently across environments.	priority, sourceScheme, or partition-key behavior is browser-dependent.	Check the installed Puppeteer and browser versions, and avoid depending on unsupported fields.
An example using page.setCookie() is deprecated.	The page-level setter is obsolete.	Move the call to browser.setCookie() or context.setCookie().

Performance, reliability, and cost

Cookie setup is a small part of a browser automation flow; the main reliability concern is ensuring the cookie is present in the correct context before the request that needs it. Keep context ownership explicit, use the browser-level setter only when the default context is intended, and avoid relying on optional fields without checking browser support. Puppeteer cookie setup itself has no per-cookie charge specified in the cited API documentation; infrastructure costs depend on where and how you run the browser.

Or skip the browser setup

If your goal is a clean screenshot rather than a browser automation test, ScreenshotNeo is a website screenshot API and MCP server. Its request takes a URL and returns an image or PDF. For a capture, use the API rather than setting browser cookies yourself. See the ScreenshotNeo API docs.

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

import requests

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

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. 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; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Can I set more than one cookie in a call?

Yes. Pass each cookie object as its own argument to setCookie().

Does a cookie without an expiry persist after the browser closes?

It is a session cookie. Set expires when a persistent expiration is needed.

Should I always set sameSite to Lax?

No universal value fits every site. Choose according to the navigation and request behavior your application requires.

Can I use these methods with a non-default context?

Yes. Use that context’s setCookie(), cookies(), or deletion method so the operation applies to its isolated storage.

References

• Puppeteer Cookies guide
• CookieData interface
• Browser.setCookie()
• BrowserContext API
• Page.setCookie() obsolete API
• CookieParam interface