node_modules is Why Your Mac is Full: Find and Delete All of Them

B | | Post-Cleanup + Pruned Caches | ~0.3 GB (Active only) | 30s (Regen) | N/A | <0.5 GB |

Key Findings:

• Flat dependency managers (npm/yarn) waste 60–80% of disk space on duplicate transitive packages.
• pnpm’s hardlink architecture reduces per-project footprint by 50–70% while maintaining identical node_modules structure for compatibility.
• Systematic cleanup of node_modules, build caches, and package manager stores typically recovers 20–50GB on active developer machines.
• Regenerating dependencies from lockfiles is safe, fast, and eliminates drift.

Core Solution

1. Discovery & Assessment

Identify all node_modules directories and quantify storage impact:

find ~ -name "node_modules" -type d -maxdepth 5 -exec du -sh {} \; 2>/dev/null

Output example:

1.2G    /Users/you/projects/webapp/node_modules
487M    /Users/you/projects/api-server/node_modules
923M    /Users/you/code/nextjs-blog/node_modules
341M    /Users/you/tutorials/react-course/node_modules
756M    /Users/you/clients/dashboard/node_modules
...

Calculate total footprint:

find ~ -name "node_modules" -type d -maxdepth 5 -exec du -sm {} \; 2>/dev/null | awk '{total += $1} END {printf "Total: %.1f GB\n", total/1024}'

Quick directory count:

find ~ -name "node_modules" -type d -maxdepth 5 2>/dev/null | wc -l

2. Nuclear Deletion (Safe Regeneration)

node_modules is a fully regenerable cache. Delete all instances under your home directory:

find ~ -name "node_modules" -type d -maxdepth 5 -exec rm -rf {} + 2>/dev/null

Critical Pre-Checks:

• Stop all running dev servers to prevent crashes.
• Ensure package.json and lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml) are intact.
• Source code remains untouched; dependencies will regenerate on next npm install/yarn/pnpm install.

3. Package Manager Cache Cleanup

Global caches accelerate installs but bloat over time. Clean them per manager:

npm

# Check size
du -sh ~/.npm

# Clean it
npm cache clean --force

Yarn (v1/Classic)

# Check size
du -sh ~/Library/Caches/Yarn

# Clean it
yarn cache clean

pnpm

# Check size
du -sh ~/Library/pnpm

# Remove unreferenced packages
pnpm store prune

Bun

# Check size
du -sh ~/.bun/install/cache

# Manual cleanup (no built-in clean command)
rm -rf ~/.bun/install/cache

Deno

# Check size
du -sh ~/.deno

Turborepo

# Check size
du -sh ~/.turbo

Unified Cache Audit

echo "=== Package Manager Caches ===" && \
du -sh ~/.npm 2>/dev/null; \
du -sh ~/Library/Caches/Yarn 2>/dev/null; \
du -sh ~/Library/pnpm 2>/dev/null; \
du -sh ~/.bun/install/cache 2>/dev/null; \
du -sh ~/.deno 2>/dev/null; \
du -sh ~/.turbo 2>/dev/null

4. Prevention & Optimization

Switch to pnpm

npm install -g pnpm
pnpm import        # converts package-lock.json to pnpm-lock.yaml
pnpm install       # creates a linked node_modules

Configure .npmrc for Lean Installs

# Don't install optional dependencies (often native binaries you don't need)
optional=false

# Disable package-lock generation for throwaway projects
# (only use this for experiments, not real projects)
# package-lock=false

Regular Maintenance & Artifact Cleanup

# List projects by last modification date
ls -lt ~/projects/*/package.json 2>/dev/null | head -20

Delete safe build outputs: dist/, build/, .next/, .nuxt/, out/. They regenerate on npm run build.

Pitfall Guide

1. Deleting While Dev Servers Are Running: Active processes hold file locks or expect node_modules to persist. Crashing dev servers mid-operation can corrupt state or cause unhandled exceptions. Always stop servers before cleanup.
2. Ignoring Build Artifacts: dist/, .next/, and similar directories often consume 200–500MB per project. They are fully regenerable and safe to delete alongside node_modules.
3. Blindly Deleting Package Manager Caches: Removing caches without pruning (e.g., rm -rf ~/.npm) forces full re-downloads, slowing future installs. Use npm cache clean --force, yarn cache clean, or pnpm store prune to maintain cache integrity.
4. Overlooking Lockfile Dependency: node_modules is ephemeral; your lockfile is the source of truth. Deleting dependencies without a valid lockfile breaks reproducible builds and introduces version drift.
5. Manual Cleanup Fatigue: CLI find commands lack context (stale vs. active projects) and degrade in performance on large trees. Schedule monthly audits or use automation to track modification dates and project activity.
6. Misunderstanding pnpm Hardlinks: Deleting a pnpm node_modules does not free the central content-addressable store. Use pnpm store prune to safely remove unreferenced packages without breaking active projects.

Deliverables

📘 Storage Recovery Blueprint

1. Scan: Run unified find and cache audit commands to map current footprint.
2. Prune: Stop dev servers → Execute node_modules deletion → Run manager-specific cache clean/prune commands.
3. Migrate: Switch to pnpm, run pnpm import, and verify hardlink deduplication.
4. Configure: Apply ~/.npmrc optimizations and add build artifact cleanup to project .gitignore/CI pipelines.
5. Schedule: Automate monthly stale-project detection and cache pruning via cron or macOS shortcuts.

✅ Pre-Cleanup Checklist

• All dev servers stopped
• package.json and lockfiles committed/backed up
• find scan completed and total size recorded
• Package manager caches audited (du -sh for npm/yarn/pnpm/bun/deno/turbo)
• Build artifacts (dist/, .next/, etc.) identified for deletion
• pnpm installed and pnpm import executed (if migrating)
• ~/.npmrc configured for optional dependency exclusion
• Post-cleanup verification: cd into active project → pnpm install → npm run dev confirms regeneration