<h2 id="what-it-is">What it is</h2>
<p>A single-file Python script that walks a macOS home directory and reports
where disk space is going. It prints a report; it never deletes anything.</p>
<p>Source: <code>apps/macos-utils/cleanup-scan.py</code>.</p>
<h2 id="run-it">Run it</h2>
<pre><code class="language-bash">python3 apps/macos-utils/cleanup-scan.py
</code></pre>
<p>No dependencies beyond the stdlib. Colors are auto-disabled when stdout
is not a TTY.</p>
<h2 id="what-it-scans">What it scans</h2>
<ul>
<li>System and user caches (<code>~/Library/Caches</code>, <code>/Library/Caches</code>)</li>
<li>Homebrew cache</li>
<li>npm / yarn / pnpm stores</li>
<li>pip caches and wheel cache</li>
<li>Docker images, containers, volumes, build cache</li>
<li>Xcode DerivedData, CoreSimulator devices, archives</li>
<li>Downloads older than 30 days</li>
<li>Trash</li>
<li>Log files</li>
<li>20 largest files under <code>$HOME</code> (skipping <code>.git</code>, <code>node_modules</code>, <code>.venv</code>, <code>Library</code>, etc.)</li>
<li><code>node_modules</code> directories</li>
<li>Python virtualenvs (<code>.venv</code>, <code>venv</code>)</li>
<li><code>~/Library/Application Support</code> subdirs</li>
</ul>
<p>Each section shows reclaimable size and the command you would run to
clear it — but running that command is left to you.</p>
<h2 id="safety">Safety</h2>
<p><code>cleanup-scan.py</code> has no delete path. It calculates sizes via <code>os.walk</code>
and <code>os.path.getsize</code>; <code>shutil</code> is only used for <code>shutil.which</code>. External
tools (<code>docker system df</code>, <code>brew --cache</code>) are invoked in read-only mode.
Re-running it is free.</p>


macOS storage cleanup scanner. Reports reclaimable space across caches, Docker, Xcode, node_modules, venvs, and large files. Report-only — never deletes.

Kyle Pericak

"It works in my environment"

cleanup-scan

What it is

Run it

What it scans

Safety