# npkill — Find and Remove Heavy node_modules Instantly

> A terminal tool that lists all node_modules directories on your system, shows their disk usage, and lets you delete them interactively.

## Install

Save in your project root:

# npkill — Find and Remove Heavy node_modules Instantly

## Quick Use
```bash
# Run without installing
npx npkill

# Or install globally
npm i -g npkill
npkill

# Scan a specific directory
npkill -d ~/projects
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-8ad62534
Author: AI Open Source