Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.rm() method

Reference for fs.rm(), fs.rmSync() and fsPromises.rm() in Node.js: delete files or whole directories with recursive and force options and retry on busy paths.

fs.rm(path[, options], callback) removes a file or, with recursive: true, a directory and everything inside it. With force: true it does not complain when the path does not exist. Together the two options give you the behaviour of the shell command rm -rf.

It was added in Node.js 14.14 to replace the earlier rmdir(path, { recursive: true }) form, which is now deprecated. By default rm() is cautious: it refuses to remove a directory unless you say recursive, and it reports a missing path as an error.

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

rmSync('build', { recursive: true, force: true });

Try it

Node.js The four option combinations

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 Async removal and removing symlinks safely

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.rm(path[, options], callback)
fs.rmSync(path[, options]): undefined
fsPromises.rm(path[, options]): Promise<undefined>

// path: string | Buffer | URL
// options: {
//   force?: boolean,        // default false
//   recursive?: boolean,    // default false
//   maxRetries?: number,    // default 0
//   retryDelay?: number     // default 100 (ms)
// }
Option Description
recursive Remove directories and their contents. Without it a directory is an error.
force Ignore ENOENT when the path does not exist. Other errors still throw.
maxRetries Retry on EBUSY, EMFILE, ENFILE, ENOTEMPTY or EPERM, with a linear back-off. Only used with recursive: true.
retryDelay Milliseconds to wait between retries (increases with each attempt).

Returns: nothing.

Errors: ENOENT (missing, without force), ERR_FS_EISDIR (directory without recursive), EACCES/EPERM, EBUSY, ENOTEMPTY.

Usage notes

  • recursive: true, force: true is the idiom for "make sure it is gone". Use it for temporary folders and build output.
  • Symlinks are removed, not followed. The link goes away and the target is untouched, even in recursive mode.
  • Be careful with paths. An empty string, a variable that is undefined (turned into a path) or a path built from user input can delete the wrong thing. Validate and resolve paths first. Removing / is not special-cased by the API.
  • Windows retries: antivirus tools and indexers briefly lock new files. Set maxRetries: 3 or more with recursive: true to ride that out.
  • Not atomic: a failure in the middle of a tree leaves some of it removed.
  • Compared with relatives: unlink() deletes one file, rmdir() one empty directory, rm() handles both and trees.
  • rmdir(path, { recursive: true }) is deprecated; use rm().