Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.link() method

Reference for fs.link() in Node.js: create a hard link to an existing file, share one inode under two names, and handle EEXIST, EXDEV and EPERM errors.

fs.link(existingPath, newPath, callback) creates a hard link: a second directory entry that points at the same file data as the first. After the call both names are equally real. There is no "original" and no "copy". Writing through one name changes what you read through the other, and the data is freed only when the last name is removed and no process still has the file open.

Hard links are cheap, because no bytes are copied. They are used by backup tools to keep unchanged files across snapshots, and by package managers to share one stored file between many projects. If you want a name that merely points at a path, use fs.symlink() instead.

NODE
import fs from "node:fs";

fs.linkSync("report.txt", "report-alias.txt");

Try it

Node.js Two names, one file

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 What can go wrong

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.link(existingPath, newPath, callback)
fs.linkSync(existingPath, newPath): undefined
fsPromises.link(existingPath, newPath): Promise<undefined>
Name Description
existingPath Path of the file that already exists. A string, Buffer or URL.
newPath The new name to create. Its parent directory must exist. A string, Buffer or URL.
callback Called as callback(err).

Returns: undefined (the promise form resolves with undefined).

Errors: ENOENT if existingPath is missing or the parent of newPath does not exist. EEXIST if newPath is already taken. EXDEV if the two paths are on different file systems. EPERM if existingPath is a directory, or if the file system has no hard link support. ERR_INVALID_ARG_TYPE for a wrong argument type.

Usage notes

  • No overwrite. Unlike copyFile(), link() fails with EEXIST when newPath exists. To replace a name atomically, link to a temporary name and rename() it over the target.
  • Same device only. Both names must live on the same mounted file system, or you get EXDEV. Fall back to fs.copyFile() when you see it.
  • Directories cannot be hard-linked on any common platform. The error is usually EPERM.
  • The link count is stats.nlink (see fs.Stats). It goes up with each link and down with each fs.unlink(). Data is freed at zero.
  • Permissions and owner are shared, because they belong to the file, not to the name. chmod through one name shows up through the other.
  • Not a backup. A hard link protects against deleting a name, not against someone editing the content in place.
  • Editors that save by rename replace the name with a new file, which silently breaks the link. A program that writes in place keeps it.
  • Platforms: works on Linux, macOS and NTFS on Windows. FAT and some network or container volumes reject it.