Node.js Reference ยท fs and fs/promises
Node.js fs.realpath() method
Reference for fs.realpath() in Node.js: resolve symlinks, dots and relative parts into one canonical absolute path, plus the .native variant and ENOENT errors.
fs.realpath(path, callback) turns a path into its canonical form: absolute, with every symbolic link followed and every . and .. segment collapsed. Two different paths that lead to the same file give the same answer, so it is the right tool for comparing locations or for checking where a path really ends up.
Unlike path.resolve(), which only does string arithmetic, realpath() asks the file system. That means the path must exist, and the answer can change if a link is repointed.
import fs from "node:fs"; console.log(fs.realpathSync("./src/../src/index.js"));
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
fs.realpath(path[, options], callback) fs.realpathSync(path[, options]): string fs.realpath.native(path[, options], callback) fs.realpathSync.native(path[, options]): string fsPromises.realpath(path[, options]): Promise<string>
| Name | Description |
|---|---|
path |
The path to resolve. Relative paths start from process.cwd(). A string, Buffer or URL. |
options |
An encoding name, or { encoding }. Default "utf8"; "buffer" returns a Buffer. |
callback |
Called as callback(err, resolvedPath). |
Returns: the canonical absolute path as a string (or Buffer).
Errors: ENOENT if any part of the path is missing, including a dangling symlink at the end. ELOOP if links form a cycle. ENOTDIR if a middle segment is a file. EACCES if a directory cannot be searched.
Usage notes
- The path must exist. To canonicalize a file you are about to create, resolve its parent directory with
realpath()and join the file name on. - JavaScript vs native. The plain
realpath()is implemented in JavaScript withlstatandreadlinkcalls and caches what it learns for the duration of one call.realpath.nativecalls the operating system'srealpath(3)and is a single trip. On Linux they agree. Differences show on Windows and macOS, such as letter case and how drive paths are written. - Windows: the native version can report the real on-disk letter case, which the JavaScript one may not.
- Security checks: to confirm a user-supplied file is inside an upload folder,
realpath()both and test the prefix with a trailing separator (startsWith(root + path.sep)). A plain string comparison of unresolved paths is fooled by..and symlinks. There is still a small time-of-check race between the check and the use. - Temporary folders can be links. On macOS
os.tmpdir()sits behind a link, so a path you built and the onerealpath()returns differ. Resolve the base once and compare against that. - Cost: every path segment may need a system call. Do not call it in a hot loop; cache the result for fixed roots.
- Not for display. The canonical path may leak internal layout (release folders, mount points). Show users the path they asked for.