Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.rename() method

Reference for fs.rename() in Node.js: rename or move a file or directory, replace targets atomically, and handle EXDEV errors across file systems.

fs.rename(oldPath, newPath, callback) renames a file or directory. Because a path includes the directory, it also moves: rename('a/x.txt', 'b/x.txt') moves the file from a to b. No data is copied; only the directory entry changes, so it is instant even for huge files.

On the same file system, renaming over an existing file replaces it in a single atomic step. That makes rename() the standard last step of a "write a temporary file, then publish it" pattern.

NODE
import { renameSync } from 'node:fs';

renameSync('report.tmp', 'report.json');

Try it

Node.js Renaming, moving and replacing

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 Errors you can expect

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.rename(oldPath, newPath, callback)
fs.renameSync(oldPath, newPath): undefined
fsPromises.rename(oldPath, newPath): Promise<undefined>

// oldPath, newPath: string | Buffer | URL
// callback: (err: Error | null) => void
Name Description
oldPath Existing file or directory.
newPath New location and name. Replaced if it is a file (or an empty directory when moving a directory).

Returns: nothing.

Errors: ENOENT (missing source, or the target's parent directory is missing), EXDEV (source and target are on different devices or volumes), EISDIR and ENOTDIR (type mismatch), ENOTEMPTY/EEXIST (directory onto a non-empty directory), EACCES/EPERM, EBUSY (a file in use, mostly on Windows).

Usage notes

  • Atomic replace: on POSIX systems the target is always either the old or the new file, never half of each. This holds only within one file system.
  • EXDEV across volumes: moving between drives, mounted volumes or Docker bind mounts fails. The fallback is copyFile() followed by unlink().
  • Parent directories are not created. Make them first with mkdir(..., { recursive: true }).
  • Silent overwrite. There is no "do not replace" flag. Check with access() first (racy), or use link() plus unlink() for an atomic no-clobber move.
  • Windows: renaming over an open file or a file that antivirus is scanning can fail with EPERM or EBUSY. Retrying after a short delay often helps.
  • Open descriptors stay valid after the file is renamed; they refer to the file, not to the name.
  • Renaming to the same path succeeds and does nothing.
  • Different case on case-insensitive systems: renaming a.txt to A.txt works on macOS and Windows, but compare names carefully in your own checks.