Skip to content

How to save and load cookies in Puppeteer

Cookies are how most sites remember that a browser has already signed in, accepted a consent banner or picked a region.

OUTPUT FORMATSHTMLJSONMarkdown

Puppeteer exposes that store through two page methods: one reads the current cookies, the other writes cookies back. This guide shows the read-then-write pattern, walks through a two-page example, and gives you a checklist for the common case where the cookies are restored but the page still behaves as if you were a new visitor.

The two methods that do all the work

Reading is handled by page.cookies(), which returns the cookies currently associated with the page. Writing is handled by page.setCookie(), which accepts cookie objects and installs them on the page. A save-and-load cycle is therefore just: call the read method, keep the returned array somewhere, and later pass those cookie objects to the write method.

One detail trips people up. page.setCookie() takes cookies as separate arguments, not as a single array, so the usual call spreads the saved array: page.setCookie(...cookies). If you pass the array without spreading it, you are handing the method one argument that is not a cookie object.

A two-page walkthrough

The example launches a browser, opens a new page and navigates to a first site. It then stores the result of page.cookies() in a variable called cookies. Next it navigates the same page to a second address, calls page.setCookie(...cookies) to install the saved cookies, reads the cookies again with page.cookies(), and prints them as JSON before closing the browser.

The printed output is the evidence that matters: it shows what the page actually holds after the write, not what you hoped to write. Treat that second read as your assertion step rather than an optional extra.

One caveat belongs to the example's shape rather than to Puppeteer. The first site and the second site are different origins, and a browser will not let one origin's cookies be applied as another origin's cookies. If the second read comes back without the cookies you passed in, origin mismatch is the first thing to check, not a bug in the method.

What a cookie object carries

Each entry returned by page.cookies() describes one cookie. When you plan to restore cookies later, these are the fields worth understanding:

  • name and value: the pair the server reads. This is the part that usually carries the session.
  • domain and path: the scope in which the browser will send the cookie. A cookie scoped to one host is not sent to a different host.
  • expires: when the cookie stops being valid. A cookie with no expiry is a session cookie and disappears when the browser session ends.
  • httpOnly: the cookie is hidden from page scripts but still sent with requests, which is typical for authentication cookies.
  • secure: the cookie is only sent over HTTPS.
  • sameSite: controls whether the cookie travels with cross-site requests.

When a restore appears to do nothing, compare these fields between what you saved and what the second read returns. A changed domain, an expired timestamp or a secure flag on a plain HTTP page will each produce a silent no-op rather than an error.

Checklist for a restore that does not stick

Work through these in order; each one rules out a different failure layer.

  1. Did the first read return anything? Log the length of the saved array before navigating away. An empty array means there was nothing to save, which is a capture problem, not a restore problem.
  2. Are the cookies scoped to the origin you are restoring into? Compare the domain field on each saved cookie with the host you navigate to next.
  3. Did you spread the array? Confirm the call reads page.setCookie(...cookies) and not page.setCookie(cookies).
  4. Did you read back after writing? A second page.cookies() call tells you whether the browser accepted the cookies.
  5. Has anything expired? Check the expires field against the current time before blaming the method.
  6. Is the page still logged out despite the cookies being present? That points at server-side session state, not at Puppeteer: the session may have been invalidated, or the site may require additional headers or tokens beyond the cookie.

Separating these layers matters because the fixes are completely different. Steps 1 to 5 are client-side and you can verify each one from the browser. Step 6 is outside the browser's control.

Keeping cookies beyond a single run

The array in the example lives only in memory. Close the process and it is gone, which is fine for a single script that saves and restores within one run but useless if you want a session to survive between runs.

The pattern is the same either way: capture with page.cookies(), serialize the array to storage you control, read it back on the next run, and pass the parsed objects to page.setCookie(). What changes is only where the array sits between the two steps. Two practical notes: store the serialized data somewhere private, because a session cookie is a credential; and expect the stored cookies to age, so a restore that worked last week can fail today purely on expiry.

Where this fits in a scraping workflow

Cookie handling is usually one step inside a larger Puppeteer script. If you are still assembling that script, the related questions cover loading local files, waiting for a page to finish loading, capturing background requests and responses, locating elements by CSS selector or XPath, and taking screenshots. Each of those is a separate concern from cookie transfer, and mixing them up is a common reason a script appears to fail at the cookie step when the real problem is a page that had not finished loading.

Cookie fields and what they change on restore
FieldWhat it holdsWhy it matters when loading
nameThe cookie's identifierMust match what the server expects; a renamed cookie is a different cookie
valueThe stored stringUsually carries the session token
domainHost scopeA cookie for one host is not applied to another host
pathURL path scopeLimits which requests carry the cookie
expiresExpiry timestampAn expired cookie is discarded on write
httpOnlyScript visibility flagHidden from page scripts but still sent with requests
secureHTTPS-only flagNot sent over plain HTTP
sameSiteCross-site send policyAffects whether the cookie travels with cross-site requests

Field meanings describe standard browser cookie attributes; the example itself only demonstrates reading and writing the array, not each field individually.

Failure checklist by layer
SymptomLayerFirst check
Saved array is emptyCaptureDid page.cookies() run on a page that had cookies?
Cookies missing after writeScopeDo the saved domains match the target host?
Write call throws or does nothingCall formIs the array spread into page.setCookie()?
Cookies present but session inactiveServerHas the session been invalidated server-side?
Worked before, fails nowTimeHas the expires timestamp passed?

Diagnostic ordering reflects how the two methods behave; it is not a substitute for inspecting the actual cookies in your script.

Frequently asked questions

Which Puppeteer methods save and load cookies?

page.cookies() returns the cookies for the current page, and page.setCookie() installs cookie objects onto the page. A save-and-load cycle is a read followed later by a write.

Why does page.setCookie(...cookies) use a spread operator?

Because page.setCookie() accepts cookies as separate arguments. Spreading the saved array passes each cookie object individually; passing the array directly hands the method a single argument that is not a cookie.

Can I copy cookies from one website to another?

Not across different origins. Cookies are scoped by domain, so a browser will not apply one site's cookies as another site's cookies. The two-page example works as a demonstration of the read and write calls, but a cross-origin restore will not carry a session.

Do saved cookies survive after the browser closes?

Only if you store them yourself. The array returned by page.cookies() exists in your script's memory, so serialize it to storage you control and read it back on the next run. Session cookies without an expiry also end with the browser session.

The cookies load but the page is still logged out. Why?

Once the cookies are present in the browser, the remaining variable is server-side: the session may have been invalidated, or the site may expect additional headers or tokens. Verify the cookie is actually present with a second page.cookies() call before looking further.