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().
import fs from "node:fs"; const target = fs.readlinkSync("current"); console.log(target); // e.g. "releases/2024-05"
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.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()orstat()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()(seefs.stat()andlstat()) or withwithFileTypesinfs.readdir(), instead of catchingEINVAL. - 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.