Skip to content
Tutorials Center
My learning

Topics

Node.js Reference Β· path, os and url

Node.js url.pathToFileURL() function

Reference for url.pathToFileURL() in Node.js: turn a file system path into a correctly percent-encoded file: URL, with the windows option, edge cases and pitfalls.

pathToFileURL() takes a file system path and returns a URL object with the file: scheme. It resolves relative paths against the current working directory first, then percent-encodes every character that is not allowed in a URL path: spaces, %, #, ? and non-ASCII characters.

Building 'file://' + path by hand breaks as soon as a path contains a # or a space, because the URL parser reads the # as the start of a fragment. This function does the escaping for you. The most common use is import(): the ES module loader wants a URL, and on Windows a bare path such as C:\app\plugin.mjs is not accepted there.

NODE
import { pathToFileURL } from 'node:url';

const url = pathToFileURL('/srv/my app/data.json');
// URL { href: 'file:///srv/my%20app/data.json', ... }

Try it

Node.js Encoding awkward paths

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Dynamic import from a path

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
url.pathToFileURL(path[, options])
Name Description
path A string. Relative paths are resolved against process.cwd().
options.windows Boolean. true forces Windows path rules (drive letters, backslashes, UNC paths), false forces POSIX rules. The default follows the current platform. Added in Node.js 22.1.

Returns: a URL object whose protocol is file:.

Errors: a non-string path throws ERR_INVALID_ARG_TYPE.

Usage notes

  • The path is resolved with path.resolve() semantics, so .. and . segments are normalized and a relative path depends on the working directory at the time of the call.
  • A trailing slash is preserved even though path.resolve() would drop it. Keep it when you want the URL to work as a base for new URL('file.txt', base).
  • On POSIX a backslash is a legal file name character, so it is encoded as %5C. On Windows it is a separator and becomes /.
  • The windows option is handy in tests and tools that format paths for another operating system: pathToFileURL('C:\\temp\\a.txt', { windows: true }).href gives file:///C:/temp/a.txt on any platform.
  • Use .href when an API wants a string, as in import(). Many file APIs, such as fs.readFile(), accept the URL object directly.
  • The opposite conversion is fileURLToPath(). Do not use decodeURIComponent(url.pathname) instead: it mishandles Windows drive letters and UNC hosts.
  • In ES modules, import.meta.url is already a file URL, so you rarely need this function for files next to the current module.