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.
import { pathToFileURL } from 'node:url'; const url = pathToFileURL('/srv/my app/data.json'); // URL { href: 'file:///srv/my%20app/data.json', ... }
Try it
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.
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
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 fornew 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
windowsoption is handy in tests and tools that format paths for another operating system:pathToFileURL('C:\\temp\\a.txt', { windows: true }).hrefgivesfile:///C:/temp/a.txton any platform. - Use
.hrefwhen an API wants a string, as inimport(). Many file APIs, such asfs.readFile(), accept theURLobject directly. - The opposite conversion is
fileURLToPath(). Do not usedecodeURIComponent(url.pathname)instead: it mishandles Windows drive letters and UNC hosts. - In ES modules,
import.meta.urlis already a file URL, so you rarely need this function for files next to the current module.