Scan a directory tree and delete matching folders (e.g. node_modules) up to a configurable depth — reclaim disk space without hunting through every project by hand.
- 🔍 Recursively scans a directory tree up to a max depth
- 🎯 Finds any folder by name (defaults to
node_modules) - 📦 Reports how much disk space each match — and the total — takes up
- 🧪
--dry-runmode to preview matches before deleting anything - ✅ Confirmation prompt before deleting (skip it with
-y) - 🚫 Never descends into a matched folder, so it won't waste time scanning what it's about to delete
Install globally to use the deepclean command anywhere:
npm install -g deepclean-cliOr run it without installing, via npx:
npx deepclean-cli -d ./my-projectsdeepclean -d <path> [options]-d, --dir <path> is required — it's the root directory to scan.
Preview all node_modules folders up to 3 levels deep (no deletion):
deepclean -d ~/code --dry-runDelete them, with a confirmation prompt:
deepclean -d ~/codeSkip the confirmation prompt (useful in scripts):
deepclean -d ~/code -yClean up a different folder, e.g. dist build output, scanning deeper:
deepclean -d ~/code -t dist -l 5| Flag | Alias | Description | Default |
|---|---|---|---|
--dir <path> |
-d |
Root directory to scan (required) | — |
--target-dir <name> |
-t |
Folder name to find/delete | node_modules |
--level <number> |
-l |
Max depth to scan (root = level 1) | 3 |
--dry-run |
List matches without deleting anything | false |
|
--yes |
-y |
Skip the confirmation prompt | false |
--version |
-V |
Print the version number | |
--help |
-h |
Print usage information |
deepcleanalways runs a dry-run pass first, printing every match it finds along with its size and a running total.- If no matches are found, it exits — nothing else happens.
- If
--dry-runwas passed, it stops here. - Otherwise, it asks for confirmation (unless
-ywas passed), then deletes each matched folder and reports how much space was freed.
Matched folders are never scanned recursively — once deepclean finds a node_modules (or whatever --target-dir you set), it stops descending into it.
- Always run with
--dry-runfirst if you're unsure what will be matched. - Deletion is permanent — folders are removed with
fs.rmSyncand are not sent to the trash/recycle bin. - The
--leveloption limits how deep the scan goes, counting the root directory itself as level 1.
MIT