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.
import { renameSync } from 'node:fs'; renameSync('report.tmp', 'report.json');
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.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.
EXDEVacross volumes: moving between drives, mounted volumes or Docker bind mounts fails. The fallback iscopyFile()followed byunlink().- 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 uselink()plusunlink()for an atomic no-clobber move. - Windows: renaming over an open file or a file that antivirus is scanning can fail with
EPERMorEBUSY. 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.txttoA.txtworks on macOS and Windows, but compare names carefully in your own checks.