# deepclean ๐งน โ Fast Rust Cache Cleaner & Disk Space Recovery
**deepclean** is a fast, parallel command-line tool written in Rust that reclaims disk space by cleaning Cargo `target/` build directories, removing unused dependencies, and clearing global toolchain caches (npm, Bun, cargo, pip, uv, Homebrew, HuggingFace, Playwright, Puppeteer, and more).
It works as a `cargo` subcommand (`cargo deepclean`) and scans your projects in parallel across all CPU cores, so cleaning dozens of repositories takes seconds instead of minutes.
[](https://github.com/yingkitw/deepclean)
[](https://www.rust-lang.org/)
## Why deepclean?
Rust projects accumulate **gigabytes** of build artifacts in `target/` directories. A single workspace can consume 5โ10 GB; a folder of projects can eat 50+ GB. On top of that, global toolchain caches (npm's `_cacache`, Bun's install cache, HuggingFace model weights, Playwright browsers) silently grow to tens of gigabytes over months of development.
**deepclean solves three problems at once:**
- ๐ **Parallel Cargo cleaning** โ removes `target/` directories across many projects simultaneously, using all CPU cores.
- ๐งน **Unused dependency removal** โ detects and optionally removes dependencies in `Cargo.toml` that your source code no longer uses, speeding up builds.
- ๐พ **Global cache cleaning** โ lists npm, Bun, cargo, pip, uv, Homebrew, HuggingFace, and other caches with estimated reclaimable sizes, then lets you interactively pick which to clean.
## Quick Start
### Install
```bash
# From source (recommended for latest features)
git clone https://github.com/yingkitw/deepclean.git
cd deepclean
cargo install --path .
# Or directly from the repository
cargo install --git https://github.com/yingkitw/deepclean.git
```
> **Note:** Ensure `~/.cargo/bin` is on your `PATH` so the `cargo deepclean` subcommand is found.
### First run
```bash
# Clean target/ directories in the current folder and all subfolders
cargo deepclean
# Preview what would be cleaned (no deletion)
cargo deepclean --dry-run
```
## Features
### Cargo project cleaning
- โ
**Parallel processing** โ cleans multiple projects simultaneously across all CPU cores
- โ
**Smart workspace detection** โ scans `Cargo.toml` manifests to collapse workspace members to their root, no subprocesses required
- โ
**Size filtering** โ `--min-size 100MB` cleans only projects above a threshold
- โ
**Exclude patterns** โ skip directories with glob patterns (`-e "**/node_modules"`)
- โ
**Dry-run mode** โ preview exactly what would be cleaned before deleting
- โ
**Progress bars** โ real-time progress via `indicatif`
- โ
**JSON output** โ machine-readable results for scripts and CI
### Unused dependency detection
- โ
**Built-in detection** โ parses `Cargo.toml` and scans source code; no external tools required
- โ
**Report mode** โ `--clean-deps` lists unused dependencies
- โ
**Auto-remove** โ `--remove-deps` removes them (requires `cargo-edit`)
### Global toolchain cache cleaning (new)
- โ
**Discovers 44 caches** โ npm, Bun, pnpm, Yarn, Deno, node-gyp, Vercel CLI, Cypress, Electron, Prisma, Chrome DevTools MCP, Selenium, cargo registry/git, sccache, pip, uv, Poetry, Conda, NuGet, Gradle, Maven, JVM shared cache, Homebrew, HuggingFace, PyTorch, Puppeteer, Playwright, go-build, Go modules, Xcode DerivedData/DeviceSupport, iOS Simulator, SwiftPM, CocoaPods, JetBrains, VS Code-family editors, Bazel, Zig, GitHub CLI, ChromaDB, codex-runtimes, opencode
- โ
**Estimated sizes** โ shows reclaimable disk space per cache, computed in parallel
- โ
**Risk tagging** โ each cache is marked **safe** (re-fetches on demand) or **heavy** (re-download required, e.g. model weights or browser binaries)
- โ
**Interactive selection** โ pick caches by number, type `all`, or `q` to quit
- โ
**Non-interactive mode** โ `--caches --all` cleans every safe cache without prompting
- โ
**Dry-run and JSON** โ preview without deleting, or emit JSON for automation
## CLI Options
| `[DIRECTORY]` | Directory to start cleaning from (default: `.`) |
| `-j, --jobs <N>` | Number of parallel jobs (default: CPU count) |
| `-e, --exclude <PATTERN>` | Exclude directories matching a glob pattern (repeatable) |
| `--dry-run` | Preview mode โ no changes are made |
| `--min-size <SIZE>` | Only clean projects above this size (e.g. `100MB`, `1GB`) |
| `--clean-deps` | Detect and report unused dependencies |
| `--remove-deps` | Remove unused dependencies (requires `cargo-edit`) |
| `--caches` | List global toolchain caches and interactively select which to clean |
| `--all` | With `--caches`: clean all safe caches non-interactively (heavy caches skipped) |
| `--interactive` | Prompt for confirmation before cleaning projects |
| `-v, --verbose` | Verbose output |
| `--json` | Output results as JSON |
| `-h, --help` | Print help |
## Usage Examples
### Clean all Cargo projects in a directory tree
```bash
cargo deepclean /path/to/projects
```
### Clean only large projects (above 500 MB)
```bash
cargo deepclean --min-size 500MB
```
### Preview without deleting (dry run)
```bash
cargo deepclean --dry-run
```
### Find and remove unused dependencies
```bash
# Detect only
cargo deepclean --clean-deps
# Detect and remove (requires cargo-edit)
cargo deepclean --remove-deps
```
### Exclude specific directories
```bash
cargo deepclean --exclude "**/target/debug" --exclude "**/node_modules"
```
### Limit parallelism
```bash
cargo deepclean -j 8
```
### Clean global toolchain caches
Beyond per-project `target/` directories, dev toolchains accumulate large global caches. `--caches` discovers them, shows their sizes, and lets you interactively pick which to clean:
```bash
# Interactive: pick caches by number, 'all', or 'q' to quit
cargo deepclean --caches
# Preview without deleting
cargo deepclean --caches --dry-run
# Non-interactive: clean every safe cache, no prompts (heavy caches skipped)
cargo deepclean --caches --all
# Machine-readable list of discovered caches (JSON array)
cargo deepclean --caches --json
# Clean safe caches and report results as JSON (automation/CI)
cargo deepclean --caches --all --json
```
Each cache is tagged **safe** (pure download cache that re-fetches on demand) or **heavy** (model weights, browser binaries, or runtimes that must re-download). Caches are removed with `rm -rf` and regenerated automatically by their tools on next use. `--caches --all` never touches heavy caches โ clean those via the interactive selection.
#### Supported caches
| Rust | cargo registry cache, cargo registry src, cargo git checkouts, sccache |
| Python | pip, uv, Poetry, Conda pkgs |
| JS/TS | npm (`_cacache` + `_npx`), Bun, pnpm, Yarn, Deno, node-gyp, Vercel CLI, Cypress, Electron, Prisma engines, Chrome DevTools MCP, Selenium Manager |
| .NET | NuGet packages |
| Java | Gradle caches, Maven repository, JVM shared class cache |
| Apple | Xcode DerivedData, Xcode DeviceSupport, iOS Simulator, SwiftPM, CocoaPods |
| IDE | JetBrains caches, VS Code-family editor caches (Code, Insiders, VSCodium, Cursor, Windsurf, Trae, Qoder, Positron, Kiro, Void) |
| Other | Homebrew, Puppeteer, Playwright (+ ms-playwright-mcp), HuggingFace, PyTorch models, go-build, Go modules, Bazel, Zig, GitHub CLI, ChromaDB, codex-runtimes, opencode |
### JSON output for automation and CI
```bash
cargo deepclean --json
cargo deepclean --caches --json
```
When `--clean-deps` is enabled, each entry in `results` also carries an
`unused_deps` array (`name`, `location`) with the detection findings. The field
is omitted entirely when dependency detection did not run, so existing JSON
consumers see a stable shape.
`--caches --json` emits the discovered caches as a JSON array of
`{ id, name, category, risk, size_bytes, note }` entries. With `--caches --all
--json`, the output is instead a JSON array of clean results
(`{ id, name, success, freed_bytes, error }`), one per safe cache โ dry-run
included (`success: true`, nothing deleted).
## How It Works
1. **Discovery** โ recursively finds all `Cargo.toml` files using `walkdir` and resolves workspace membership by scanning manifests for `[workspace]` tables (no external commands).
2. **Filtering** โ applies exclude patterns and optional `--min-size` threshold.
3. **Cleaning** โ removes `target/` directories in parallel via `rayon`; falls back to direct `rm -rf` if `cargo clean` fails.
4. **Dependency analysis** โ parses `Cargo.toml` and scans `src/`, `examples/`, `tests/`, and `build.rs` for dependency usage; reports or removes unused crates.
5. **Cache cleaning** (`--caches`) โ scans known global cache locations, computes sizes in parallel, presents an interactive selection, and removes chosen caches. `--caches --all` skips the prompt and cleans every safe cache.
## Requirements
- **Rust toolchain** and **Cargo** (for installation and project cleaning)
- **Optional:** [`cargo-edit`](https://github.com/killercup/cargo-edit) for `--remove-deps` (detection works without it)
```bash
cargo install cargo-edit
```
## Performance
deepclean is built in Rust for maximum performance:
- **Parallel execution** across all CPU cores via `rayon`'s work-stealing scheduler
- **Efficient directory traversal** with `walkdir` and early pruning of hidden/excluded dirs
- **Parallel size calculation** for global cache discovery
- **Minimal memory footprint** โ streams results rather than buffering
## FAQ
### Is deepclean safe to use?
Yes. `--dry-run` previews every change without deleting anything. Project cleaning removes only `target/` directories (regenerated by the next `cargo build`). Cache cleaning removes only the listed cache directories, which tools re-create on next use. The `--interactive` flag adds a confirmation prompt before cleaning projects.
### Does deepclean modify my source code?
Only when you explicitly pass `--remove-deps`, which edits `Cargo.toml` to remove unused dependencies. Without that flag, deepclean only deletes `target/` directories and (with `--caches`) global cache directories.
### How is deepclean different from `cargo clean`?
`cargo clean` cleans a single project. deepclean finds and cleans **all** projects in a directory tree in parallel, detects unused dependencies, and cleans global toolchain caches โ none of which `cargo clean` does.
### Which caches does `--caches` support?
npm, Bun, pnpm, Yarn, Cypress, Electron, cargo registry, pip, uv, Poetry, Gradle, Maven, Homebrew, Puppeteer, Playwright, HuggingFace, PyTorch, go-build, Go modules, Xcode DerivedData, and codex-runtimes. See the [Supported caches](#supported-caches) table above.
### Can I use deepclean in CI?
Yes. Use `--json` for machine-readable output and `--dry-run` for safe previews. The exit code is non-zero if any cleaning operation fails.
## Contributing
Contributions are welcome! Please open issues or submit pull requests at [github.com/yingkitw/deepclean](https://github.com/yingkitw/deepclean).
## License
Apache-2.0
## Links
- **Repository:** [github.com/yingkitw/deepclean](https://github.com/yingkitw/deepclean)
- **Documentation:** [docs.rs/deepclean](https://docs.rs/deepclean)
- **Crates.io:** [crates.io/crates/deepclean](https://crates.io/crates/deepclean)