npkill — Find and Remove Heavy node_modules Instantly

Introduction

npkill is a lightweight command-line tool that scans your filesystem for node_modules directories, displays each one with its size, and lets you selectively delete them with a single keystroke. It helps JavaScript developers reclaim gigabytes of disk space from old or unused project dependencies.

What npkill Does

• Recursively scans directories to find every node_modules folder on disk
• Displays results in a sorted, interactive terminal UI showing path and size
• Lets you navigate with arrow keys and delete selected directories with the spacebar
• Calculates total freed space as you remove directories
• Supports filtering and targeting specific base directories

Architecture Overview

npkill is written in TypeScript and runs on Node.js. It uses a recursive filesystem walker to locate node_modules directories, calculates their sizes using OS-native commands for speed, and renders an interactive TUI using ANSI escape sequences. The tool streams results as they are found rather than waiting for a full scan to complete.

Self-Hosting & Configuration

• Install globally via npm or run directly with npx for zero-install usage
• Use the -d flag to target a specific directory instead of scanning from the current location
• Exclude directories from scanning with the -E flag
• Set the --sort flag to order results by size or path
• Requires Node.js 10+ and works on Linux, macOS, and Windows

Key Features

• Interactive TUI with real-time size calculation and deletion
• Streams results progressively so you can start deleting before the scan finishes
• Lightweight with minimal dependencies for fast startup
• Cross-platform support across Linux, macOS, and Windows
• Shows running total of freed disk space during the session

Comparison with Similar Tools

• Manual rm -rf — error-prone and requires knowing exact paths; npkill is visual and safe
• find + du — powerful but requires composing shell commands; npkill is interactive
• ncdu — general disk usage analyzer; npkill targets node_modules specifically
• npx depcheck — identifies unused npm packages; npkill removes entire dependency trees
• pnpm — uses symlinks to share packages globally; npkill cleans up existing projects

FAQ

Q: Will npkill delete node_modules for active projects? A: It shows all found directories and lets you choose which to delete. You decide what to remove.

Q: How much space can I expect to recover? A: This varies widely, but developers with many projects often recover 10-50 GB or more.

Q: Can I use it in a CI script? A: npkill is designed for interactive use. For scripted cleanup, use find with -exec rm.

Q: Does it work with monorepos? A: Yes. It finds nested node_modules directories within monorepo workspace structures.

Sources

• https://github.com/voidcosmos/npkill
• https://npkill.js.org