Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import fs from "node:fs";

console.log(fs.realpathSync("./src/../src/index.js"));

Try it

Node.js Following links and dots

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 Missing paths and the promise form

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
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 with lstat and readlink calls and caches what it learns for the duration of one call. realpath.native calls the operating system's realpath(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 one realpath() 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.