> ## Documentation Index
> Fetch the complete documentation index at: https://toolkit.astralsolutions.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Reclaim Gigabytes by Cleaning Unused Dev Dependencies

> Scan your projects for node_modules and Python environments, preview recoverable disk space, and purge unused dependency folders safely with Toolkit.

Over months of active development, your `~/projects` folder quietly grows into a graveyard of `node_modules` and `.venv` directories from old experiments, abandoned side projects, and long-forgotten client repos. These directories are notorious for their size — a single `node_modules` folder can easily exceed 500 MB, and a Python virtual environment isn't far behind. Multiply that by dozens of projects and you can find yourself short on disk space without a clear culprit.

This guide walks you through using Toolkit to scan your projects directory, preview exactly how much space you can reclaim, and safely purge the directories you no longer need.

<Warning>
  Purging is permanent and cannot be undone. Always run `--dry-run` first to review exactly what will be removed before executing the actual purge.
</Warning>

## Step-by-Step Cleanup

<Steps>
  <Step title="Scan your projects folder">
    Start by running a scan against your projects directory. Toolkit recursively walks the directory tree and identifies every `node_modules`, `.venv`, `venv`, `env`, and `conda` folder it finds.

    ```bash theme={null}
    toolkit clean scan ~/projects
    ```

    For each discovered directory, the scan output shows:

    * **Path** — the full filesystem path to the environment
    * **Size** — the amount of disk space consumed
    * **Type** — whether it's a `node_modules` or a Python virtual environment (`venv`, `.venv`, `conda`, etc.)
    * **Status** — whether the environment is orphaned (no associated manifest file detected)

    Example output:

    ```
    Scanning ~/projects (depth: 5)...

    ┌─────────────────────────────────────────────┬──────────┬─────────────┬──────────┐
    │ Path                                        │ Size     │ Type        │ Status   │
    ├─────────────────────────────────────────────┼──────────┼─────────────┼──────────┤
    │ ~/projects/old-landing/node_modules         │ 847 MB   │ node_modules│ orphaned │
    │ ~/projects/api-v1/node_modules              │ 312 MB   │ node_modules│ ok       │
    │ ~/projects/data-pipeline/.venv              │ 220 MB   │ venv        │ orphaned │
    │ ~/projects/dashboard/node_modules           │ 640 MB   │ node_modules│ ok       │
    │ ~/projects/ml-experiment/venv               │ 1.1 GB   │ venv        │ orphaned │
    └─────────────────────────────────────────────┴──────────┴─────────────┴──────────┘

    Found 5 targets. Total recoverable: 3.12 GB
    ```
  </Step>

  <Step title="Preview what will be removed">
    Before deleting anything, run the purge in dry-run mode. This calculates and displays the total space to be recovered and lists every directory that would be deleted — without touching a single file.

    ```bash theme={null}
    toolkit clean purge ~/projects --dry-run
    ```

    The dry-run output summarizes the operation:

    ```
    [DRY RUN] The following directories would be removed:

      ~/projects/old-landing/node_modules        (847 MB)
      ~/projects/data-pipeline/.venv             (220 MB)
      ~/projects/ml-experiment/venv              (1.1 GB)
      ~/projects/api-v1/node_modules             (312 MB)
      ~/projects/dashboard/node_modules          (640 MB)

    Total to be freed: 3.12 GB
    No files were deleted. Re-run without --dry-run to apply.
    ```

    Nothing is deleted at this stage. The exit code reflects whether the command succeeded, so you can use this safely in CI checks.
  </Step>

  <Step title="Review the list carefully">
    Go through the list before committing to the purge. Pay special attention to any entries marked as **orphaned** — these are environments where Toolkit found no corresponding `package.json`, `pyproject.toml`, or `requirements.txt` in the parent directory. They are the safest targets for cleanup.

    For entries that are **not** orphaned, verify that you can restore those dependencies by re-running your package manager (`npm install`, `pip install -r requirements.txt`, etc.) before deleting them. If you're unsure, exclude that project path for now.
  </Step>

  <Step title="Run the purge">
    Once you've reviewed the dry-run list and are confident in the selections, run the actual purge. Use `--force` to skip the manual confirmation prompt.

    ```bash theme={null}
    toolkit clean purge ~/projects --force
    ```

    Toolkit deletes each directory and prints a running total as it frees space:

    ```
    Purging ~/projects...

    ✓ Removed ~/projects/old-landing/node_modules        (847 MB freed)
    ✓ Removed ~/projects/data-pipeline/.venv             (220 MB freed)
    ✓ Removed ~/projects/ml-experiment/venv              (1.1 GB freed)
    ✓ Removed ~/projects/api-v1/node_modules             (312 MB freed)
    ✓ Removed ~/projects/dashboard/node_modules          (640 MB freed)

    Done. Total freed: 3.12 GB
    ```
  </Step>

  <Step title="Verify the cleanup">
    Run the scan one more time to confirm all targeted directories have been removed:

    ```bash theme={null}
    toolkit clean scan ~/projects
    ```

    If the purge was successful, you should see an empty results table or a significantly reduced list — confirming that the space has been reclaimed.
  </Step>
</Steps>

## Orphan Detection

<Info>
  Toolkit automatically marks an environment as **orphaned** when it cannot find a recognized project manifest in the same directory. The following manifest files are used as indicators of an active project:

  * **Node.js:** `package.json`
  * **Python:** `pyproject.toml` or `requirements.txt`

  If none of these files exist alongside the `node_modules` or virtual environment folder, Toolkit flags the directory as an orphan — a strong signal that the project is abandoned and the environment is safe to remove.
</Info>

## Adjusting Scan Depth

By default, Toolkit recurses up to **5 directory levels** deep when scanning. For large or deeply nested project trees, you can tune this with the `--depth` flag:

```bash theme={null}
toolkit clean scan ~/projects --depth 3
```

A lower depth value speeds up the scan but may miss environments buried deeper in your directory structure. A higher depth is more thorough but takes longer on large trees.

| Depth        | Use Case                                       |
| :----------- | :--------------------------------------------- |
| `--depth 2`  | Flat project layout, fast scan                 |
| `--depth 5`  | Default — balanced depth for typical monorepos |
| `--depth 10` | Deeply nested workspaces or nested monorepos   |

## Automating Cleanup

<Tip>
  Use `toolkit clean scan --json` to pipe structured disk reports into CI/CD pipelines or custom monitoring scripts. The JSON output includes a `targets` array with per-directory metadata and a top-level `totalSize` field you can threshold against.

  ```bash theme={null}
  toolkit clean scan ~/projects --json | your-monitoring-script
  ```

  This lets you alert on disk usage, generate weekly reports, or trigger automated cleanups as part of your infrastructure workflows.
</Tip>