rimraf

A deep deletion module for node (like `rm -rf`)

weekly downloads115.1M

versionv6.1.3

licenseBlueOak-1.0.0

categorytoolchain

rmrm -rfrm -frremovedirectoryclirmdirrecursive

Overview

rimraf is a Node.js package that provides cross-platform recursive file and directory deletion, emulating Unix's rm -rf command. With over 115 million weekly downloads, it's one of the most widely adopted utility packages in the npm ecosystem, primarily because native filesystem deletion commands behave inconsistently across operating systems—particularly on Windows where permissions and file locking create reliability issues.

The package wraps Node.js's native fs.rm() (available since Node 14.14.0) as its default implementation, but adds critical retry logic, glob pattern support, and platform-specific fallbacks. On Windows, rimraf implements a "move-then-remove" strategy to handle EBUSY errors from locked files, using exponential backoff for retries. This makes it significantly more reliable than raw shell commands or basic filesystem APIs when dealing with large directories like node_modules.

Developers primarily use rimraf in build scripts, test cleanup routines, and CLI tools where consistent deletion behavior across development environments is essential. It provides both asynchronous promise-based APIs and synchronous methods, along with a standalone CLI for use in npm scripts. The package handles edge cases like EMFILE errors (too many open files), supports abort signals for canceling long-running operations, and allows filtering paths with custom functions.

While modern Node.js versions include built-in recursive deletion via fs.rm(), rimraf remains relevant for projects requiring Windows compatibility guarantees, glob pattern matching, or advanced control flow options that the native API doesn't provide. Its battle-tested implementation has been refined over years of production use in major frameworks and toolchains.

Quick Start

typescript

import { rimraf } from 'rimraf';
import { mkdir, writeFile } from 'fs/promises';

// Create test directory structure
await mkdir('temp/logs/archived', { recursive: true });
await writeFile('temp/logs/app.log', 'log data');
await writeFile('temp/logs/archived/old.log', 'old data');

// Basic async deletion
await rimraf('temp/logs');
console.log('Deleted logs directory');

// Glob pattern matching - delete all .log files recursively
await mkdir('temp/cache', { recursive: true });
await writeFile('temp/cache/data.json', '{}');
await writeFile('temp/cache/debug.log', 'debug');

await rimraf('temp/**/*.log', { glob: true });
console.log('Deleted only .log files, cache/data.json remains');

// Filter function - delete files older than threshold
const cutoffTime = Date.now() - 86400000; // 24 hours ago
await rimraf('temp/cache', {
  filter: async (path, stats) => {
    return stats.mtime.getTime() < cutoffTime;
  }
});

// With abort signal for large operations
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

try {
  await rimraf('large-directory', { signal: controller.signal });
} catch (err) {
  if (err.name === 'AbortError') {
    console.log('Deletion aborted after timeout');
  }
}

// Synchronous for simple scripts
import { rimrafSync } from 'rimraf';
rimrafSync('temp');

Use Cases

Build process cleanup: Automatically delete dist/, build/, or .cache/ directories before compilation in webpack, Rollup, or Vite configurations. Many build tools use rimraf internally or recommend it in their setup guides for consistent cross-platform behavior.

Test environment isolation: Remove test fixtures, temporary databases, or generated files between test runs. Frameworks like Jest often integrate rimraf in their setup/teardown hooks to ensure clean state, especially when tests create filesystem artifacts.

node_modules maintenance: Quickly delete node_modules directories in monorepos or during CI cache invalidation. The CLI command rimraf node_modules is standard practice before fresh installs, handling Windows permission issues that prevent manual deletion.

CLI tool development: Implement safe uninstall or clean commands in developer tools. If you're building a CLI that generates scaffolding or manages project files, rimraf provides reliable cleanup without platform-specific code paths.

Glob-based selective deletion: Remove files matching patterns like *.log or temp-* recursively. Combined with the glob option, rimraf can clean specific file types across nested directories without requiring separate glob libraries.

Pros & Cons

Pros

+Cross-platform reliability with Windows-specific fallbacks for locked files and permission errors that break native commands
+Glob pattern support and filter functions enable selective deletion without additional dependencies
+Retry logic with configurable backoff handles EBUSY and EMFILE errors common in concurrent operations
+Both CLI and programmatic APIs with async/sync variants fit different use cases from npm scripts to application code
+Battle-tested in production by millions of projects; used internally by major frameworks and build tools

Cons

−Adds dependency weight when native fs.rm() suffices for simple cases on modern Node.js versions
−Synchronous API is slower due to lack of parallelism compared to async operations on large directories
−AbortSignal support disables the faster native fs.rm implementation, falling back to manual recursion
−Glob features can cause unexpected deletions if patterns aren't carefully tested (e.g., overly broad wildcards)
−Slightly slower than native shell commands on Unix systems due to JavaScript execution overhead

Alternatives

delv8.0.1

Delete files and directories

toolchaindeletefiles

13.2M / week

Install

bash

npm install rimraf

bash

pnpm add rimraf

bash

bun add rimraf

Overview

Quick Start

typescript

import { rimraf } from 'rimraf';
import { mkdir, writeFile } from 'fs/promises';

// Create test directory structure
await mkdir('temp/logs/archived', { recursive: true });
await writeFile('temp/logs/app.log', 'log data');
await writeFile('temp/logs/archived/old.log', 'old data');

// Basic async deletion
await rimraf('temp/logs');
console.log('Deleted logs directory');

// Glob pattern matching - delete all .log files recursively
await mkdir('temp/cache', { recursive: true });
await writeFile('temp/cache/data.json', '{}');
await writeFile('temp/cache/debug.log', 'debug');

await rimraf('temp/**/*.log', { glob: true });
console.log('Deleted only .log files, cache/data.json remains');

// Filter function - delete files older than threshold
const cutoffTime = Date.now() - 86400000; // 24 hours ago
await rimraf('temp/cache', {
  filter: async (path, stats) => {
    return stats.mtime.getTime() < cutoffTime;
  }
});

// With abort signal for large operations
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

try {
  await rimraf('large-directory', { signal: controller.signal });
} catch (err) {
  if (err.name === 'AbortError') {
    console.log('Deletion aborted after timeout');
  }
}

// Synchronous for simple scripts
import { rimrafSync } from 'rimraf';
rimrafSync('temp');

Use Cases

Pros & Cons

Pros

+Cross-platform reliability with Windows-specific fallbacks for locked files and permission errors that break native commands
+Glob pattern support and filter functions enable selective deletion without additional dependencies
+Retry logic with configurable backoff handles EBUSY and EMFILE errors common in concurrent operations
+Both CLI and programmatic APIs with async/sync variants fit different use cases from npm scripts to application code
+Battle-tested in production by millions of projects; used internally by major frameworks and build tools

Cons

−Adds dependency weight when native fs.rm() suffices for simple cases on modern Node.js versions
−Synchronous API is slower due to lack of parallelism compared to async operations on large directories
−AbortSignal support disables the faster native fs.rm implementation, falling back to manual recursion
−Glob features can cause unexpected deletions if patterns aren't carefully tested (e.g., overly broad wildcards)
−Slightly slower than native shell commands on Unix systems due to JavaScript execution overhead