Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.readlink() method

Reference for fs.readlink() in Node.js: read the target a symbolic link stores, the encoding option, EINVAL for non-links, and how it differs from realpath.

fs.readlink(path, callback) returns the text stored inside a symbolic link: the path it points to. It does not follow the link and does not check that the target exists. A dangling link is read just as easily as a good one.

The value comes back exactly as it was written. If someone created the link with a relative target, you get a relative string, and it is relative to the folder that holds the link, not to your current working directory. To get a fully resolved absolute path instead, use fs.realpath().

NODE
import fs from "node:fs";

const target = fs.readlinkSync("current");
console.log(target); // e.g. "releases/2024-05"

Try it

Node.js Reading relative and absolute targets

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 Not a link, and resolving relative targets

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.readlink(path[, options], callback)
fs.readlinkSync(path[, options]): string | Buffer
fsPromises.readlink(path[, options]): Promise<string | Buffer>
Name Description
path The symbolic link to read. A string, Buffer or URL.
options An encoding name, or { encoding }. Default "utf8". Use "buffer" to get the raw bytes.
callback Called as callback(err, linkString).

Returns: the stored target as a string, or a Buffer when the encoding is "buffer".

Errors: EINVAL if path exists but is not a symbolic link. ENOENT if path does not exist. EACCES if a parent directory cannot be searched.

Usage notes

  • One hop only. If the target is itself a link, you get the text of the first link. Loop, or call realpath(), to follow the whole chain.
  • No existence check. The result may name a file that is gone. Pair it with fs.access() or stat() if that matters.
  • Relative means relative to the link's folder. Use path.resolve(path.dirname(linkPath), target) to get an absolute path. This is the most common mistake.
  • Detect links first with fs.lstat(path).isSymbolicLink() (see fs.stat() and lstat()) or with withFileTypes in fs.readdir(), instead of catching EINVAL.
  • Windows: junctions and symlinks both read back, but a directory junction often returns an absolute path with a trailing separator, even when you created it with a relative one.
  • Encoding matters for odd names. A target that is not valid UTF-8 is mangled by the default string conversion. Use "buffer" to see the true bytes.