Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.symlink() method

Reference for fs.symlink() in Node.js: create symbolic links, how relative targets resolve, dangling links, the type argument on Windows and common errors.

fs.symlink(target, path, type, callback) creates a symbolic link (symlink): a tiny file at path whose content is the path target. When a program opens the link, the operating system transparently follows it to the target.

Note the argument order: the target comes first, then the location of the new link. It is the same order as ln -s target linkname, and the reverse of what many people expect from a "copy" style call.

NODE
import fs from "node:fs";

fs.symlinkSync("releases/v2", "current");

Try it

Node.js Creating and following a link

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 Relative targets, dangling links and switching a link

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.symlink(target, path[, type], callback)
fs.symlinkSync(target, path[, type]): undefined
fsPromises.symlink(target, path[, type]): Promise<undefined>
Name Description
target The text stored in the link. Relative paths are resolved against the directory that contains the link. The target does not need to exist.
path Where to create the link. Must not already exist.
type "file", "dir" or "junction". Used only on Windows; ignored elsewhere. Default: detected from the target if it exists, otherwise "file".

Returns: undefined.

Errors: EEXIST if path already exists, ENOENT if the folder for the link does not exist, EPERM on Windows without the privilege to create links, EACCES without write permission to the folder.

Usage notes

  • Relative targets are the top mistake. symlink("data.txt", "sub/link") points at sub/data.txt, not at ./data.txt. Build the target relative to the link's folder with path.relative(path.dirname(link), real).
  • Dangling links are legal. Node does not check that the target exists. A broken link makes stat and readFile fail with ENOENT, while lstat and readlink still work.
  • There is no overwrite option. To replace a link atomically, create a new link under a temporary name and rename it over the old one.
  • Windows: creating links needs administrator rights or Developer Mode. Pass "junction" for directories to avoid that; junctions require absolute targets, and Node converts them. Pass "dir" correctly if the target does not exist yet, because the type cannot be guessed.
  • Symlinks versus hard links: a symlink is a pointer by name and works across file systems and for directories. A hard link (fs.link()) is another name for the same data and needs the same file system.
  • Security: when you unpack or serve user-supplied paths, a link can point outside the folder you meant. Resolve with fs.realpath() and check the prefix.
  • Deleting a link with unlink removes only the link, never the target.