Skip to content

How to Load Local Files in Puppeteer

Puppeteer navigates to a file on disk the same way it navigates to a web address: through page.goto.

OUTPUT FORMATSHTMLJSONMarkdown

The difference is the address format. A local file needs the file protocol and a full path from the filesystem root, not a relative path from the script.

The two conditions for a file:// navigation

Two things must be true before page.goto will open a local file. First, the URL must begin with file://. Second, the path that follows must be absolute, meaning it starts at the filesystem root rather than at the current working directory. A relative path such as ./index.html will not resolve the way you expect inside the browser context.

The example below uses an absolute path on a macOS-style filesystem. The same pattern applies on other systems, with the path adjusted to that platform's root and separators.

Build the file URL before launching

Keep the path construction separate from the browser launch so the URL is easy to inspect. A common pattern is to define the absolute path as a string, prepend file://, then pass the result to page.goto after creating a new page. The original walkthrough launches with headless: false, which is useful while you are confirming that the right document appears.

If your script receives a relative path, resolve it first with Node's path module, then prefix the protocol. That keeps the absolute-path rule explicit instead of relying on the browser to guess.

Why a file loads but its neighbors may not

Browsers apply the same-origin policy to local files. A page opened from file:// is treated as its own origin, so JavaScript running in that page may be blocked from reading other local files that are not part of the same origin. The script also needs filesystem permission to reach the path you pass in.

This is the distinction worth remembering: a failed navigation usually means the path or protocol is wrong, while a page that loads but cannot read a sibling file usually means the browser's origin rules are doing their job.

When to serve the file over HTTP instead

If the page needs to fetch other local assets or scripts across paths, serving the directory through a local HTTP server is the cleaner option. Requests then share an http:// origin, and the same-origin policy applies in the familiar web way rather than the restrictive file:// way.

Use this quick check before choosing an approach:

  • Single self-contained HTML file with no cross-file reads: file:// with an absolute path is enough.
  • Page that fetches JSON, images, or scripts from other local folders: start a local server and navigate to its http:// address.
  • Unsure why a read is failing: confirm the navigation succeeded first, then check whether the blocked request is cross-origin.

Related Puppeteer questions

Other Puppeteer tasks that pair with local-file navigation include waiting for a page to finish loading, finding elements by CSS selector or XPath, saving and loading cookies, capturing background requests, and taking screenshots. A broader JavaScript scraping walkthrough covers Puppeteer's role as a headless browser.

Frequently asked questions

Why does page.goto fail with a relative local path?

The file URL needs an absolute path. Resolve the relative path against the current working directory first, then prepend file:// before calling page.goto.

Can a file:// page read another local file with fetch?

Often no. Browsers apply the same-origin policy to local files, so a page opened from file:// may be blocked from reading files outside its own origin. Serving the folder over a local HTTP server avoids that restriction.

Does Puppeteer need a special launch option to open local files?

The navigation itself uses the standard page.goto call. The original example launches with headless: false, but that is a visibility choice for confirming the page, not a requirement for file navigation.