<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:content="http://purl.org/rss/1.0/modules/content/"
     xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>Disk space · Loosely Decoupled</title>
    <link>https://looselydecoupled.com/topics/disk-space/</link>
    <description>These guides find what fills a developer&#39;s disk on a Mac or a Windows PC, measure what each cleanup gave back, and free it one tool at a time.</description>
    <language>en-us</language>
    
    <copyright>© 2026 Emmanuel Tsouris</copyright>
    <lastBuildDate>Fri, 30 Oct 2026 00:00:00 +0000</lastBuildDate>
    <atom:link href="https://looselydecoupled.com/topics/disk-space/index.xml" rel="self" type="application/rss+xml" />
    
    <item>
      <title>How to Find What&#39;s Taking Up Space on Your C: Drive with PowerShell</title>
      <link>https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/</link>
      <guid isPermaLink="true">https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/</guid>
      <pubDate>Fri, 30 Oct 2026 00:00:00 +0000</pubDate>
      <dc:creator>Emmanuel Tsouris</dc:creator>
      <category>Disk space</category>
      <category>PowerShell</category>
      
      <description>You finish with each large C: folder matched to its owner, whether an AI model folder, a package cache or the hibernation file, and to the cleanup it needs.</description>
      <content:encoded><![CDATA[<div class="answer" data-answer="true">
  <p class="answer__label" data-pagefind-ignore>TL;DR</p>
  <p>Record the free space, then size the folders one level at a time until a directory belongs to one tool. That tells you which cleanup you need. Clean it with that tool&rsquo;s own command where it has one, never by deleting files inside a cache a tool manages. Then record the free space again, because a cleanup&rsquo;s own report isn&rsquo;t what the disk got back.</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">PS&gt; </span><span class="console__token">Get-Volume</span> <span class="console__token">-DriveLetter</span> <span class="console__token">C</span> <span class="console__token">|</span> <span class="console__token">Select-Object</span> <span class="console__token">SizeRemaining,</span> <span class="console__token">Size</span>
</span><span class="line"><span class="prompt">PS&gt; </span><span class="console__token">Get-ChildItem</span> <span class="console__token">-LiteralPath</span> <span class="console__token">$env:USERPROFILE</span> <span class="console__token">-Force</span> <span class="console__token">-Directory</span> <span class="console__token">|</span> <span class="console__token">ForEach-Object</span> <span class="console__token">{</span> <span class="console__token">[pscustomobject]@{</span> <span class="console__token">Name</span> <span class="console__token">=</span> <span class="console__token">$_.Name;</span> <span class="console__token">GiB</span> <span class="console__token">=</span> <span class="console__token">[math]::Round((Get-ChildItem</span> <span class="console__token">-LiteralPath</span> <span class="console__token">$_.FullName</span> <span class="console__token">-Recurse</span> <span class="console__token">-File</span> <span class="console__token">-Force</span> <span class="console__token">-ErrorAction</span> <span class="console__token">SilentlyContinue</span> <span class="console__token">|</span> <span class="console__token">Measure-Object</span> <span class="console__token">Length</span> <span class="console__token">-Sum).Sum</span> <span class="console__token">/</span> <span class="console__token">1GB,</span> <span class="console__token">2)</span> <span class="console__token">}</span> <span class="console__token">}</span> <span class="console__token">|</span> <span class="console__token">Sort-Object</span> <span class="console__token">GiB</span> <span class="console__token">-Descending</span> <span class="console__token">|</span> <span class="console__token">Select-Object</span> <span class="console__token">-First</span> <span class="console__token">10</span></span></code></pre>
    </div>
  </div></div>
</div>

<p>My Windows 10 PC had 586.4 GB free on a 999.0 GB disk, so the disk wasn&rsquo;t full and nothing was urgent. I measured it anyway. I use it for ComfyUI and Hugging Face models, Steam games and development, and I wanted to know what was there before it became a problem. The largest folder in my user profile was Documents, at 75.86 GiB. Nearly all of it was ComfyUI, and most of that was model checkpoints. Which directory is largest on your PC depends on what you run. The <a href="https://looselydecoupled.com/series/developer-windows-disk-cleanup/">series</a> covers each cause. This is the Windows counterpart of the Mac series, built from readings I took on this PC. The Mac version of this article is <a href="https://looselydecoupled.com/mac-disk-full-developer-caches/">What&rsquo;s Taking Up All the Space on My Developer Mac?</a>.</p>
<h2 id="record-the-free-space-before-you-start">Record the free space before you start<a class="heading-anchor" href="https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/#record-the-free-space-before-you-start"
     aria-label="Link to section: Record the free space before you start" data-pagefind-ignore></a>
</h2>
<p>You check a cleanup by comparing two readings, so take the first one now. <code>Get-Volume</code> reads the volume and changes nothing. C: is the drive Windows lives on; use the letter of the drive you are sizing up:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">PS&gt; </span><span class="console__token">Get-Volume</span> <span class="console__token">-DriveLetter</span> <span class="console__token">C</span> <span class="console__token">|</span> <span class="console__token">Select-Object</span> <span class="console__token">SizeRemaining,</span> <span class="console__token">Size</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line">
</span><span class="line"><span class="console__token">SizeRemaining</span>          <span class="console__token">Size</span>
</span><span class="line"><span class="console__token">-------------</span>          <span class="console__token">----</span>
</span><span class="line"> <span class="console__token">586395574272</span>  <span class="console__token">999002918912</span></span></code></pre>
    </div>
  </div></div><div class="tested" id="tested">
  <p class="label label--seam">Tested with</p><dl class="tested__rows">
    <div class="tested__row"><dt>Windows</dt> <dd>10 Pro 22H2 (10.0.19045), PowerShell 7</dd></div>
    <div class="tested__row"><dt>Date</dt> <dd>November 2026</dd></div>
  </dl>
</div>
<p>Both columns are bytes. Take the reading when the PC is quiet: no update installing, no application downloading, nothing you started still writing. I took this one with no ComfyUI or Python process running. A PC keeps writing while you work, so free space can move between readings. On this one, two readings taken a minute after a first one were each less than 2 MB below it.</p>
<p>Use one unit for every reading. <code>Get-Volume</code> reports bytes, and 586.4 GB and 546.1 GiB are the same free space. In this article, volume figures are GB and folder sizes are GiB (1024 to the third power, which is what <code>1GB</code> means in PowerShell).</p>
<h2 id="find-whats-taking-up-space-with-powershell">Find what&rsquo;s taking up space with PowerShell<a class="heading-anchor" href="https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/#find-whats-taking-up-space-with-powershell"
     aria-label="Link to section: Find what’s taking up space with PowerShell" data-pagefind-ignore></a>
</h2>
<p>Each command here reads sizes and changes nothing. A folder that PowerShell can&rsquo;t read adds nothing to its total, so a size can be too low. The function in step 2 counts those paths instead of hiding them. A size can also be too high: a hard link is a second directory entry for the same file data. PowerShell counts that file in full in every folder that has an entry for it, so two folders can share the same bytes and both report them.</p>
<!-- style-check: procedure -->
<ol>
<li>
<p>List the size of each folder in your user profile. This is the command from the answer:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">PS&gt; </span><span class="console__token">Get-ChildItem</span> <span class="console__token">-LiteralPath</span> <span class="console__token">$env:USERPROFILE</span> <span class="console__token">-Force</span> <span class="console__token">-Directory</span> <span class="console__token">|</span> <span class="console__token">ForEach-Object</span> <span class="console__token">{</span> <span class="console__token">[pscustomobject]@{</span> <span class="console__token">Name</span> <span class="console__token">=</span> <span class="console__token">$_.Name;</span> <span class="console__token">GiB</span> <span class="console__token">=</span> <span class="console__token">[math]::Round((Get-ChildItem</span> <span class="console__token">-LiteralPath</span> <span class="console__token">$_.FullName</span> <span class="console__token">-Recurse</span> <span class="console__token">-File</span> <span class="console__token">-Force</span> <span class="console__token">-ErrorAction</span> <span class="console__token">SilentlyContinue</span> <span class="console__token">|</span> <span class="console__token">Measure-Object</span> <span class="console__token">Length</span> <span class="console__token">-Sum).Sum</span> <span class="console__token">/</span> <span class="console__token">1GB,</span> <span class="console__token">2)</span> <span class="console__token">}</span> <span class="console__token">}</span> <span class="console__token">|</span> <span class="console__token">Sort-Object</span> <span class="console__token">GiB</span> <span class="console__token">-Descending</span> <span class="console__token">|</span> <span class="console__token">Select-Object</span> <span class="console__token">-First</span> <span class="console__token">10</span></span></code></pre>
    </div>
  </div></div><p>On the PC measured here, an inventory of the same folders on 2026-11-01 put <code>Documents</code> first at 75.86 GiB, then <code>AppData</code> at 31.89 GiB, <code>.cache</code> at 6.14 GiB and <code>OneDrive</code> at 5.45 GiB.</p>
</li>
<li>
<p>Define a function that sizes one level of any path, folders and files together, and counts what it could not read. Then run it on the largest folder, and on the largest folder inside that, until one tool owns the directory:</p>
<div class="code-block" data-copyable data-copy-label="PowerShell">
  <div class="code-block__head"><span class="code-block__lang">PowerShell</span>
  </div>
  <div class="code-block__scroll">
    <div data-copy-source><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-powershell" data-lang="powershell"><span class="line"><span class="cl"><span class="nv">$script:unread</span> <span class="p">=</span> <span class="mf">0</span>
</span></span><span class="line"><span class="cl"><span class="kd">function</span><span class="w"> </span><span class="nb">Get-FolderSize($root</span><span class="p">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nb">Get-ChildItem</span> <span class="n">-LiteralPath</span> <span class="nv">$root</span> <span class="n">-Force</span> <span class="p">|</span> <span class="nb">ForEach-Object</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nv">$e</span> <span class="p">=</span> <span class="vm">$null</span>
</span></span><span class="line"><span class="cl">    <span class="nv">$bytes</span> <span class="p">=</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$_</span><span class="p">.</span><span class="n">PSIsContainer</span><span class="p">)</span> <span class="p">{</span> <span class="p">(</span><span class="nb">Get-ChildItem</span> <span class="n">-LiteralPath</span> <span class="nv">$_</span><span class="p">.</span><span class="py">FullName</span> <span class="n">-Recurse</span> <span class="o">-File</span> <span class="n">-Force</span> <span class="n">-ErrorAction</span> <span class="n">SilentlyContinue</span> <span class="n">-ErrorVariable</span> <span class="n">e</span> <span class="p">|</span> <span class="nb">Measure-Object</span> <span class="n">Length</span> <span class="n">-Sum</span><span class="p">).</span><span class="py">Sum</span> <span class="p">}</span> <span class="k">else</span> <span class="p">{</span> <span class="nv">$_</span><span class="p">.</span><span class="py">Length</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="nv">$script:unread</span> <span class="p">+=</span> <span class="nv">$e</span><span class="p">.</span><span class="py">Count</span>
</span></span><span class="line"><span class="cl">    <span class="p">[</span><span class="no">pscustomobject</span><span class="p">]</span><span class="vm">@</span><span class="p">{</span> <span class="n">Name</span> <span class="p">=</span> <span class="nv">$_</span><span class="p">.</span><span class="n">Name</span><span class="p">;</span> <span class="n">GiB</span> <span class="p">=</span> <span class="p">[</span><span class="no">math</span><span class="p">]::</span><span class="n">Round</span><span class="p">(</span><span class="nv">$bytes</span> <span class="p">/</span> <span class="mf">1</span><span class="p">GB,</span> <span class="mf">2</span><span class="p">)</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span> <span class="p">|</span> <span class="nb">Sort-Object</span> <span class="n">GiB</span> <span class="n">-Descending</span> <span class="p">|</span> <span class="nb">Select-Object</span> <span class="n">-First</span> <span class="mf">8</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
  </div>
</div><div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">PS&gt; </span><span class="console__token">Get-FolderSize</span> <span class="console__token">&#34;$env:USERPROFILE\Documents&#34;</span>
</span><span class="line"><span class="prompt">PS&gt; </span><span class="console__token">&#34;$script:unread</span> <span class="console__token">paths</span> <span class="console__token">could</span> <span class="console__token">not</span> <span class="console__token">be</span> <span class="console__token">read&#34;</span></span></code></pre>
    </div>
  </div></div><p>Repeat <code>Get-FolderSize</code> on the largest entry it lists. On this PC that was <code>Documents\ComfyUI</code>, where the <code>models</code> folder holds the checkpoints, text encoders and LoRA files.</p>
</li>
<li>
<p>Check the hidden places, even if they didn&rsquo;t top the first list. <code>AppData\Local</code> holds the caches that tools keep for themselves. The files at the root of C: include the ones Windows manages, such as <code>hiberfil.sys</code>:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">PS&gt; </span><span class="console__token">Get-FolderSize</span> <span class="console__token">&#34;$env:USERPROFILE\AppData\Local&#34;</span>
</span><span class="line"><span class="prompt">PS&gt; </span><span class="console__token">Get-ChildItem</span> <span class="console__token">C:\</span> <span class="console__token">-Force</span> <span class="console__token">-File</span> <span class="console__token">-ErrorAction</span> <span class="console__token">SilentlyContinue</span> <span class="console__token">|</span> <span class="console__token">Select-Object</span> <span class="console__token">Name,</span> <span class="console__token">@{</span> <span class="console__token">n</span> <span class="console__token">=</span> <span class="console__token">&#39;GiB&#39;;</span> <span class="console__token">e</span> <span class="console__token">=</span> <span class="console__token">{</span> <span class="console__token">[math]::Round($_.Length</span> <span class="console__token">/</span> <span class="console__token">1GB,</span> <span class="console__token">2)</span> <span class="console__token">}</span> <span class="console__token">}</span> <span class="console__token">|</span> <span class="console__token">Sort-Object</span> <span class="console__token">GiB</span> <span class="console__token">-Descending</span></span></code></pre>
    </div>
  </div></div><p>On this PC, the 2026-11-01 inventory read <code>hiberfil.sys</code> at 6.38 GiB and <code>pagefile.sys</code> at 2.82 GiB. <code>pagefile.sys</code> changes size; it read 2.38 GiB on 2026-10-30.</p>
</li>
<li>
<p>For a package manager, ask the tool where its cache is rather than assuming a path. Each command runs only when the tool is on <code>PATH</code>; if PowerShell can&rsquo;t find it, see <a href="https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/#cache-command-not-found">Cache command not found</a>:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">PS&gt; </span><span class="console__token">uv</span> <span class="console__token">cache</span> <span class="console__token">dir</span>
</span><span class="line"><span class="prompt">PS&gt; </span><span class="console__token">python</span> <span class="console__token">-m</span> <span class="console__token">pip</span> <span class="console__token">cache</span> <span class="console__token">dir</span></span></code></pre>
    </div>
  </div></div></li>
</ol>
<!-- style-check: end procedure -->
<p>The sizes in the next section come from a separate inventory of known locations on the same PC. It doesn&rsquo;t drill down level by level, so use it as a checklist of places to look, not as a replacement for the steps earlier.</p>
<h2 id="match-the-directory-to-its-cause">Match the directory to its cause<a class="heading-anchor" href="https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/#match-the-directory-to-its-cause"
     aria-label="Link to section: Match the directory to its cause" data-pagefind-ignore></a>
</h2>
<p>This table lists the large directories on this PC and the article in the series that covers each one:</p>
<div class="table-wrap" data-scrollable data-label="Table: Directory and what fills it">
  <table>
    <thead>
      <tr><th scope="col">Directory and what fills it</th><th class="align-right" scope="col">Size here</th><th scope="col">Covered in</th></tr>
    </thead>
    <tbody>
      <tr><td><code>Documents\ComfyUI</code><br>Model checkpoints (54.65 GiB), text encoders, LoRA files, and one virtual environment</td><td class="align-right">75.86 GiB</td><td>AI models</td></tr>
      <tr><td><code>AppData</code><br>Per-user application data, including the two caches below</td><td class="align-right">31.89 GiB</td><td>Hidden caches</td></tr>
      <tr><td><code>.cache\huggingface</code><br>Hugging Face model cache; the newest file is from 2023</td><td class="align-right">5.27 GiB</td><td>AI models</td></tr>
      <tr><td><code>AppData\Local\uv</code><br>The uv cache of ComfyUI Desktop&rsquo;s bundled uv; at least one of its files is hard-linked into the ComfyUI virtual environment</td><td class="align-right">4.56 GiB</td><td>Hidden caches</td></tr>
      <tr><td><code>AppData\Local\pip</code><br>The pip cache of a Python 3.10 since uninstalled</td><td class="align-right">2.72 GiB</td><td>Hidden caches</td></tr>
      <tr><td><code>C:\hiberfil.sys</code><br>The hibernation file</td><td class="align-right">6.38 GiB</td><td>Windows itself</td></tr>
      <tr><td>Component store, <code>WinSxS</code><br>Windows system components; DISM reports the real size and needs an elevated session; read two days earlier</td><td class="align-right">11.76 GB</td><td>Windows itself</td></tr>
      <tr><td><code>C:\Windows\SoftwareDistribution\Download</code><br>Windows Update downloads</td><td class="align-right">1.15 GiB</td><td>Windows itself</td></tr>
      <tr><td><code>C:\Windows\Installer</code><br>Installer files that Windows keeps</td><td class="align-right">1.07 GiB</td><td>Windows itself</td></tr>
      <tr><td><code>C:\$Recycle.Bin</code><br>Held nine crash dumps (178.8 MB, 0.17 GiB) on 2026-10-30 before it was emptied, and 129 bytes right after; the size here is the later inventory&rsquo;s reading</td><td class="align-right">0.02 GiB</td><td>Crash dumps</td></tr>
      <tr><td><code>C:\ProgramData\NVIDIA Corporation\Downloader</code><br>NVIDIA app downloads</td><td class="align-right">2.41 GiB</td><td>Games and launchers</td></tr>
      <tr><td>Steam library<br>Mostly on another drive; 0.62 GiB on C:, with shader and web caches under 1 GiB each</td><td class="align-right">0.62 GiB on C:</td><td>Games and launchers</td></tr>
    </tbody>
  </table>
</div>
<p>The rows overlap. Of the 3.96 GiB in the ComfyUI virtual environment&rsquo;s <code>site-packages</code>, 3.87 GiB are in files with more than one hard link. On the one file I checked, the other link was in the uv cache. A hard-linked file counts in full in both the <code>Documents\ComfyUI</code> row and the <code>uv</code> row, so clearing the uv cache can free much less than its folder total. The article on hidden caches measures how much.</p>
<p>The numbers move between runs. One ComfyUI update grew the uv cache from 3.55 to 4.56 GiB. Quote the reading you took, not one from this table.</p>
<p>Some directories stay whatever their size:</p>
<ul>
<li>Model files you still use. A checkpoint isn&rsquo;t a cache.</li>
<li>A Steam library. It holds installed games, not leftovers.</li>
<li><code>OneDrive</code> and <code>iCloudDrive</code>. Both sync with online storage. <code>OneDrive</code> is a reparse point here: its files can be placeholders for files stored online, so neither folder&rsquo;s size is a cleanup target.</li>
<li><code>C:\Windows\Installer</code> and the component store. Do not delete files from either by hand. Windows manages both, and the article on what Windows keeps for itself covers the commands that do.</li>
</ul>
<p>Docker and WSL aren&rsquo;t covered in this series. Docker Desktop and any WSL distribution are absent on this PC (only Windows&rsquo; built-in <code>wsl.exe</code> stub is present), so this article has no readings for them.</p>
<h2 id="record-the-free-space-again">Record the free space again<a class="heading-anchor" href="https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/#record-the-free-space-again"
     aria-label="Link to section: Record the free space again" data-pagefind-ignore></a>
</h2>
<p>Run the same command you started with:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">PS&gt; </span><span class="console__token">Get-Volume</span> <span class="console__token">-DriveLetter</span> <span class="console__token">C</span> <span class="console__token">|</span> <span class="console__token">Select-Object</span> <span class="console__token">SizeRemaining,</span> <span class="console__token">Size</span></span></code></pre>
    </div>
  </div></div><p>Compare the new figure with the first reading, not with the size of what you removed; only the volume&rsquo;s figure says what the disk got back. <a href="https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/#emptying-the-bin-freed-no-space">Emptying the bin freed no space</a> shows a cleanup where the two differed.</p>
<h2 id="do-this-with-a-coding-agent">Do this with a coding agent<a class="heading-anchor" href="https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/#do-this-with-a-coding-agent"
     aria-label="Link to section: Do this with a coding agent" data-pagefind-ignore></a>
</h2>
<p>Paste this prompt into your own local coding agent. It measures and reports, and it changes nothing:</p>
<div class="code-block" data-copyable data-copy-label="Text">
  <div class="code-block__head"><span class="code-block__lang">Text</span>
  </div>
  <div class="code-block__scroll">
    <div data-copy-source><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Find what is taking up space on this Windows PC&#39;s system drive. Measure and
</span></span><span class="line"><span class="cl">report only. Delete, move or clean nothing, and stop and ask me before any
</span></span><span class="line"><span class="cl">change. Use PowerShell. Do not run elevated commands unless I ask. Do not
</span></span><span class="line"><span class="cl">open, move or change files in model folders, game libraries or the Hugging Face
</span></span><span class="line"><span class="cl">cache. You may size them, but do not suggest deleting their contents.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">1. Record free space on C: first with Get-Volume -DriveLetter C
</span></span><span class="line"><span class="cl">   (SizeRemaining, Size). Say that the figures are bytes, and use one unit for
</span></span><span class="line"><span class="cl">   every size you report.
</span></span><span class="line"><span class="cl">2. List the size of each folder in my user profile, then do the same on the
</span></span><span class="line"><span class="cl">   largest folder inside it, one level at a time, until each large directory
</span></span><span class="line"><span class="cl">   belongs to one tool. In this step do not recurse into ComfyUI, models,
</span></span><span class="line"><span class="cl">   checkpoints, .cache\huggingface, Steam or any game library; report each by
</span></span><span class="line"><span class="cl">   size as a whole and map it to AI models or games by name.
</span></span><span class="line"><span class="cl">   Also check AppData\Local and the files at the root of C:. Count the paths
</span></span><span class="line"><span class="cl">   you could not read, and say that a size can be too low because of them, or
</span></span><span class="line"><span class="cl">   too high because a hard-linked file counts in every folder that links it.
</span></span><span class="line"><span class="cl">   Ask package managers for their cache paths (for example uv cache dir or
</span></span><span class="line"><span class="cl">   python -m pip cache dir) instead of assuming them, and say so if a tool is
</span></span><span class="line"><span class="cl">   not on PATH.
</span></span><span class="line"><span class="cl">3. For each measured directory over 1 GiB, report a table with its size, which
</span></span><span class="line"><span class="cl">   tool owns it, what fills it, and that tool&#39;s own cleanup command if it has
</span></span><span class="line"><span class="cl">   one.
</span></span><span class="line"><span class="cl">4. Mark anything that is in use or holds work: a running application that has
</span></span><span class="line"><span class="cl">   files open there, an update in progress, a game launcher, a project with
</span></span><span class="line"><span class="cl">   uncommitted changes. Say what would be lost if each were removed.
</span></span><span class="line"><span class="cl">5. Treat OneDrive and iCloud folders as placeholders for online files and do
</span></span><span class="line"><span class="cl">   not scan them for cleanup.
</span></span><span class="line"><span class="cl">6. End by naming which of these applies to each large folder: crash dumps and
</span></span><span class="line"><span class="cl">   error reports, AI models, hidden uv and pip caches, games and launchers, or
</span></span><span class="line"><span class="cl">   what Windows keeps for itself.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">Then stop and wait. I will choose what to clean.</span></span></code></pre></div></div>
  </div>
</div><h2 id="common-failures">Common failures<a class="heading-anchor" href="https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/#common-failures"
     aria-label="Link to section: Common failures" data-pagefind-ignore></a>
</h2>
<h3 id="emptying-the-bin-freed-no-space">Emptying the bin freed no space<a class="heading-anchor" href="https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/#emptying-the-bin-freed-no-space"
     aria-label="Link to section: Emptying the bin freed no space" data-pagefind-ignore></a>
</h3>
<p>I emptied the bin with <code>Clear-RecycleBin -DriveLetter C -Force</code>. It held nine crash dumps, 178.8 MB. <code>Get-Volume</code> read 581,462,724,608 bytes before and 581,462,724,608 after. One minute later, two more readings were each less than 2 MB below the first, and the <code>$Recycle.Bin</code> folder was down to 129 bytes. Free space didn&rsquo;t rise.</p>
<p>The cause isn&rsquo;t established, and the evidence points away from restore points. In a controlled test, I created a 1 GiB file, deleted it and read <code>Get-Volume</code>, with and without a shadow copy newer than the file, and the space came back at once both times. The dumps are gone, so the original run can&rsquo;t be repeated.</p>
<p>Do not delete shadow copies to make the number move. They are the restore points System Restore uses.</p>
<h3 id="cache-command-not-found">Cache command not found<a class="heading-anchor" href="https://looselydecoupled.com/find-whats-taking-up-space-c-drive-windows/#cache-command-not-found"
     aria-label="Link to section: Cache command not found" data-pagefind-ignore></a>
</h3>
<p>On this PC, neither <code>uv</code> nor <code>python</code> is on <code>PATH</code>, the list of folders PowerShell searches for a command, so neither command can find a tool to run. The cache folders exist all the same: <code>AppData\Local\uv</code> at 4.56 GiB and <code>AppData\Local\pip</code> at 2.72 GiB. A cache can belong to a copy of a tool that an application bundles, or to a tool you&rsquo;ve since uninstalled. Here there&rsquo;s one of each. The uv cache belongs to the copy of uv that ComfyUI Desktop bundles, which its log shows running <code>uv pip install --dry-run</code> at the start of an update, and whose cache gained files during that update. The pip cache belongs to a Python 3.10 installed in 2022 and since uninstalled; its newest file is from January 2023, and nothing on the PC uses it. Size the folder with <code>Get-FolderSize</code>, as in step 2, and treat the owner as unconfirmed until you find the tool that wrote it.</p>
]]></content:encoded>
    </item>
    
    <item>
      <title>Why Docker.raw Is Huge on a Mac, and How to Get Its Space Back</title>
      <link>https://looselydecoupled.com/docker-desktop-disk-space-mac/</link>
      <guid isPermaLink="true">https://looselydecoupled.com/docker-desktop-disk-space-mac/</guid>
      <pubDate>Tue, 20 Oct 2026 00:00:00 +0000</pubDate>
      <dc:creator>Emmanuel Tsouris</dc:creator>
      <category>Disk space</category>
      <category>Docker</category>
      
      <description>Get the space in Docker.raw back on a Mac by pruning images no container uses, keeping the volumes that hold app data and the images stopped containers need.</description>
      <content:encoded><![CDATA[<div class="answer" data-answer="true">
  <p class="answer__label" data-pagefind-ignore>TL;DR</p>
  <p><code>Docker.raw</code> is a sparse file. The <code>ls</code> command reports its maximum size. That size is the disk limit shown in Docker Desktop&rsquo;s Settings &gt; Resources &gt; Advanced, and it was 1.0T in the test. The <code>du</code> command reports what the file occupies. In the test, that was 15G, then 8.6G after pruning. To get space back, run <code>docker image prune -a</code>. That command removes every image that no container uses. Plain <code>docker image prune</code> removes only dangling (untagged) images. Keep the volumes, because a volume holds an app&rsquo;s data. The space returns to the Mac minutes later, not at once. Before you decide the prune did nothing, wait several minutes. Then check <code>df</code> and <code>du</code> again. In the test runs, quitting, reopening or updating Docker Desktop freed nothing more.</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">ls</span> <span class="console__token">-lh</span> <span class="console__token">~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-h</span> <span class="console__token">~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">docker</span> <span class="console__token">system</span> <span class="console__token">df</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">docker</span> <span class="console__token">image</span> <span class="console__token">prune</span> <span class="console__token">-a</span></span></code></pre>
    </div>
  </div></div>
</div>

<p>I went looking for what was filling my Mac, and Docker&rsquo;s folder sat near the top of the list. <code>ls</code> read <code>Docker.raw</code> as 1.0T, which can&rsquo;t be what it occupies. I measured it, pruned, and watched how much of the space came back and when. This page is part of a series on <a href="https://looselydecoupled.com/series/developer-mac-disk-cleanup/">cleaning up a developer Mac&rsquo;s disk</a>. If you haven&rsquo;t yet found out that Docker is what fills your disk, <a href="https://looselydecoupled.com/mac-disk-full-developer-caches/">finding what is taking up the space</a> comes first; you don&rsquo;t need it to follow the steps here.</p>
<div class="tested" id="tested">
  <p class="label label--seam">Tested with</p><dl class="tested__rows">
    <div class="tested__row"><dt>Docker Desktop</dt> <dd>4.95.0, then 4.96.0</dd></div>
    <div class="tested__row"><dt>Docker engine</dt> <dd>29.8.2, then 29.9.1</dd></div>
    <div class="tested__row"><dt>macOS</dt> <dd>27.0.1, Apple silicon, APFS</dd></div>
    <div class="tested__row"><dt>Date</dt> <dd>October 2026</dd></div>
  </dl>
</div>
<p>The first prune run below was on an earlier engine, 29.6.2, before Docker Desktop was updated.</p>
<h2 id="read-the-real-size-of-dockerraw">Read the real size of <code>Docker.raw</code><a class="heading-anchor" href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#read-the-real-size-of-dockerraw"
     aria-label="Link to section: Read the real size of Docker.raw" data-pagefind-ignore></a>
</h2>
<p>Docker Desktop keeps its Linux containers and images in one disk image file, <code>Docker.raw</code> (<a href="https://docs.docker.com/desktop/troubleshoot-and-support/faqs/macfaqs/" rel="external noopener" target="_blank">Docker&rsquo;s Mac FAQ<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>). Compare what <code>ls</code> and <code>du</code> say about it:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">ls</span> <span class="console__token">-lh</span> <span class="console__token">~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-h</span> <span class="console__token">~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw</span></span></code></pre>
    </div>
  </div></div><p><code>ls</code> printed 1.0T in both runs, and <code>du</code> printed 15G on one day and 14G on another (<code>du -h</code> shows GiB as G). The file is sparse: its maximum size is the disk limit, 1.0T here, and it occupies only the blocks that have been written. <code>du</code> counts those blocks, so it is the figure that matters. Write it down; it is your before number.</p>
<p>Also write down the free space the Mac reports, because that is what the prune is for:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">df</span> <span class="console__token">-h</span> <span class="console__token">/</span></span></code></pre>
    </div>
  </div></div><h2 id="see-what-docker-says-it-can-reclaim">See what Docker says it can reclaim<a class="heading-anchor" href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#see-what-docker-says-it-can-reclaim"
     aria-label="Link to section: See what Docker says it can reclaim" data-pagefind-ignore></a>
</h2>
<p>Docker Desktop has to be running for these commands. Start it with <code>open -a Docker</code> and wait until <code>docker info</code> succeeds.</p>
<p><code>docker system df</code> prints how much each kind of object uses and how much of it Docker thinks it could reclaim:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">docker</span> <span class="console__token">system</span> <span class="console__token">df</span></span></code></pre>
    </div>
  </div></div><p>On October 16 it showed 7 images, 1 of them active, 13.61GB in total with 4.213GB (30%) reclaimable. On October 19 it showed 2 images, 12.06GB, with 5.548GB (46%) reclaimable.</p>
<p>Docker has no dry-run option for the image prune that I found; its help text lists <code>--all</code>, <code>--filter</code> and <code>--force</code> only. To preview, list the images and the containers, including stopped ones, and compare them by hand:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">docker</span> <span class="console__token">images</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">docker</span> <span class="console__token">ps</span> <span class="console__token">-a</span></span></code></pre>
    </div>
  </div></div><p>An image that no container in the second list uses is a candidate for <code>docker image prune -a</code>. An image that a stopped container uses is not.</p>
<h2 id="prune-images-with-no-container">Prune images with no container<a class="heading-anchor" href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#prune-images-with-no-container"
     aria-label="Link to section: Prune images with no container" data-pagefind-ignore></a>
</h2>
<p>Two commands look alike, and they remove different sets. According to <code>docker image prune --help</code>, <code>-a</code> removes all unused images, which is more than the dangling ones. Plain <code>docker image prune</code> removes only dangling images, meaning untagged ones, so a tagged image that no container uses stays unless you pass <code>-a</code>.</p>
<div class="admonition admonition--warning" role="note">
  <p class="admonition__label">
    <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#i-triangle-alert"/></svg>
    <span>Warning</span>
  </p>
  <p><code>docker image prune -a</code> deletes every image that no container uses, named or not. Pulling a registry image again takes a download. An image you built locally and never pushed is gone for good and has to be rebuilt. The prune keeps images that a container uses and does not touch volumes.</p>
</div><div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">docker</span> <span class="console__token">image</span> <span class="console__token">prune</span> <span class="console__token">-a</span></span></code></pre>
    </div>
  </div></div><p>Without <code>-f</code>, Docker asks for confirmation first. On October 16 (run with <code>-f</code>) it removed the six images with no container and reported <code>Total reclaimed space: 7.104GB</code>. The images went from 13.61GB to 6.508GB. An image that a stopped container uses, that container and its volume stayed, because the container used the image.</p>
<p>I didn&rsquo;t run <code>docker volume prune</code> or <code>docker system prune</code>, and this page doesn&rsquo;t either. A volume holds an app&rsquo;s data, and <code>docker system df</code> showed one local volume of 1.408GB that I wanted to keep.</p>
<h2 id="prune-the-build-cache-with-all">Prune the build cache with &ndash;all<a class="heading-anchor" href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#prune-the-build-cache-with-all"
     aria-label="Link to section: Prune the build cache with –all" data-pagefind-ignore></a>
</h2>
<p>This section rests on my recollection of a run on October 15, not on a terminal transcript, so treat the numbers as my report. Plain <code>docker builder prune</code> reported 24.58kB reclaimed. After <code>docker builder prune --all</code>, Docker reported a total of 7GB, and <code>docker system df</code> showed the build cache at 0B. <a href="https://docs.docker.com/reference/cli/docker/builder/prune/" rel="external noopener" target="_blank">Docker&rsquo;s reference for <code>docker builder prune</code><svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a> describes <code>--all</code> as removing all unused build cache, not only the dangling part. On Docker Desktop 4.96.0 the command runs as <code>docker buildx prune</code>, and its <code>--help</code> describes <code>--all</code> as &ldquo;Include internal/frontend images&rdquo; instead. Check <code>docker builder prune --help</code> on your version before you run it. Free space read 44Gi before it and 43Gi after, with no record of how long after; given how late the space came back on October 16, that reading was probably taken too soon, but I can&rsquo;t show it. I didn&rsquo;t re-run this one, so I can&rsquo;t tell you what the same commands report on your version.</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">docker</span> <span class="console__token">builder</span> <span class="console__token">prune</span> <span class="console__token">--all</span></span></code></pre>
    </div>
  </div></div><h2 id="wait-before-judging-the-result">Wait before judging the result<a class="heading-anchor" href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#wait-before-judging-the-result"
     aria-label="Link to section: Wait before judging the result" data-pagefind-ignore></a>
</h2>
<p>Free space did not move right after the prune. On October 16, the reading straight after was unchanged at 66,071,195,648 bytes, and <code>Docker.raw</code> still read 15G. Five minutes later free space was 73,278,255,104 bytes (up 7.2 GB) and <code>Docker.raw</code> read 8.6G. At 15 minutes both were unchanged from the five-minute reading.</p>
<p>On October 19, the second run, the space came back within a minute. Free space rose from 80.63 GB to 83.62 GB by the one-minute reading, and <code>Docker.raw</code> read 14G at the start and 8.6G from the one-minute reading on. I took no readings inside that first minute, so I can&rsquo;t say when it moved.</p>
<p><a href="https://docs.docker.com/desktop/troubleshoot-and-support/faqs/macfaqs/" rel="external noopener" target="_blank">Docker&rsquo;s documentation<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a> says the same thing: &ldquo;It might take a few minutes to reclaim space on the host.&rdquo; A <code>df</code> taken straight after the prune makes it look as if nothing happened. Wait, then read both again:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-h</span> <span class="console__token">~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span></span></code></pre>
    </div>
  </div></div><h2 id="check-the-reclaimed-figure-against-dockerraw">Check the reclaimed figure against <code>Docker.raw</code><a class="heading-anchor" href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#check-the-reclaimed-figure-against-dockerraw"
     aria-label="Link to section: Check the reclaimed figure against Docker.raw" data-pagefind-ignore></a>
</h2>
<p>Docker&rsquo;s printed total and the earlier estimate differed in one run and matched in the other:</p>
<div class="table-wrap" data-scrollable data-label="Table: Run">
  <table>
    <thead>
      <tr><th scope="col">Run</th><th scope="col"><code>docker system df</code> estimate</th><th scope="col">Prune reported</th><th scope="col"><code>Docker.raw</code> before, after</th></tr>
    </thead>
    <tbody>
      <tr><td>October 16</td><td>4.213GB</td><td>7.104GB (69% more)</td><td>15G, 8.6G</td></tr>
      <tr><td>October 19</td><td>5.548GB</td><td>5.548GB (equal)</td><td>14G, 8.6G</td></tr>
    </tbody>
  </table>
</div>
<p>On October 16 the printed 7.104GB came close to the 7.2 GB of free space the Mac gained. On October 19 it didn&rsquo;t: <code>Docker.raw</code> shrank by about 5.4G (about 5.8 GB) while free space rose about 3.0 GB. Other writes and frees on the Mac run at the same time, so free space moves less, or more, than the file does. Treat <code>Docker.raw</code> from <code>du</code>, and the free space after the wait, as the measure, and the printed total as approximate.</p>
<p>The listed image sizes also add up to more than the estimate. On October 16 the unused images&rsquo; listed sizes added to about 10 GB while Docker estimated 4.213GB reclaimable. Shared layers, which Docker stores once, are the likely cause; I did not check the SHARED SIZE column of <code>docker system df -v</code>.</p>
<h2 id="do-this-with-a-coding-agent">Do this with a coding agent<a class="heading-anchor" href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#do-this-with-a-coding-agent"
     aria-label="Link to section: Do this with a coding agent" data-pagefind-ignore></a>
</h2>
<p>Paste this prompt into your own local coding agent. It measures and reports, and it asks before anything is removed:</p>
<div class="code-block" data-copyable data-copy-label="Text">
  <div class="code-block__head"><span class="code-block__lang">Text</span>
  </div>
  <div class="code-block__scroll">
    <div data-copy-source><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Investigate Docker Desktop&#39;s disk use on this Mac. Measure and report only;
</span></span><span class="line"><span class="cl">change nothing yet.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">0. Docker Desktop has to be running. If it is not, start it with
</span></span><span class="line"><span class="cl">   open -a Docker and wait until docker info succeeds.
</span></span><span class="line"><span class="cl">1. Read Docker.raw two ways: ls -lh and du -h on
</span></span><span class="line"><span class="cl">   ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw.
</span></span><span class="line"><span class="cl">   Explain that ls shows the sparse maximum and du the real size.
</span></span><span class="line"><span class="cl">2. Report free space with diskutil info / (Container Free Space) and df -h /.
</span></span><span class="line"><span class="cl">3. Run docker system df and docker system df -v. Report each category&#39;s total
</span></span><span class="line"><span class="cl">   and reclaimable figure.
</span></span><span class="line"><span class="cl">4. List images that no container uses (compare docker images with docker ps -a,
</span></span><span class="line"><span class="cl">   including stopped containers), with each one&#39;s size. List the build cache
</span></span><span class="line"><span class="cl">   and its size. These two are the only removal candidates.
</span></span><span class="line"><span class="cl">5. Report every volume with its size. Never propose removing a volume, and do
</span></span><span class="line"><span class="cl">   not run docker volume prune or docker system prune.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">Then stop and wait for my confirmation. For images, remove only the ones I
</span></span><span class="line"><span class="cl">name, with docker image rm &lt;image&gt;. Run docker image prune -a -f only if I
</span></span><span class="line"><span class="cl">confirm removing every image on the list. For the build cache, run
</span></span><span class="line"><span class="cl">docker builder prune --all -f only after I confirm.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">After the prunes, wait a few minutes. The space can take that long to return.
</span></span><span class="line"><span class="cl">Then read du on Docker.raw and the free space again with the same commands, and
</span></span><span class="line"><span class="cl">compare the change against the total reclaimed space Docker printed. Say how far
</span></span><span class="line"><span class="cl">apart they are. Do not conclude the prune failed from a reading taken right
</span></span><span class="line"><span class="cl">after it.</span></span></code></pre></div></div>
  </div>
</div><h2 id="common-failures">Common failures<a class="heading-anchor" href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#common-failures"
     aria-label="Link to section: Common failures" data-pagefind-ignore></a>
</h2>
<h3 id="space-doesnt-come-back-after-you-quit-and-reopen-the-app">Space doesn&rsquo;t come back after you quit and reopen the app<a class="heading-anchor" href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#space-doesnt-come-back-after-you-quit-and-reopen-the-app"
     aria-label="Link to section: Space doesn’t come back after you quit and reopen the app" data-pagefind-ignore></a>
</h3>
<p>After the prune, <code>Docker.raw</code> read 8.6G before and after I quit and reopened Docker Desktop, on October 16 and again on October 19. Free space read 75.5 GB after the first reopening, but <code>Docker.raw</code> did not change, so that rise came from something else on the Mac.</p>
<h3 id="space-doesnt-come-back-after-you-update-the-app">Space doesn&rsquo;t come back after you update the app<a class="heading-anchor" href="https://looselydecoupled.com/docker-desktop-disk-space-mac/#space-doesnt-come-back-after-you-update-the-app"
     aria-label="Link to section: Space doesn’t come back after you update the app" data-pagefind-ignore></a>
</h3>
<p>I updated Docker Desktop on October 16 and, with <code>docker desktop update</code>, on October 20, and <code>Docker.raw</code> did not shrink either time: on October 20 it read 9,020,776 KB before and 9,020,796 KB after, 20 KB more. That is what I ran, on those versions; I make no claim about other releases.</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">docker</span> <span class="console__token">desktop</span> <span class="console__token">update</span> <span class="console__token">--check-only</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">docker</span> <span class="console__token">desktop</span> <span class="console__token">update</span> <span class="console__token">--quiet</span></span></code></pre>
    </div>
  </div></div>]]></content:encoded>
    </item>
    
    <item>
      <title>What Claude Code Leaves on Your Mac&#39;s Disk, and What Not to Delete</title>
      <link>https://looselydecoupled.com/claude-code-disk-space-worktrees/</link>
      <guid isPermaLink="true">https://looselydecoupled.com/claude-code-disk-space-worktrees/</guid>
      <pubDate>Tue, 20 Oct 2026 00:00:00 +0000</pubDate>
      <dc:creator>Emmanuel Tsouris</dc:creator>
      <category>Disk space</category>
      <category>Claude Code</category>
      
      <description>A read-only prompt makes Claude Code sort its scratch folders, worktrees and session history into in use, recoverable or unknown, with evidence for each.</description>
      <content:encoded><![CDATA[<div class="answer" data-answer="true">
  <p class="answer__label" data-pagefind-ignore>TL;DR</p>
  <p>Do not delete these folders yet. Claude Code&rsquo;s scratch checkouts, its worktrees and its <code>~/.claude</code> directory can hold unpushed commits and session history that exist nowhere else. Paste the prompt below into Claude Code in <a href="https://code.claude.com/docs/en/permission-modes#plan-mode" rel="external noopener" target="_blank">plan mode<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>. Claude Code measures every large item and every worktree and classifies each as IN USE, RECOVERABLE or UNKNOWN, with a line of evidence. Treat UNKNOWN as the default, and never treat a session transcript as recoverable, because a stopped session can be resumed from it. Read the limits before you act on RECOVERABLE, and approve removals one item at a time; the prompt tells Claude Code to delete nothing until you do.</p>

</div>

<p>On October 20 I measured the folders that Claude Code leaves behind on my Mac again. Size and age won&rsquo;t sort them: a folder that looks abandoned can hold the only copy of a commit, or a session you can still resume. This page is part of a series on <a href="https://looselydecoupled.com/series/developer-mac-disk-cleanup/">cleaning up a developer Mac&rsquo;s disk</a>. If you don&rsquo;t yet know that agents are what fills your disk, <a href="https://looselydecoupled.com/mac-disk-full-developer-caches/">finding what&rsquo;s taking up the space</a> comes first. If the space is a uv cache that agents filled through MCP servers, <a href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/">that has its own cleanup</a>.</p>
<div class="tested" id="tested">
  <p class="label label--seam">Tested with</p><dl class="tested__rows">
    <div class="tested__row"><dt>macOS</dt> <dd>27.0.1 (26A434), APFS, Claude Code=2.1.304</dd></div>
    <div class="tested__row"><dt>Date</dt> <dd>October 2026</dd></div>
  </dl>
</div>
<h2 id="run-the-prompt">Run the prompt<a class="heading-anchor" href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#run-the-prompt"
     aria-label="Link to section: Run the prompt" data-pagefind-ignore></a>
</h2>
<p>Paste this into Claude Code in <a href="https://code.claude.com/docs/en/permission-modes#plan-mode" rel="external noopener" target="_blank">plan mode<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>. Plan mode doesn&rsquo;t limit Bash to read-only commands on its own, and it writes a plan file of its own. The prompt&rsquo;s no-write rule is the guard, so watch the first tool calls; see <a href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#common-failures">Common failures</a>. I ran it in a fresh session started with <code>claude -p &quot;&lt;prompt&gt;&quot; --permission-mode plan</code>. A <code>-p</code> run is one-shot and ends after the report, so I haven&rsquo;t tested the prompt&rsquo;s approval step, which applies only in an interactive session.</p>
<div class="code-block" data-copyable data-copy-label="Text">
  <div class="code-block__head"><span class="code-block__lang">Text</span>
  </div>
  <div class="code-block__scroll">
    <div data-copy-source><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">You are helping me find out how much disk space my coding agents and their git worktrees are using, and which of it is safe to remove. Do not delete, move, or modify anything, and do not write any file, including a plan or notes file; answer in the chat only. Do not run any command that writes. Use the read-only form of git (git --no-optional-locks status) because plain git status can rewrite the index. If I want something removed, you will propose it and wait for my approval.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">1. Measure. Report the size of: (a) the agent temporary scratch area (for tools that use a per-session scratchpad under the system temp folder, list each session&#39;s scratchpad with its size), (b) the agent&#39;s configuration and session-history directory in my home folder, broken down by its largest subdirectories, (c) every git worktree: run `git worktree list` in each repository under my projects folder and give each linked worktree&#39;s path and size. Use du; note that du counts APFS clones at full size, so totals are an upper bound.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">2. Classify every item over 100 MB, and every worktree, as exactly one of:
</span></span><span class="line"><span class="cl">   - IN USE: a running process has its working directory or files there (check with ps and lsof on the process list, not by assumption), or it is the scratchpad of a session that is running now (including this one).
</span></span><span class="line"><span class="cl">   - RECOVERABLE: nothing is running there, `git status` shows no uncommitted changes, no untracked files you cannot regenerate, and every local commit is pushed (compare with the upstream branch); or it is a plain build or dependency folder (node_modules, .build, .venv) that can be rebuilt.
</span></span><span class="line"><span class="cl">   - UNKNOWN: anything else, including when you could not check. A session transcript or history folder is never RECOVERABLE: a stopped session can still be resumed from it, and it cannot be regenerated. A folder holding a worktree whose branch has commits that exist nowhere else is UNKNOWN even if the folder itself is missing.
</span></span><span class="line"><span class="cl">   For each item give the evidence in one line: the process found or not found, the git status result, the unpushed commit count, the last-modified time.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">3. Report as a table: path, size, class, evidence. Then totals per class. State what your checks could not see, for example a session that is stopped but could be resumed, or a worktree with a stash.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">4. Stop. Do not delete anything. Ask which items I want removed, and say for each which tool&#39;s own command you would use (`git worktree remove`, `swift package reset`, deleting the folder).</span></span></code></pre></div></div>
  </div>
</div><p>The prompt avoids Claude Code&rsquo;s names, but I tested it only in Claude Code.</p>
<h2 id="read-the-table-by-class">Read the table by class<a class="heading-anchor" href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#read-the-table-by-class"
     aria-label="Link to section: Read the table by class" data-pagefind-ignore></a>
</h2>
<p>A session transcript or history folder is never RECOVERABLE: a stopped session can be resumed from it with <code>--resume</code>, and it can&rsquo;t be regenerated. In my run, a running session&rsquo;s transcripts came back IN USE and the rest UNKNOWN. Claude Code already deletes transcripts older than its <code>cleanupPeriodDays</code> setting (see <a href="https://code.claude.com/docs/en/settings-reference#cleanupperioddays" rel="external noopener" target="_blank">the settings reference<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>); change that setting rather than deleting transcripts by hand.</p>
<p>A worktree whose folder is gone can still matter. A worktree is a second working folder for a repository, and git records it in the repository itself. If the worktree was on a detached HEAD, its HEAD in the repository may be the only reference to its commits, even though the folder is gone. A named branch survives removing the worktree; its unpushed commits are at risk only if you later delete the branch. The prompt classes such a worktree as UNKNOWN.</p>
<p>The report ends with totals per class and a list of what the checks couldn&rsquo;t see. Read the list before the totals.</p>
<h2 id="what-the-report-cannot-see">What the report cannot see<a class="heading-anchor" href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#what-the-report-cannot-see"
     aria-label="Link to section: What the report cannot see" data-pagefind-ignore></a>
</h2>
<p>Claude Code can&rsquo;t check everything, and the prompt makes it say so. In my run it listed these:</p>
<ul>
<li><strong>A stopped session that could be resumed.</strong> The check finds that no process is running, not whether you&rsquo;ll come back to it.</li>
<li><strong>Short-lived processes.</strong> A process that wasn&rsquo;t running at the moment of the check doesn&rsquo;t show up in <code>ps</code>.</li>
<li><strong>Remote-tracking refs last fetched months ago.</strong> The unpushed count compares local commits with the last-fetched state of the remote, so it can be wrong in either direction. In the test Claude Code didn&rsquo;t run <code>git ls-remote</code>, which contacts the network.</li>
<li><strong>A stash.</strong> Stashes are repository-wide, and a worktree&rsquo;s <code>git status</code> doesn&rsquo;t show them.</li>
<li><strong>Ignored files in clones.</strong> Files that git ignores don&rsquo;t appear in <code>git status</code>, so a RECOVERABLE clone can still hold something you made.</li>
</ul>
<p><code>du</code> has a limit of its own. It counts APFS clones at full size, so every total is an upper bound on what deleting frees. Measure the container&rsquo;s free space before and after, as in <a href="https://looselydecoupled.com/mac-disk-full-developer-caches/">finding what&rsquo;s taking up the space</a>, to see what the Mac actually got back.</p>
<h2 id="approve-removals-one-item-at-a-time">Approve removals one item at a time<a class="heading-anchor" href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#approve-removals-one-item-at-a-time"
     aria-label="Link to section: Approve removals one item at a time" data-pagefind-ignore></a>
</h2>
<p>The prompt&rsquo;s last step tells Claude Code to stop after the report and ask which items you want removed. For each item it names the tool&rsquo;s own command: <code>git worktree remove</code> for a worktree, <code>swift package reset</code> for a Swift package&rsquo;s build state, or deleting the folder. My test run was one-shot, so I haven&rsquo;t seen this step in an interactive session.</p>
<p>Decide per item, not per class. RECOVERABLE means the checks found nothing to lose, not that the item is certain to be safe, so go through the limits in the previous section first. A line of evidence you can&rsquo;t explain is a reason to refuse that item.</p>
<div class="admonition admonition--warning" role="note">
  <p class="admonition__label">
    <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#i-triangle-alert"/></svg>
    <span>Warning</span>
  </p>
  <p>Do not let the agent run <code>git worktree prune</code> while a missing worktree in the repository is on a detached HEAD. Pruning clears every missing worktree in a repository, not only the one you have in mind. A detached worktree&rsquo;s HEAD can be the only reference to its commits (<a href="https://git-scm.com/docs/git-worktree" rel="external noopener" target="_blank">git worktree<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>). Git also removes a missing worktree&rsquo;s records on its own after a while (<code>gc.worktreePruneExpire</code>), so do not leave those commits without a branch. Give each one a branch first: read the commit from <code>git worktree list --porcelain</code> and run <code>git branch keep-&lt;name&gt; &lt;commit&gt;</code>. Remove a worktree whose folder still exists with <code>git worktree remove &lt;path&gt;</code>; removing it without a branch drops the reference exactly as pruning does. The report drew the same line: it called pruning safe for worktrees whose branches existed and unsafe for those on a detached HEAD.</p>
</div><h2 id="what-one-run-found">What one run found<a class="heading-anchor" href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#what-one-run-found"
     aria-label="Link to section: What one run found" data-pagefind-ignore></a>
</h2>
<p>Numbers from one Mac on October 20. The prompt asks about all my coding agents, so the report also measured a second agent&rsquo;s directory, <code>~/.codex</code>. It was the largest item, and this page doesn&rsquo;t cover cleaning it. Worktrees whose folders were gone still referenced commits.</p>
<div class="table-wrap" data-scrollable data-label="Table: Item">
  <table>
    <thead>
      <tr><th scope="col">Item</th><th scope="col">Size</th><th scope="col">What it was</th></tr>
    </thead>
    <tbody>
      <tr><td>Claude Code temporary scratch area</td><td>2.0 GB</td><td>66 per-session scratchpads; the largest 1.3 GB, the next 246 MB</td></tr>
      <tr><td><code>~/.claude</code></td><td>3.7 GB</td><td>Session transcripts (<code>projects</code>) 2.6 GB, the largest part</td></tr>
      <tr><td>A second agent&rsquo;s directory, <code>~/.codex</code></td><td>7.8 GB</td><td>Packages 2.0 GB, sessions 1.9 GB, a history database 1.5 GB, generated images 1.1 GB</td></tr>
    </tbody>
  </table>
</div>
<p>Claude Code classed the second agent&rsquo;s package folder IN USE, because a running process executed from it. It classed three worktrees on a detached HEAD, whose folders were gone, as UNKNOWN.</p>
<p>The class totals were about 2.6 GB IN USE, 1.5 GB RECOVERABLE and 8.7 GB UNKNOWN; most of the UNKNOWN was the rest of the second agent&rsquo;s directory. The totals cover only what the prompt classifies, items over 100 MB and worktrees, so they don&rsquo;t add up to the table.</p>
<p>I checked the Claude Code sizes against my own <code>du</code>; the <code>~/.codex</code> figures are the agent&rsquo;s. I checked that the second run wrote no plan file. I didn&rsquo;t check each classification line. Treat the classes as the agent&rsquo;s report, not as my measurement.</p>
<p>Claude Code counted 19 linked worktrees across 9 repositories. My own search, to six directory levels, found 16, plus 12 <code>.claude/worktrees</code> directories under my projects folder.</p>
<h2 id="common-failures">Common failures<a class="heading-anchor" href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#common-failures"
     aria-label="Link to section: Common failures" data-pagefind-ignore></a>
</h2>
<h3 id="plan-file-appears-after-a-read-only-run">Plan file appears after a read-only run<a class="heading-anchor" href="https://looselydecoupled.com/claude-code-disk-space-worktrees/#plan-file-appears-after-a-read-only-run"
     aria-label="Link to section: Plan file appears after a read-only run" data-pagefind-ignore></a>
</h3>
<p>A new file appears in <code>~/.claude/plans</code> after the report. Plan mode writes a plan file by a mechanism of its own, and a prompt that only says not to modify anything doesn&rsquo;t stop it. My first run, with that wording, wrote one. Keep the prompt&rsquo;s line that forbids writing any file, including a plan or notes file; with it, my second run wrote none. After a run, list the folder newest first and check for a file from that run:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">ls</span> <span class="console__token">-lt</span> <span class="console__token">~/.claude/plans</span></span></code></pre>
    </div>
  </div></div>]]></content:encoded>
    </item>
    
    <item>
      <title>How to Find and Delete Old node_modules, .build and .venv Folders on a Mac</title>
      <link>https://looselydecoupled.com/delete-build-folders-old-projects-mac/</link>
      <guid isPermaLink="true">https://looselydecoupled.com/delete-build-folders-old-projects-mac/</guid>
      <pubDate>Tue, 20 Oct 2026 00:00:00 +0000</pubDate>
      <dc:creator>Emmanuel Tsouris</dc:creator>
      <category>Disk space</category>
      
      <description>The build folders in projects you&#39;ve stopped working on held about 27 of the 63 GiB on the test Mac, and those are the ones safe to clear.</description>
      <content:encoded><![CDATA[<div class="answer" data-answer="true">
  <p class="answer__label" data-pagefind-ignore>TL;DR</p>
  <p>Delete build folders only in projects you haven&rsquo;t touched in a while. Treat a project as idle when its last commit is 90 or more days old and <code>git status</code> is empty. That&rsquo;s a choice, not a standard. For Swift, run <code>swift package reset</code> in the project. It removes <code>.build</code> entirely, while <code>swift package clean</code> leaves a 2 MiB skeleton that keeps the downloaded dependencies. For Node, the npm documentation lists no command that removes <code>node_modules</code>, so delete the folder and reinstall when you need it back: <code>npm ci</code> if the project has a <code>package-lock.json</code>, otherwise the package manager whose lockfile it has. The Python docs call a <code>.venv</code> disposable, so delete it and recreate it. First check the project has a requirements file or a lockfile. Expect to pay a rebuild the next time you open a project you cleared. Rebuild time wasn&rsquo;t measured.</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">git</span> <span class="console__token">-C</span> <span class="console__token">&#34;&lt;project-folder&gt;&#34;</span> <span class="console__token">status</span> <span class="console__token">--porcelain</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">swift</span> <span class="console__token">package</span> <span class="console__token">reset</span> <span class="console__token">--package-path</span> <span class="console__token">&#34;&lt;project-folder&gt;&#34;</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">rm</span> <span class="console__token">-rf</span> <span class="console__token">&#34;&lt;project-folder&gt;/node_modules&#34;</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">rm</span> <span class="console__token">-rf</span> <span class="console__token">&#34;&lt;project-folder&gt;/.venv&#34;</span></span></code></pre>
    </div>
  </div></div><p>Run the <code>rm</code> and <code>reset</code> lines only if <code>git status --porcelain</code> printed nothing and the last commit is 90 or more days old. <code>git status</code> doesn&rsquo;t report what&rsquo;s inside a folder that <code>.gitignore</code> lists, and projects usually list these, so that check can&rsquo;t see a hand-patched package inside one. Each command deletes the folder for good.</p>
<div class="tested" id="tested">
  <p class="label label--seam">Tested with</p><dl class="tested__rows">
    <div class="tested__row"><dt>macOS</dt> <dd>27.0.1</dd></div>
    <div class="tested__row"><dt>Swift</dt> <dd>6.4</dd></div>
    <div class="tested__row"><dt>Date</dt> <dd>October 2026</dd></div>
  </dl>
</div>

</div>

<p><a href="https://looselydecoupled.com/mac-disk-full-developer-caches/">Finding what&rsquo;s filling a developer Mac</a>
turned up one of the biggest causes on mine: the build folders that old
projects leave behind. Across my projects folder, 110 <code>.build</code> folders held
52.7 GiB of the 63.2 GiB that the three kinds below added up to. Each cause in
the <a href="https://looselydecoupled.com/series/developer-mac-disk-cleanup/">series</a> gets its own article, and
this one uses the build tool&rsquo;s own command where one exists. You don&rsquo;t need
that article to follow the steps here.</p>
<!-- style-check: procedure -->
<h2 id="find-the-build-folders-in-your-projects-folder">Find the build folders in your projects folder<a class="heading-anchor" href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#find-the-build-folders-in-your-projects-folder"
     aria-label="Link to section: Find the build folders in your projects folder" data-pagefind-ignore></a>
</h2>
<p>These commands only read. <code>-prune</code> stops <code>find</code> from descending into a match,
so a <code>node_modules</code> nested inside another isn&rsquo;t counted twice. Replace
<code>&lt;projects-folder&gt;</code> with the folder that holds your projects, such as
<code>~/Projects</code>.</p>
<p>Count the folders of each kind:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">find</span> <span class="console__token">&lt;projects-folder&gt;</span> <span class="console__token">-type</span> <span class="console__token">d</span> <span class="console__token">-name</span> <span class="console__token">.build</span> <span class="console__token">-prune</span> <span class="console__token">-print</span> <span class="console__token">|</span> <span class="console__token">wc</span> <span class="console__token">-l</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">find</span> <span class="console__token">&lt;projects-folder&gt;</span> <span class="console__token">-type</span> <span class="console__token">d</span> <span class="console__token">-name</span> <span class="console__token">node_modules</span> <span class="console__token">-prune</span> <span class="console__token">-print</span> <span class="console__token">|</span> <span class="console__token">wc</span> <span class="console__token">-l</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">find</span> <span class="console__token">&lt;projects-folder&gt;</span> <span class="console__token">-type</span> <span class="console__token">d</span> <span class="console__token">-name</span> <span class="console__token">.venv</span> <span class="console__token">-prune</span> <span class="console__token">-print</span> <span class="console__token">|</span> <span class="console__token">wc</span> <span class="console__token">-l</span></span></code></pre>
    </div>
  </div></div><p>Add up the size of one kind, in GiB. <code>du -sk</code> prints sizes in KiB, and <code>awk</code>
sums them:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">find</span> <span class="console__token">&lt;projects-folder&gt;</span> <span class="console__token">-type</span> <span class="console__token">d</span> <span class="console__token">-name</span> <span class="console__token">.build</span> <span class="console__token">-prune</span> <span class="console__token">-exec</span> <span class="console__token">du</span> <span class="console__token">-sk</span> <span class="console__token">{}</span> <span class="console__token">+</span> <span class="console__token">|</span> <span class="console__token">awk</span> <span class="console__token">&#39;{</span> <span class="console__token">kib</span> <span class="console__token">+=</span> <span class="console__token">$1</span> <span class="console__token">}</span> <span class="console__token">END</span> <span class="console__token">{</span> <span class="console__token">printf</span> <span class="console__token">&#34;%.1f</span> <span class="console__token">GiB\n&#34;,</span> <span class="console__token">kib</span> <span class="console__token">/</span> <span class="console__token">1024</span> <span class="console__token">/</span> <span class="console__token">1024</span> <span class="console__token">}&#39;</span></span></code></pre>
    </div>
  </div></div><p>Run it again with <code>node_modules</code> and <code>.venv</code> in place of <code>.build</code>.</p>
<h2 id="compare-your-totals-with-one-machines">Compare your totals with one machine&rsquo;s<a class="heading-anchor" href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#compare-your-totals-with-one-machines"
     aria-label="Link to section: Compare your totals with one machine’s" data-pagefind-ignore></a>
</h2>
<p>The totals here come from one Mac. The idle column used the last-commit test
only: a project counted as idle when its last commit was 90 or more days old,
and a folder that isn&rsquo;t a git repository used the folder&rsquo;s modified time
instead. It didn&rsquo;t check <code>git status</code>. The loop in the next section applies
both tests and skips folders that aren&rsquo;t git repositories, so its totals can
come out lower than this column.</p>
<div class="table-wrap" data-scrollable data-label="Table: Kind">
  <table>
    <thead>
      <tr><th scope="col">Kind</th><th class="align-right" scope="col">Directories</th><th class="align-right" scope="col">GiB</th><th class="align-right" scope="col">GiB in idle projects</th></tr>
    </thead>
    <tbody>
      <tr><td><code>.build</code></td><td class="align-right">110</td><td class="align-right">52.7</td><td class="align-right">24.5</td></tr>
      <tr><td><code>node_modules</code></td><td class="align-right">20</td><td class="align-right">7.4</td><td class="align-right">1.5</td></tr>
      <tr><td><code>.venv</code></td><td class="align-right">41</td><td class="align-right">3.1</td><td class="align-right">1.1</td></tr>
      <tr><td>Total</td><td class="align-right">171</td><td class="align-right">63.2</td><td class="align-right">27.1</td></tr>
    </tbody>
  </table>
</div>
<p>The largest single <code>.build</code> was 8.6 GiB, in a project idle for 156 days.</p>
<p><code>du -sk</code> is an upper bound on what deleting frees. APFS clones share their
blocks with the original until one of them changes, and <code>du</code> counts a cloned
file at full size wherever it appears.</p>
<h2 id="pick-the-idle-projects">Pick the idle projects<a class="heading-anchor" href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#pick-the-idle-projects"
     aria-label="Link to section: Pick the idle projects" data-pagefind-ignore></a>
</h2>
<p>A build folder in a project you&rsquo;re working in costs you a rebuild. Delete only
where both of these hold:</p>
<ul>
<li>The last commit is 90 or more days old.</li>
<li>Running <code>git status --porcelain</code> prints nothing, so the source tree has no
uncommitted change.</li>
</ul>
<p><code>git status</code> doesn&rsquo;t report what&rsquo;s inside a folder that <code>.gitignore</code> lists,
and build folders usually are listed, so the second test says nothing about
what&rsquo;s inside one. A package you patched by hand in <code>node_modules</code>, or
installed into a <code>.venv</code> without adding it to a requirements file, is lost
with the folder. If you might have done either, check before you delete.</p>
<p>Use a different number than 90 if your projects move at a different pace. This
loop applies both tests and prints a count and a total per kind. It skips a
folder whose parent isn&rsquo;t a git repository, because the loop has no commit to
read there. A project where <code>git</code> itself fails, such as one with a damaged
index or no commits yet, is counted as skipped rather than clean. Replace
<code>~/Projects</code> with your projects folder:</p>
<div class="code-block" data-copyable data-copy-label="Bash">
  <div class="code-block__head"><span class="code-block__lang">Bash</span>
  </div>
  <div class="code-block__scroll">
    <div data-copy-source><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">projects</span><span class="o">=</span>~/Projects
</span></span><span class="line"><span class="cl"><span class="k">for</span> kind in .build node_modules .venv<span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">  <span class="nv">count</span><span class="o">=</span>0<span class="p">;</span> <span class="nv">kib</span><span class="o">=</span>0<span class="p">;</span> <span class="nv">skipped</span><span class="o">=</span><span class="m">0</span>
</span></span><span class="line"><span class="cl">  <span class="k">while</span> <span class="nv">IFS</span><span class="o">=</span> <span class="nb">read</span> -r dir<span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="nv">project</span><span class="o">=</span><span class="k">$(</span>dirname <span class="s2">&#34;</span><span class="nv">$dir</span><span class="s2">&#34;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">    git -C <span class="s2">&#34;</span><span class="nv">$project</span><span class="s2">&#34;</span> rev-parse --is-inside-work-tree &gt;/dev/null 2&gt;<span class="p">&amp;</span><span class="m">1</span> <span class="o">||</span> <span class="o">{</span> <span class="o">[</span> -e <span class="s2">&#34;</span><span class="nv">$project</span><span class="s2">/.git&#34;</span> <span class="o">]</span> <span class="o">&amp;&amp;</span> <span class="nv">skipped</span><span class="o">=</span><span class="k">$((</span>skipped <span class="o">+</span> <span class="m">1</span><span class="k">))</span><span class="p">;</span> <span class="k">continue</span><span class="p">;</span> <span class="o">}</span>
</span></span><span class="line"><span class="cl">    <span class="nv">recent</span><span class="o">=</span><span class="k">$(</span>git -C <span class="s2">&#34;</span><span class="nv">$project</span><span class="s2">&#34;</span> log -1 --since<span class="o">=</span><span class="s1">&#39;90 days ago&#39;</span> 2&gt;/dev/null<span class="k">)</span> <span class="o">||</span> <span class="o">{</span> <span class="nv">skipped</span><span class="o">=</span><span class="k">$((</span>skipped <span class="o">+</span> <span class="m">1</span><span class="k">))</span><span class="p">;</span> <span class="k">continue</span><span class="p">;</span> <span class="o">}</span>
</span></span><span class="line"><span class="cl">    <span class="o">[</span> -z <span class="s2">&#34;</span><span class="nv">$recent</span><span class="s2">&#34;</span> <span class="o">]</span> <span class="o">||</span> <span class="k">continue</span>
</span></span><span class="line"><span class="cl">    <span class="nv">changes</span><span class="o">=</span><span class="k">$(</span>git -C <span class="s2">&#34;</span><span class="nv">$project</span><span class="s2">&#34;</span> status --porcelain 2&gt;/dev/null<span class="k">)</span> <span class="o">||</span> <span class="o">{</span> <span class="nv">skipped</span><span class="o">=</span><span class="k">$((</span>skipped <span class="o">+</span> <span class="m">1</span><span class="k">))</span><span class="p">;</span> <span class="k">continue</span><span class="p">;</span> <span class="o">}</span>
</span></span><span class="line"><span class="cl">    <span class="o">[</span> -z <span class="s2">&#34;</span><span class="nv">$changes</span><span class="s2">&#34;</span> <span class="o">]</span> <span class="o">||</span> <span class="k">continue</span>
</span></span><span class="line"><span class="cl">    <span class="nv">count</span><span class="o">=</span><span class="k">$((</span>count <span class="o">+</span> <span class="m">1</span><span class="k">))</span>
</span></span><span class="line"><span class="cl">    <span class="nv">kib</span><span class="o">=</span><span class="k">$((</span>kib <span class="o">+</span> <span class="k">$(</span>du -sk <span class="s2">&#34;</span><span class="nv">$dir</span><span class="s2">&#34;</span> <span class="p">|</span> cut -f1<span class="k">)))</span>
</span></span><span class="line"><span class="cl">  <span class="k">done</span> &lt; &lt;<span class="o">(</span>find <span class="s2">&#34;</span><span class="nv">$projects</span><span class="s2">&#34;</span> -type d -name <span class="s2">&#34;</span><span class="nv">$kind</span><span class="s2">&#34;</span> -prune -print 2&gt;/dev/null<span class="o">)</span>
</span></span><span class="line"><span class="cl">  <span class="nb">echo</span> <span class="s2">&#34;</span><span class="nv">$kind</span><span class="s2">: </span><span class="nv">$count</span><span class="s2"> idle and clean, </span><span class="k">$((</span>kib <span class="o">/</span> <span class="m">1024</span> <span class="o">/</span> <span class="m">1024</span><span class="k">))</span><span class="s2"> GiB, </span><span class="nv">$skipped</span><span class="s2"> skipped because git failed&#34;</span>
</span></span><span class="line"><span class="cl"><span class="k">done</span></span></span></code></pre></div></div>
  </div>
</div><p>The GiB figure is rounded down, so a kind under 1 GiB prints 0. A project
that isn&rsquo;t a git repository needs your own judgment. The folder&rsquo;s modified
time is a rough substitute, and it&rsquo;s the one the table used.</p>
<p>To list the idle projects, add <code>echo &quot;$project&quot;</code> on the line after
<code>count=$((count + 1))</code>.</p>
<h2 id="delete-a-build-folder-with-swift-package-reset">Delete a .build folder with swift package reset<a class="heading-anchor" href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#delete-a-build-folder-with-swift-package-reset"
     aria-label="Link to section: Delete a .build folder with swift package reset" data-pagefind-ignore></a>
</h2>
<p>SwiftPM has two commands that sound alike. The documentation describes
<a href="https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/packageclean" rel="external noopener" target="_blank"><code>swift package clean</code><svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>
as &ldquo;Delete build artifacts.&rdquo; and
<a href="https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/packagereset" rel="external noopener" target="_blank"><code>swift package reset</code><svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>
as &ldquo;Reset the complete cache/build directory.&rdquo; Neither page says what
survives, so I ran each on a throwaway copy of one idle project. Both copies
had a <code>.build</code> of about 678 MiB:</p>
<div class="table-wrap" data-scrollable data-label="Table: Command">
  <table>
    <thead>
      <tr><th scope="col">Command</th><th scope="col"><code>.build</code> afterward</th></tr>
    </thead>
    <tbody>
      <tr><td><code>swift package clean</code></td><td>About 2 MiB, still holding <code>checkouts</code>, <code>repositories</code>, <code>artifacts</code> and <code>workspace-state.json</code></td></tr>
      <tr><td><code>swift package reset</code></td><td>Removed entirely</td></tr>
    </tbody>
  </table>
</div>
<p><code>clean</code> removes the compiled products and keeps the downloaded dependencies.
<code>reset</code> removes the folder, so the dependencies go with it. To get the space
back, use <code>reset</code>.</p>
<p><code>swift package reset</code> deletes the <code>.build</code> folder, including downloaded
dependencies, in the package that <code>--package-path</code> names. Point it at the
folder that holds the <code>.build</code> and its <code>Package.swift</code>, after the
<code>git status --porcelain</code> check:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">git</span> <span class="console__token">-C</span> <span class="console__token">&#34;&lt;project-folder&gt;&#34;</span> <span class="console__token">status</span> <span class="console__token">--porcelain</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">swift</span> <span class="console__token">package</span> <span class="console__token">reset</span> <span class="console__token">--package-path</span> <span class="console__token">&#34;&lt;project-folder&gt;&#34;</span></span></code></pre>
    </div>
  </div></div><p>On the real project, whose <code>.build</code> measured about 675 MiB,
<code>git status --porcelain</code> printed nothing before or after, <code>.build</code> was gone,
and Container Free Space rose by about 675 MiB.</p>
<p>The next build of that project has to rebuild what <code>reset</code> removed, and how
long that takes wasn&rsquo;t measured. If a project keeps its build output somewhere
other than <code>.build</code>, both commands take <code>--scratch-path</code>, whose default is
<code>.build</code>.</p>
<h2 id="delete-node_modules-in-an-idle-project">Delete node_modules in an idle project<a class="heading-anchor" href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#delete-node_modules-in-an-idle-project"
     aria-label="Link to section: Delete node_modules in an idle project" data-pagefind-ignore></a>
</h2>
<p>The npm documentation lists no command that removes <code>node_modules</code>. It describes
<a href="https://docs.npmjs.com/cli/v11/commands/npm-prune" rel="external noopener" target="_blank"><code>npm prune</code><svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a> as removing
only extraneous packages. <a href="https://docs.npmjs.com/cli/v11/commands/npm-ci" rel="external noopener" target="_blank"><code>npm ci</code><svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>
deletes the folder as a side effect: &ldquo;If a <code>node_modules</code> is already present,
it will be automatically removed before <code>npm ci</code> begins its install.&rdquo; That
reinstalls rather than frees space.</p>
<p>This deletes the folder and everything in it. <code>package.json</code> and the lockfile
stay, so the project&rsquo;s package manager restores it: <code>npm ci</code> needs a
<code>package-lock.json</code> or <code>npm-shrinkwrap.json</code>, and a project with a <code>yarn.lock</code>
or <code>pnpm-lock.yaml</code> reinstalls with that tool instead. Replace
<code>&lt;project-folder&gt;</code> with the idle project&rsquo;s root, and run it after the
<code>git status --porcelain</code> check:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">rm</span> <span class="console__token">-rf</span> <span class="console__token">&#34;&lt;project-folder&gt;/node_modules&#34;</span></span></code></pre>
    </div>
  </div></div><h2 id="delete-a-venv-in-an-idle-project">Delete a .venv in an idle project<a class="heading-anchor" href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#delete-a-venv-in-an-idle-project"
     aria-label="Link to section: Delete a .venv in an idle project" data-pagefind-ignore></a>
</h2>
<p>The Python documentation calls a virtual environment
<a href="https://docs.python.org/3/library/venv.html" rel="external noopener" target="_blank">&ldquo;Considered as disposable – it should be simple to delete and recreate it from scratch.&rdquo;<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>
No command removes one. <code>--clear</code> empties the directory and recreates the
environment in place, so it doesn&rsquo;t clear space for good.</p>
<p>Look for a requirements file or a lockfile in the project first. If there&rsquo;s
none, stop: the environment is the only place the installed package list might
live, and recreating it needs that list. To recreate the environment later, run
<code>python3 -m venv .venv</code> in the project and install from the file. A <code>.venv</code>
removal wasn&rsquo;t measured.</p>
<p>The next command deletes the folder and everything in it. Replace
<code>&lt;project-folder&gt;</code> with the idle project&rsquo;s root, and run it after the
<code>git status --porcelain</code> check:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">rm</span> <span class="console__token">-rf</span> <span class="console__token">&#34;&lt;project-folder&gt;/.venv&#34;</span></span></code></pre>
    </div>
  </div></div><h2 id="confirm-the-space-came-back">Confirm the space came back<a class="heading-anchor" href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#confirm-the-space-came-back"
     aria-label="Link to section: Confirm the space came back" data-pagefind-ignore></a>
</h2>
<p>Read the container&rsquo;s free space before the first deletion and again after the
last:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span></span></code></pre>
    </div>
  </div></div><p>Wait at least 20 seconds after the last deletion before the second reading. In
the test, readings 20, 40 and 60 seconds after <code>swift package reset</code> agreed
within about 5 MB.</p>
<!-- style-check: end procedure -->
<h2 id="do-this-with-a-coding-agent">Do this with a coding agent<a class="heading-anchor" href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/#do-this-with-a-coding-agent"
     aria-label="Link to section: Do this with a coding agent" data-pagefind-ignore></a>
</h2>
<p>Paste this prompt into your own local coding agent. It reports first and
removes nothing until you confirm:</p>
<div class="code-block" data-copyable data-copy-label="Text">
  <div class="code-block__head"><span class="code-block__lang">Text</span>
  </div>
  <div class="code-block__scroll">
    <div data-copy-source><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Find build-output directories under &lt;projects-folder&gt;: .build, node_modules and
</span></span><span class="line"><span class="cl">.venv. Measure and report first; delete nothing until I confirm.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">1. Record free space with diskutil info / (Container Free Space).
</span></span><span class="line"><span class="cl">2. Find every .build, node_modules and .venv directory under the folder with
</span></span><span class="line"><span class="cl">   find -prune, so nested matches aren&#39;t counted twice. For each project that
</span></span><span class="line"><span class="cl">   holds one, report the directory&#39;s size (du -sk), the date of the last
</span></span><span class="line"><span class="cl">   commit, and whether git status --porcelain is empty. Say plainly that du
</span></span><span class="line"><span class="cl">   counts APFS clones at full size, so a total is an upper bound.
</span></span><span class="line"><span class="cl">3. List the projects whose last commit is 90 or more days old and whose git
</span></span><span class="line"><span class="cl">   status is clean as candidates. Treat a project that is not a git repository
</span></span><span class="line"><span class="cl">   as needing my decision, and say so.
</span></span><span class="line"><span class="cl">4. Stop and wait. I will say which candidates to clear.
</span></span><span class="line"><span class="cl">5. For each one I confirm, use the ecosystem&#39;s own command where it has one:
</span></span><span class="line"><span class="cl">   swift package reset for .build. There is no npm or Python command that
</span></span><span class="line"><span class="cl">   removes node_modules or .venv, so for those, delete only the directory I
</span></span><span class="line"><span class="cl">   confirmed, by its full path. Check a requirements file or lockfile exists
</span></span><span class="line"><span class="cl">   before removing a .venv, and tell me which lockfile each node_modules
</span></span><span class="line"><span class="cl">   project has so I know how to reinstall it. git status does not look inside
</span></span><span class="line"><span class="cl">   ignored folders, so ask me whether I patched or hand-installed anything in
</span></span><span class="line"><span class="cl">   one before deleting it.
</span></span><span class="line"><span class="cl">6. Record free space again with the same command, after at least 20 seconds,
</span></span><span class="line"><span class="cl">   and report the difference. Report it against the du total, and don&#39;t claim
</span></span><span class="line"><span class="cl">   a rebuild time you did not measure.</span></span></code></pre></div></div>
  </div>
</div>]]></content:encoded>
    </item>
    
    <item>
      <title>Why the uv Cache Is So Large on a Mac, and How to Prune It Safely</title>
      <link>https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/</link>
      <guid isPermaLink="true">https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/</guid>
      <pubDate>Fri, 16 Oct 2026 00:00:00 +0000</pubDate>
      <dc:creator>Emmanuel Tsouris</dc:creator>
      <category>Disk space</category>
      
      <description>Pruning cut a 133 GiB uv cache to 4 GiB, and free-space readings before and after show the real gain: about 28 GB on a 1 TB Mac.</description>
      <content:encoded><![CDATA[<div class="answer" data-answer="true">
  <p class="answer__label" data-pagefind-ignore>TL;DR</p>
  <p>Quit every coding agent and editor that launches MCP servers. Then run <code>uv cache prune</code>. A running session holds the cache lock. While a session holds it, prune prints &ldquo;Cache is currently in-use, waiting for other uv processes to finish&rdquo;. After uv&rsquo;s lock timeout, prune gives up. Do not use <code>--force</code> to skip the lock. Expect much less space back than prune reports. On this Mac, prune reported 111.1 GiB (about 119 GB) removed, and the disk gained 27.5 GB. Cloned files that share blocks most likely explain the gap.</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">uv</span> <span class="console__token">cache</span> <span class="console__token">size</span> <span class="console__token">-H</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">df</span> <span class="console__token">-h</span> <span class="console__token">/</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">lsof</span> <span class="console__token">&#34;$(uv</span> <span class="console__token">cache</span> <span class="console__token">dir)/.lock&#34;</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">uv</span> <span class="console__token">cache</span> <span class="console__token">prune</span></span></code></pre>
    </div>
  </div></div>
</div>

<p>My Mac was down to 38.4 GB free on a 1 TB disk. The largest directory on it was a 132.7 GiB uv cache that I had never thought about. The coding agents I use launch MCP servers with <code>uvx</code>, and that was enough to fill it.</p>
<p><code>uvx</code> is uv&rsquo;s command for running a Python tool from a temporary environment, without installing it. If you have never run uv by hand, an agent or editor ran it for you. This page is part of a series on <a href="https://looselydecoupled.com/series/developer-mac-disk-cleanup/">cleaning up a developer Mac&rsquo;s disk</a>. <a href="https://looselydecoupled.com/mac-disk-full-developer-caches/">What&rsquo;s Taking Up All the Space on My Developer Mac?</a>, on finding what&rsquo;s filling the disk, is how to know the cache is the cause; you don&rsquo;t need it to follow the steps here.</p>
<div class="tested" id="tested">
  <p class="label label--seam">Tested with</p><dl class="tested__rows">
    <div class="tested__row"><dt>uv</dt> <dd>0.11.12</dd></div>
    <div class="tested__row"><dt>macOS</dt> <dd>27.0.1, Apple silicon, APFS</dd></div>
    <div class="tested__row"><dt>Date</dt> <dd>October 2026</dd></div>
  </dl>
</div>
<h2 id="check-the-size-and-location-of-the-cache">Check the size and location of the cache<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#check-the-size-and-location-of-the-cache"
     aria-label="Link to section: Check the size and location of the cache" data-pagefind-ignore></a>
</h2>
<p>The environments <code>uvx</code> builds go in uv&rsquo;s cache. Ask uv for the size and the directory:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">uv</span> <span class="console__token">cache</span> <span class="console__token">size</span> <span class="console__token">-H</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">warning:</span> <span class="console__token">`uv</span> <span class="console__token">cache</span> <span class="console__token">size`</span> <span class="console__token">is</span> <span class="console__token">experimental</span> <span class="console__token">and</span> <span class="console__token">may</span> <span class="console__token">change</span> <span class="console__token">without</span> <span class="console__token">warning.</span> <span class="console__token">Pass</span> <span class="console__token">`--preview-features</span> <span class="console__token">cache-size`</span> <span class="console__token">to</span> <span class="console__token">disable</span> <span class="console__token">this</span> <span class="console__token">warning.</span>
</span><span class="line"><span class="console__token">132.7GiB</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">uv</span> <span class="console__token">cache</span> <span class="console__token">dir</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">/Users/&lt;user&gt;/.cache/uv</span></span></code></pre>
    </div>
  </div></div><p>uv labels <code>uv cache size</code> as experimental, which is the reason for the warning. The number is still the one to start from. The <code>--cache-dir</code> option, the <code>UV_CACHE_DIR</code> and <code>XDG_CACHE_HOME</code> variables and the <code>tool.uv.cache-dir</code> setting move the directory, according to <a href="https://docs.astral.sh/uv/concepts/cache/" rel="external noopener" target="_blank">uv&rsquo;s cache documentation<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>. Every command below reads the directory from <code>uv cache dir</code>, so it follows a moved cache.</p>
<h2 id="find-what-fills-the-cache">Find what fills the cache<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#find-what-fills-the-cache"
     aria-label="Link to section: Find what fills the cache" data-pagefind-ignore></a>
</h2>
<p>Environments that <code>uvx</code> builds sit in the cache&rsquo;s <code>archive-v0</code> directory. Count its entries, then count the ones that are Python environments, which have a <code>pyvenv.cfg</code> at their root:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">ls</span> <span class="console__token">&#34;$(uv</span> <span class="console__token">cache</span> <span class="console__token">dir)&#34;/archive-v0</span> <span class="console__token">|</span> <span class="console__token">wc</span> <span class="console__token">-l</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">find</span> <span class="console__token">&#34;$(uv</span> <span class="console__token">cache</span> <span class="console__token">dir)&#34;/archive-v0</span> <span class="console__token">-maxdepth</span> <span class="console__token">2</span> <span class="console__token">-name</span> <span class="console__token">pyvenv.cfg</span> <span class="console__token">|</span> <span class="console__token">wc</span> <span class="console__token">-l</span></span></code></pre>
    </div>
  </div></div><p>On this Mac, <code>archive-v0</code> held 4,005 entries, and 2,562 of them were environments. To see which MCP servers the environments belong to, count the executables with <code>mcp</code> in their names in the environments&rsquo; <code>bin</code> directories (a server named otherwise needs its own pattern):</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">ls</span> <span class="console__token">-d</span> <span class="console__token">&#34;$(uv</span> <span class="console__token">cache</span> <span class="console__token">dir)&#34;/archive-v0/*/bin/*mcp*</span> <span class="console__token">|</span> <span class="console__token">xargs</span> <span class="console__token">-n1</span> <span class="console__token">basename</span> <span class="console__token">|</span> <span class="console__token">sort</span> <span class="console__token">|</span> <span class="console__token">uniq</span> <span class="console__token">-c</span> <span class="console__token">|</span> <span class="console__token">sort</span> <span class="console__token">-rn</span> <span class="console__token">|</span> <span class="console__token">head</span></span></code></pre>
    </div>
  </div></div><p>Nearly all of the environments were copies of three MCP servers, with 1,150, 1,143 and 191 copies, plus 50 of a fourth. One server&rsquo;s environments held only 158 distinct sets of installed packages, and environments built on the same day had the same installed packages.</p>
<h3 id="why-each-launch-can-add-an-environment">Why each launch can add an environment<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#why-each-launch-can-add-an-environment"
     aria-label="Link to section: Why each launch can add an environment" data-pagefind-ignore></a>
</h3>
<p>An MCP server configured as <code>uvx &lt;server&gt;@latest</code> asks uv to resolve the latest version on every launch. With <code>uvx -v</code>, the log shows uv fetching the latest version and revalidating the index. Launching one server did not explain more than a thousand copies, so I measured when a launch adds an environment:</p>
<div class="table-wrap" data-scrollable data-label="Table: Launches">
  <table>
    <thead>
      <tr><th scope="col">Launches</th><th scope="col">Resolution</th><th class="align-right" scope="col">Environments added</th></tr>
    </thead>
    <tbody>
      <tr><td>One</td><td>New (not cached yet)</td><td class="align-right">1</td></tr>
      <tr><td>Four at the same moment</td><td>New</td><td class="align-right">4</td></tr>
      <tr><td>Four at the same moment</td><td>Already cached</td><td class="align-right">0</td></tr>
      <tr><td>Four, <code>@latest</code> and plain</td><td>Already cached</td><td class="align-right">0</td></tr>
    </tbody>
  </table>
</div>
<p>When several sessions start together and the resolution isn&rsquo;t cached yet, each launch builds its own environment. Once the resolution is cached, launches add nothing. That implies pinning a version, instead of <code>@latest</code>, would stop most of the copies. I didn&rsquo;t test that. I also didn&rsquo;t check whether a later release of uv reuses an environment that another process built moments earlier. All of this is uv 0.11.12.</p>
<h2 id="choose-between-uv-cache-prune-and-uv-cache-clean">Choose between uv cache prune and uv cache clean<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#choose-between-uv-cache-prune-and-uv-cache-clean"
     aria-label="Link to section: Choose between uv cache prune and uv cache clean" data-pagefind-ignore></a>
</h2>
<p><code>uv cache prune</code> removes the cache entries nothing uses, and all centralized project environments, which uv recreates as needed. <code>uv cache clean</code> removes every entry and empties the cache; <code>uv cache clean &lt;package&gt;</code> removes one package&rsquo;s entries. Both are described in <a href="https://docs.astral.sh/uv/concepts/cache/" rel="external noopener" target="_blank">uv&rsquo;s cache documentation<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>. This page uses prune, which here took the cache from 132.7 GiB to 3.9 GiB and left 540 entries in place. I didn&rsquo;t run clean.</p>
<h2 id="quit-every-session-that-holds-the-cache-lock">Quit every session that holds the cache lock<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#quit-every-session-that-holds-the-cache-lock"
     aria-label="Link to section: Quit every session that holds the cache lock" data-pagefind-ignore></a>
</h2>
<p>Each running <code>uvx</code> process holds the cache lock, the <code>.lock</code> file in the cache directory, for as long as its server runs. Cache-modifying commands wait for the lock, so a prune started now waits too. List the holders:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">lsof</span> <span class="console__token">&#34;$(uv</span> <span class="console__token">cache</span> <span class="console__token">dir)/.lock&#34;</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">COMMAND</span>   <span class="console__token">PID</span>    <span class="console__token">USER</span>   <span class="console__token">FD</span>   <span class="console__token">TYPE</span> <span class="console__token">DEVICE</span> <span class="console__token">SIZE/OFF</span>    <span class="console__token">NODE</span> <span class="console__token">NAME</span>
</span><span class="line"><span class="console__token">uv</span>      <span class="console__token">&lt;pid&gt;</span> <span class="console__token">&lt;user&gt;</span>   <span class="console__token">9u</span>   <span class="console__token">REG</span>  <span class="console__token">&lt;dev&gt;</span>        <span class="console__token">0</span> <span class="console__token">&lt;inode&gt;</span> <span class="console__token">/Users/&lt;user&gt;/.cache/uv/.lock</span>
</span><span class="line"><span class="console__token">uv</span>      <span class="console__token">&lt;pid&gt;</span> <span class="console__token">&lt;user&gt;</span>   <span class="console__token">9u</span>   <span class="console__token">REG</span>  <span class="console__token">&lt;dev&gt;</span>        <span class="console__token">0</span> <span class="console__token">&lt;inode&gt;</span> <span class="console__token">/Users/&lt;user&gt;/.cache/uv/.lock</span></span></code></pre>
    </div>
  </div></div><p><code>lsof</code> prints nothing when the lock is free; empty output from a path that is not your cache directory is not a clear lock. Each row is one <code>uvx</code> process. To find the session that started it, look up the parent of each <code>&lt;pid&gt;</code>:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">ps</span> <span class="console__token">-o</span> <span class="console__token">ppid=</span> <span class="console__token">-p</span> <span class="console__token">&lt;pid&gt;</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">ps</span> <span class="console__token">-o</span> <span class="console__token">comm=</span> <span class="console__token">-p</span> <span class="console__token">&lt;ppid&gt;</span></span></code></pre>
    </div>
  </div></div><p>On this Mac, one holder was launched by a Claude Code session and another by the VS Code extension host. Quitting a session or an editor ends its <code>uvx</code> children, which release the lock:</p>
<ol>
<li>Run <code>lsof &quot;$(uv cache dir)/.lock&quot;</code>.</li>
<li>Look up the parent of each <code>&lt;pid&gt;</code>.</li>
<li>Quit that session or editor.</li>
<li>Run <code>lsof</code> again until it prints nothing.</li>
</ol>
<h2 id="record-free-space-before-pruning">Record free space before pruning<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#record-free-space-before-pruning"
     aria-label="Link to section: Record free space before pruning" data-pagefind-ignore></a>
</h2>
<p>The comparison needs readings from before the prune, so take them now and save the output:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">df</span> <span class="console__token">-h</span> <span class="console__token">/</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">uv</span> <span class="console__token">cache</span> <span class="console__token">size</span> <span class="console__token">-H</span></span></code></pre>
    </div>
  </div></div><h2 id="run-the-prune">Run the prune<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#run-the-prune"
     aria-label="Link to section: Run the prune" data-pagefind-ignore></a>
</h2>
<p>This command deletes cached environments. With nothing running, it removed every environment in the cache, not only the ones that no process referenced. The next launch of each MCP server builds a fresh environment. Run it from a plain Terminal window, not from inside one of the sessions you quit:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">uv</span> <span class="console__token">cache</span> <span class="console__token">prune</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">Pruning</span> <span class="console__token">cache</span> <span class="console__token">at:</span> <span class="console__token">.cache/uv</span>
</span><span class="line"><span class="console__token">Removed</span> <span class="console__token">7278379</span> <span class="console__token">files</span> <span class="console__token">(111.1GiB)</span></span></code></pre>
    </div>
  </div></div><p>It took 409 seconds. Do not interrupt it.</p>
<h2 id="check-the-space-you-got-back">Check the space you got back<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#check-the-space-you-got-back"
     aria-label="Link to section: Check the space you got back" data-pagefind-ignore></a>
</h2>
<p>The free space went up by much less than 111.1 GiB. Run the same three commands again and compare them with the readings you saved:</p>
<div class="table-wrap" data-scrollable data-label="Table: Reading">
  <table>
    <thead>
      <tr><th scope="col">Reading</th><th scope="col">Before</th><th scope="col">After</th></tr>
    </thead>
    <tbody>
      <tr><td><code>df -h /</code>, available</td><td>36Gi</td><td>61Gi</td></tr>
      <tr><td>Container Free Space</td><td>38.4 GB (38,372,454,400 bytes)</td><td>65.8 GB (65,847,853,056 bytes)</td></tr>
      <tr><td><code>uv cache size -H</code></td><td>132.7GiB</td><td>3.9GiB</td></tr>
    </tbody>
  </table>
</div>
<p>The container gained 27.5 GB. uv reported 111.1 GiB removed, which is about 119 GB. uv prints binary units (GiB, 2^30 bytes) and <code>diskutil</code> prints decimal ones (GB), so do not compare the two figures as equals. Even in the same unit, the disk got back about a quarter of what uv reported.</p>
<p>The explanation that fits is the link mode; I didn&rsquo;t test it directly. uv&rsquo;s default on macOS is <code>clone</code>, per <a href="https://docs.astral.sh/uv/reference/settings/#link-mode" rel="external noopener" target="_blank">uv&rsquo;s settings reference<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>, which makes APFS copy-on-write clones. Environments share blocks with each other and with the cached wheels. uv 0.11.12 counts every cloned file at its full size, and deleting a clone frees nothing when another file still uses its blocks. <a href="https://docs.astral.sh/uv/concepts/cache/" rel="external noopener" target="_blank">uv&rsquo;s cache documentation<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a> describes a <code>cache-physical-space</code> preview feature that accounts for copy-on-write clones; I didn&rsquo;t test it.</p>
<p><code>du -sh</code> agreed with <code>uv cache size</code> at 3.9G after the prune. That is a drop of 128.8 GiB from 132.7GiB, while prune printed 111.1GiB removed; I did not find why the two differ.</p>
<p>A local snapshot could also hold space after a delete. On this Mac, <code>tmutil listlocalsnapshots /</code> listed none, and <code>diskutil apfs listSnapshots</code> showed none on the data volume, so no snapshot was holding any.</p>
<h2 id="confirm-your-mcp-servers-still-start">Confirm your MCP servers still start<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#confirm-your-mcp-servers-still-start"
     aria-label="Link to section: Confirm your MCP servers still start" data-pagefind-ignore></a>
</h2>
<p>The prune left <code>archive-v0</code> with 540 entries and no environments, and emptied <code>environments-v2</code>. Start each agent or editor that uses MCP servers and open a session. Each server builds a fresh environment on its next launch; on this Mac, one appeared at the next session start. Check:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">find</span> <span class="console__token">&#34;$(uv</span> <span class="console__token">cache</span> <span class="console__token">dir)&#34;/archive-v0</span> <span class="console__token">-maxdepth</span> <span class="console__token">2</span> <span class="console__token">-name</span> <span class="console__token">pyvenv.cfg</span> <span class="console__token">|</span> <span class="console__token">wc</span> <span class="console__token">-l</span></span></code></pre>
    </div>
  </div></div><p>A count above zero means at least one server built an environment. Check each agent&rsquo;s MCP server list or status view for errors.</p>
<h2 id="do-this-with-a-coding-agent">Do this with a coding agent<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#do-this-with-a-coding-agent"
     aria-label="Link to section: Do this with a coding agent" data-pagefind-ignore></a>
</h2>
<p>Paste this prompt into your own local coding agent. It measures and reports, and it proposes before anything is removed:</p>
<div class="code-block" data-copyable data-copy-label="Text">
  <div class="code-block__head"><span class="code-block__lang">Text</span>
  </div>
  <div class="code-block__scroll">
    <div data-copy-source><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Investigate my uv cache on this Mac. Measure and report only; change nothing yet.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">1. Report the cache directory (uv cache dir) and its size (uv cache size -H).
</span></span><span class="line"><span class="cl">2. Report how many entries in archive-v0 are Python environments (a pyvenv.cfg
</span></span><span class="line"><span class="cl">   at the root), and which tools they belong to (the executables in their bin
</span></span><span class="line"><span class="cl">   directories).
</span></span><span class="line"><span class="cl">3. Report free space two ways: df -h / and diskutil info / (Container Free
</span></span><span class="line"><span class="cl">   Space).
</span></span><span class="line"><span class="cl">4. List every process holding the cache lock (lsof on the .lock file in the
</span></span><span class="line"><span class="cl">   cache directory), and for each one its parent process, so I can tell which
</span></span><span class="line"><span class="cl">   agent or editor session to quit.
</span></span><span class="line"><span class="cl">5. Separate what is safe from what is in use: running uv processes, open agent
</span></span><span class="line"><span class="cl">   or editor sessions, and any project whose own virtual environment lives
</span></span><span class="line"><span class="cl">   inside the cache. If this session is itself one of the lock holders, say so
</span></span><span class="line"><span class="cl">   and stop; I will run the prune from a plain Terminal.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">Then propose each removal as a separate item, with the command and the current
</span></span><span class="line"><span class="cl">cache size as an upper bound. uv has no dry run, so do not state an expected
</span></span><span class="line"><span class="cl">figure, and note that APFS clones make the real gain smaller. Remove nothing until I approve that item. Remove only
</span></span><span class="line"><span class="cl">through uv&#39;s own command (uv cache prune). Never delete files under the cache
</span></span><span class="line"><span class="cl">directory by hand and never use --force. Afterwards, report free space again
</span></span><span class="line"><span class="cl">with the same two readings and say how far the figure uv printed is from the
</span></span><span class="line"><span class="cl">space actually gained.</span></span></code></pre></div></div>
  </div>
</div><h2 id="common-failures">Common failures<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#common-failures"
     aria-label="Link to section: Common failures" data-pagefind-ignore></a>
</h2>
<h3 id="cache-is-currently-in-use-waiting-for-other-uv-processes-to-finish">Cache is currently in-use, waiting for other uv processes to finish<a class="heading-anchor" href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#cache-is-currently-in-use-waiting-for-other-uv-processes-to-finish"
     aria-label="Link to section: Cache is currently in-use, waiting for other uv processes to finish" data-pagefind-ignore></a>
</h3>
<div class="console console--error"><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Error</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">Cache</span> <span class="console__token">is</span> <span class="console__token">currently</span> <span class="console__token">in-use,</span> <span class="console__token">waiting</span> <span class="console__token">for</span> <span class="console__token">other</span> <span class="console__token">uv</span> <span class="console__token">processes</span> <span class="console__token">to</span> <span class="console__token">finish</span> <span class="console__token">(use</span> <span class="console__token">`--force`</span> <span class="console__token">to</span> <span class="console__token">override)</span></span></code></pre>
    </div>
  </div></div><p>Another uv process holds the cache lock, and <code>uv cache prune</code> and <code>uv cache clean</code> wait for it. Run <code>lsof &quot;$(uv cache dir)/.lock&quot;</code>, quit the session that owns each holder as described earlier, and run the command again. Nothing was changed while it waited: I stopped a prune that had waited eight seconds, and the cache was unchanged.</p>
<p>These <code>uv cache</code> commands give up after a timeout; <a href="https://docs.astral.sh/uv/concepts/cache/" rel="external noopener" target="_blank">uv&rsquo;s cache documentation<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a> gives its value and the <code>UV_LOCK_TIMEOUT</code> environment variable that changes it. Waiting longer does not help while a session still runs its server.</p>
<p>Do not use <code>--force</code>. The documentation reserves it for cases where no other uv process is reading or writing the cache, and a running <code>uvx</code> server is exactly such a process.</p>
]]></content:encoded>
    </item>
    
    <item>
      <title>Which Xcode Simulators, Runtimes and DeviceSupport Folders Can You Delete?</title>
      <link>https://looselydecoupled.com/xcode-storage-simulators-device-support/</link>
      <guid isPermaLink="true">https://looselydecoupled.com/xcode-storage-simulators-device-support/</guid>
      <pubDate>Fri, 16 Oct 2026 00:00:00 +0000</pubDate>
      <dc:creator>Emmanuel Tsouris</dc:creator>
      <category>Disk space</category>
      <category>Xcode</category>
      
      <description>You measure Xcode&#39;s simulators, runtimes and DeviceSupport and delete what nothing uses, including the runtime images a du of your home folder misses.</description>
      <content:encoded><![CDATA[<div class="answer" data-answer="true">
  <p class="answer__label" data-pagefind-ignore>TL;DR</p>
  <p>Xcode keeps simulator devices, simulator runtimes and DeviceSupport (debug symbols copied from your physical devices) in three separate places, and one <code>du</code> total hides which is big. Measure each on its own. Skip <code>du</code> on <code>/Library/Developer/CoreSimulator/Volumes</code>: it walks into the mounted runtime images and reports their unpacked contents, not the disk they use.</p>
<p>Delete only what no test target or connected device uses:</p>
<ul>
<li>A simulator device: <code>xcrun simctl delete &lt;UDID&gt;</code>.</li>
<li>A simulator runtime: <code>xcrun simctl runtime delete</code>, with <code>--dry-run</code> first.</li>
<li>A DeviceSupport folder: move it to the Trash.</li>
</ul>
<p>Compare Container Free Space before and after. A deleted runtime can leave the list and still hold its space, so reread later.</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-sh</span> <span class="console__token">~/Library/Developer/CoreSimulator/Devices</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">xcrun</span> <span class="console__token">simctl</span> <span class="console__token">runtime</span> <span class="console__token">list</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-sh</span> <span class="console__token">/System/Library/AssetsV2/com_apple_MobileAsset_*SimulatorRuntime</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-sh</span> <span class="console__token">~/Library/Developer/Xcode/*DeviceSupport</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span></span></code></pre>
    </div>
  </div></div><div class="tested" id="tested">
  <p class="label label--seam">Tested with</p><dl class="tested__rows">
    <div class="tested__row"><dt>macOS</dt> <dd>27.0.1, Apple silicon</dd></div>
    <div class="tested__row"><dt>Xcode</dt> <dd>27.0 (27A266a)</dd></div>
    <div class="tested__row"><dt>Date</dt> <dd>October 2026</dd></div>
  </dl>
</div>

</div>

<p>A <code>du</code> of the home folder, as in <a href="https://looselydecoupled.com/mac-disk-full-developer-caches/">What&rsquo;s Taking Up All the Space on My Developer Mac?</a>, shows two of Xcode&rsquo;s three places. The third, simulator runtimes, lives outside the home folder. To get a real before-and-after without touching anything I use, I installed a watchOS 27.0 runtime for this page and removed it again. This is part of a series on <a href="https://looselydecoupled.com/series/developer-mac-disk-cleanup/">cleaning up a developer Mac&rsquo;s disk</a>, and each part stands alone.</p>
<h2 id="check-how-much-space-simulators-and-devicesupport-use">Check how much space simulators and <code>DeviceSupport</code> use<a class="heading-anchor" href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#check-how-much-space-simulators-and-devicesupport-use"
     aria-label="Link to section: Check how much space simulators and DeviceSupport use" data-pagefind-ignore></a>
</h2>
<p>Xcode keeps simulator devices, simulator runtimes and DeviceSupport in three places, and each holds something different:</p>
<div class="table-wrap" data-scrollable data-label="Table: Item">
  <table>
    <thead>
      <tr><th scope="col">Item</th><th scope="col">What it holds</th><th scope="col">Where</th></tr>
    </thead>
    <tbody>
      <tr><td>Simulator devices</td><td>Each simulated iPhone, iPad or Apple TV, with its apps and data</td><td><code>~/Library/Developer/CoreSimulator/Devices</code></td></tr>
      <tr><td>Simulator runtimes</td><td>The OS images the devices boot</td><td>Outside your home folder, under <code>/System/Library/AssetsV2</code></td></tr>
      <tr><td>DeviceSupport</td><td>Debug symbols copied from physical devices you connected</td><td><code>~/Library/Developer/Xcode/iOS DeviceSupport</code> and <code>tvOS DeviceSupport</code></td></tr>
    </tbody>
  </table>
</div>
<p>Record the free space first, so you can check the result later:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span></span></code></pre>
    </div>
  </div></div><p>Then measure the folders. These commands only read:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-sh</span> <span class="console__token">~/Library/Developer/CoreSimulator/Devices</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-sh</span> <span class="console__token">~/Library/Developer/Xcode/*DeviceSupport</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-sh</span> <span class="console__token">~/Library/Developer/Xcode/DerivedData</span> <span class="console__token">~/Library/Developer/Xcode/Archives</span></span></code></pre>
    </div>
  </div></div><p><code>du -h</code> and <code>simctl</code> print binary units, so every G they print on this page is GiB; <code>diskutil</code> prints decimal GB. On my Mac, devices were 44 GiB, <code>iOS DeviceSupport</code> 35 GiB and <code>tvOS DeviceSupport</code> 6.6 GiB. DerivedData was 0B and Archives 10M, so those weren&rsquo;t the problem here; check yours, because on a Mac that builds a lot they can be. The runtimes totaled 22.3G by <code>simctl</code>&rsquo;s count, which the next section shows how to read. Devices, both DeviceSupport folders and runtimes came to about 108 GiB.</p>
<h2 id="find-where-simulator-runtimes-live-and-size-them">Find where simulator runtimes live and size them<a class="heading-anchor" href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#find-where-simulator-runtimes-live-and-size-them"
     aria-label="Link to section: Find where simulator runtimes live and size them" data-pagefind-ignore></a>
</h2>
<p>Runtimes are disk images, and macOS mounts them read-only. List them:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">xcrun</span> <span class="console__token">simctl</span> <span class="console__token">runtime</span> <span class="console__token">list</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">==</span> <span class="console__token">Disk</span> <span class="console__token">Images</span> <span class="console__token">==</span>
</span><span class="line"><span class="console__token">--</span> <span class="console__token">iOS</span> <span class="console__token">--</span>
</span><span class="line"><span class="console__token">iOS</span> <span class="console__token">27.0</span> <span class="console__token">(24A434)</span> <span class="console__token">-</span> <span class="console__token">&lt;runtime-id&gt;</span> <span class="console__token">(Ready)</span>
</span><span class="line"><span class="console__token">iOS</span> <span class="console__token">26.5</span> <span class="console__token">(23F77)</span> <span class="console__token">-</span> <span class="console__token">&lt;runtime-id&gt;</span> <span class="console__token">(Ready)</span>
</span><span class="line"><span class="console__token">--</span> <span class="console__token">tvOS</span> <span class="console__token">--</span>
</span><span class="line"><span class="console__token">tvOS</span> <span class="console__token">27.0</span> <span class="console__token">(24J360)</span> <span class="console__token">-</span> <span class="console__token">&lt;runtime-id&gt;</span> <span class="console__token">(Ready)</span>
</span><span class="line"><span class="console__token">tvOS</span> <span class="console__token">26.5</span> <span class="console__token">(23L470)</span> <span class="console__token">-</span> <span class="console__token">&lt;runtime-id&gt;</span> <span class="console__token">(Ready)</span>
</span><span class="line">
</span><span class="line"><span class="console__token">Total</span> <span class="console__token">Disk</span> <span class="console__token">Images:</span> <span class="console__token">4</span> <span class="console__token">(22.3G)</span></span></code></pre>
    </div>
  </div></div><p>Run it again with <code>-v</code> for each image&rsquo;s details. The <code>-v</code> output adds a <code>Last Used At</code> line per image. It also gives an <code>Image Path</code> under <code>/System/Library/AssetsV2/com_apple_MobileAsset_*SimulatorRuntime/</code> and a <code>Mount Path</code>: under <code>/Library/Developer/CoreSimulator/Volumes/</code> for the iOS and tvOS images here, and under <code>/private/var/run/com.apple.security.cryptexd/mnt/</code> for the watchOS one. The image path is where the bytes are, so size the runtime images there:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-sh</span> <span class="console__token">/System/Library/AssetsV2/com_apple_MobileAsset_*SimulatorRuntime</span></span></code></pre>
    </div>
  </div></div><p>Here that printed 15G for the iOS runtime images and 6.9G for the tvOS ones. These figures are rounded and come from a different tool than the 22.3G total above. Because the images live outside your home folder, a <code>du</code> of <code>~</code> never counts them.</p>
<p>Do not run <code>du</code> on a mount path. <code>du -sh /Library/Developer/CoreSimulator/Volumes</code> printed 48G on this Mac, but that isn&rsquo;t disk use. <code>du</code> walks into each mounted image and counts its unpacked contents, which are already counted in the runtime images. Adding it to the totals counts the runtimes twice, and then some.</p>
<h2 id="delete-simulator-devices-you-no-longer-use">Delete simulator devices you no longer use<a class="heading-anchor" href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#delete-simulator-devices-you-no-longer-use"
     aria-label="Link to section: Delete simulator devices you no longer use" data-pagefind-ignore></a>
</h2>
<p>List the devices, grouped by runtime:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">xcrun</span> <span class="console__token">simctl</span> <span class="console__token">list</span> <span class="console__token">devices</span></span></code></pre>
    </div>
  </div></div><p>I had 27: 11 each on iOS 26.5 and iOS 27.0, 3 on tvOS 26.5 and 2 on tvOS 27.0. A device is worth keeping if you run a test or a preview on it. To see which ones are large, size each device folder; the folder name is the device&rsquo;s UDID, which the list prints in parentheses:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-sh</span> <span class="console__token">~/Library/Developer/CoreSimulator/Devices/*</span> <span class="console__token">|</span> <span class="console__token">sort</span> <span class="console__token">-hr</span> <span class="console__token">|</span> <span class="console__token">head</span></span></code></pre>
    </div>
  </div></div><p>By runtime, the iOS 26.5 devices took 19.9 GiB, iOS 27.0 19.1 GiB, tvOS 26.5 3.6 GiB and tvOS 27.0 1.3 GiB. The largest single device was 5.0 GiB. For scale, one watchOS device I booted for about 80 seconds grew from 8 KiB to 546 MiB. If you no longer test on a runtime, its devices are the candidates, and so is the runtime itself.</p>
<p>Deleting a device removes its installed apps and data. Two commands delete devices. <code>xcrun simctl delete &lt;UDID&gt;</code> removes the devices you name. Use the UDID, not the name, because the same device name appears under every runtime. There&rsquo;s no undo, so copy out any test data you want first. <code>xcrun simctl delete unavailable</code> removes devices that the current Xcode SDK doesn&rsquo;t support, according to <code>xcrun simctl help delete</code>. Check what it would remove before you run it:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">xcrun</span> <span class="console__token">simctl</span> <span class="console__token">list</span> <span class="console__token">devices</span> <span class="console__token">unavailable</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">==</span> <span class="console__token">Devices</span> <span class="console__token">==</span>
</span><span class="line"><span class="console__token">--</span> <span class="console__token">iOS</span> <span class="console__token">26.5</span> <span class="console__token">--</span>
</span><span class="line"><span class="console__token">--</span> <span class="console__token">iOS</span> <span class="console__token">27.0</span> <span class="console__token">--</span>
</span><span class="line"><span class="console__token">--</span> <span class="console__token">tvOS</span> <span class="console__token">26.5</span> <span class="console__token">--</span>
</span><span class="line"><span class="console__token">--</span> <span class="console__token">tvOS</span> <span class="console__token">27.0</span> <span class="console__token">--</span></span></code></pre>
    </div>
  </div></div><p>If every group is empty, as here, <code>delete unavailable</code> removes nothing.</p>
<h2 id="delete-simulator-runtimes-you-no-longer-use">Delete simulator runtimes you no longer use<a class="heading-anchor" href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#delete-simulator-runtimes-you-no-longer-use"
     aria-label="Link to section: Delete simulator runtimes you no longer use" data-pagefind-ignore></a>
</h2>
<p>A runtime is in use if a test target needs that OS version or a device you keep still runs on it. <code>Last Used At</code> in <code>xcrun simctl runtime list -v</code> shows when each image was last used.</p>
<p><code>xcrun simctl runtime delete</code> removes one. It takes an identifier from the list, or a filter: <code>--notUsedSinceDays &lt;days&gt;</code>, <code>--unusable</code> or <code>--outdated</code>. Add <code>--dry-run</code> and it prints what it would delete and deletes nothing:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">xcrun</span> <span class="console__token">simctl</span> <span class="console__token">runtime</span> <span class="console__token">delete</span> <span class="console__token">--notUsedSinceDays</span> <span class="console__token">90</span> <span class="console__token">--dry-run</span></span></code></pre>
    </div>
  </div></div><p>When the dry run lists what you expect, run the same command without <code>--dry-run</code>, or pass an identifier from <code>xcrun simctl runtime list</code> to remove a single image. Read the whole dry-run list first: a filter can match several runtimes, and each one is a multi-GB download if you need that OS version again. <code>xcrun simctl help runtime</code> says the delete shuts down any booted simulators and unmounts the image first. In my run, a tvOS simulator booted on a different runtime stayed booted, so I can&rsquo;t say which ones it stops. Shut down any simulator holding state you care about first.</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">xcrun</span> <span class="console__token">simctl</span> <span class="console__token">runtime</span> <span class="console__token">delete</span> <span class="console__token">&lt;identifier&gt;</span></span></code></pre>
    </div>
  </div></div><p>Use this command, not <code>rm</code>. The images are mounted and managed by the system, so they aren&rsquo;t folders to remove by hand. To get a runtime back, run <code>xcodebuild -downloadPlatform &lt;iOS|watchOS|tvOS|visionOS&gt;</code>, as in Apple&rsquo;s <a href="https://developer.apple.com/documentation/xcode/installing-additional-simulator-runtimes" rel="external noopener" target="_blank">Installing additional simulator runtimes<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>.</p>
<h2 id="why-a-deleted-simulator-runtime-can-keep-its-disk-space">Why a deleted simulator runtime can keep its disk space<a class="heading-anchor" href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#why-a-deleted-simulator-runtime-can-keep-its-disk-space"
     aria-label="Link to section: Why a deleted simulator runtime can keep its disk space" data-pagefind-ignore></a>
</h2>
<p>A runtime can leave <code>xcrun simctl runtime list</code> while its image stays mounted and keeps its space. Do not read the runtime list as proof you got the space back. Check that the image has left <code>mount</code> and that Container Free Space has risen, and if it hasn&rsquo;t, reread it later and after a restart.</p>
<p>The watchOS 27.0 runtime I installed for this page was a 3.83 GB download; <code>xcrun simctl runtime list -v</code> sized it at 3.6G (GiB), and it cut Container Free Space from 83.9 GB to 80.1 GB. After a dry run that named only that runtime, <code>xcrun simctl runtime delete &lt;identifier&gt;</code> took it off the list within five minutes, but Container Free Space didn&rsquo;t rise by those 3.8 GB in the next 21 minutes. The backing folder under <code>/System/Library/AssetsV2</code> still measured 3,736,360 KiB (3.56 GiB), and the image was still in <code>mount</code>, held by a <code>SimLaunchHost.arm64</code> process that had a library from it mapped. <code>xcrun simctl shutdown all</code> didn&rsquo;t release it. Stopping that process left nothing holding the image, but the image stayed mounted and the space stayed in use for the nine minutes I watched. I didn&rsquo;t test a restart, unmounting the image or restarting the CoreSimulator service, so I can&rsquo;t say what finally frees it.</p>
<h2 id="delete-devicesupport-folders-you-no-longer-need">Delete <code>DeviceSupport</code> folders you no longer need<a class="heading-anchor" href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#delete-devicesupport-folders-you-no-longer-need"
     aria-label="Link to section: Delete DeviceSupport folders you no longer need" data-pagefind-ignore></a>
</h2>
<p>DeviceSupport holds debug symbols copied from physical devices you connected. Each folder is named for the device model, the OS version and the build, and there&rsquo;s one per combination. My <code>iOS DeviceSupport</code> had six folders, at 5.4G to 6.6G each, and <code>tvOS DeviceSupport</code> had two, at 3.4G and 3.2G.</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">ls</span> <span class="console__token">~/Library/Developer/Xcode/iOS\</span> <span class="console__token">DeviceSupport</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">&lt;model&gt;</span> <span class="console__token">26.6</span> <span class="console__token">(&lt;build&gt;)</span>
</span><span class="line"><span class="console__token">&lt;model&gt;</span> <span class="console__token">27.0</span> <span class="console__token">(&lt;build&gt;)</span></span></code></pre>
    </div>
  </div></div><p>A folder is needed while a connected device still runs that OS version, or while you still read crash reports from that version. Xcode uses these symbols to name the system framework frames in a report, and Apple&rsquo;s <a href="https://developer.apple.com/documentation/xcode/adding-identifiable-symbol-names-to-a-crash-report" rel="external noopener" target="_blank">crash report documentation<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a> says to download the device symbols for the report&rsquo;s OS version if it can&rsquo;t. List your connected and paired devices from the terminal, then check each one&rsquo;s OS version on the device itself:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">xcrun</span> <span class="console__token">devicectl</span> <span class="console__token">list</span> <span class="console__token">devices</span></span></code></pre>
    </div>
  </div></div><p>Any folder for a version no device runs now, and that no crash report you still read comes from, is a candidate. If every device you connect is on 27, that&rsquo;s the five iOS 26.x folders (28.1 GiB) and both tvOS 26.6 folders (6.6 GiB). I kept all of mine, because I still need 26.x.</p>
<p><code>simctl</code> doesn&rsquo;t manage these; they&rsquo;re plain folders. Move the one you chose to the Trash in Finder, which leaves you an undo, and empty the Trash after you confirm Xcode still works. Once it&rsquo;s gone, a crash report from a device you no longer have can&rsquo;t be symbolicated from it. I haven&rsquo;t tested what Xcode does the next time you connect a device whose folder you removed, so remove one and check before you clear several.</p>
<h2 id="check-how-much-space-you-got-back">Check how much space you got back<a class="heading-anchor" href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#check-how-much-space-you-got-back"
     aria-label="Link to section: Check how much space you got back" data-pagefind-ignore></a>
</h2>
<p>Run the same command you started with:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span></span></code></pre>
    </div>
  </div></div><p>Mine read 83.9 GB before the watchOS run. Other work on the Mac moves this figure by up to about 1 GB with no action of yours, so a change under that is noise. Reread after a restart if a runtime delete hasn&rsquo;t returned its space. Do not expect the change to match the <code>du</code> totals. Only the container&rsquo;s figure says what the Mac got back.</p>
<h2 id="do-this-with-a-coding-agent">Do this with a coding agent<a class="heading-anchor" href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#do-this-with-a-coding-agent"
     aria-label="Link to section: Do this with a coding agent" data-pagefind-ignore></a>
</h2>
<p>Paste this prompt into your own local coding agent. It measures and recommends, and it removes nothing until you say what to remove:</p>
<div class="code-block" data-copyable data-copy-label="Text">
  <div class="code-block__head"><span class="code-block__lang">Text</span>
  </div>
  <div class="code-block__scroll">
    <div data-copy-source><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Measure Xcode&#39;s disk use on this Mac. Report only; delete nothing until I
</span></span><span class="line"><span class="cl">name what to remove.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">1. Run diskutil info / and record Container Free Space.
</span></span><span class="line"><span class="cl">2. Measure three places separately: simulator devices
</span></span><span class="line"><span class="cl">   (~/Library/Developer/CoreSimulator/Devices), simulator runtimes, and
</span></span><span class="line"><span class="cl">   DeviceSupport (~/Library/Developer/Xcode/*DeviceSupport). For runtimes,
</span></span><span class="line"><span class="cl">   use xcrun simctl runtime list -v and measure each runtime image
</span></span><span class="line"><span class="cl">   under /System/Library/AssetsV2. Do not run du on
</span></span><span class="line"><span class="cl">   /Library/Developer/CoreSimulator/Volumes; it walks into the mounted
</span></span><span class="line"><span class="cl">   images and overstates the size.
</span></span><span class="line"><span class="cl">3. For devices, list them with xcrun simctl list devices, group them by
</span></span><span class="line"><span class="cl">   runtime and report the size of each group. Also run
</span></span><span class="line"><span class="cl">   xcrun simctl list devices unavailable.
</span></span><span class="line"><span class="cl">4. List my connected devices (xcrun devicectl list devices) and ask me for
</span></span><span class="line"><span class="cl">   the OS version of each; do not infer it. Also report which OS versions my test targets and deployment targets
</span></span><span class="line"><span class="cl">   need, from the projects I name or from the project files you can find.
</span></span><span class="line"><span class="cl">5. Recommend removal candidates with a reason for each: devices and runtimes
</span></span><span class="line"><span class="cl">   no target uses, and DeviceSupport folders for OS versions no connected
</span></span><span class="line"><span class="cl">   device runs. Ask me whether I still read crash reports from those
</span></span><span class="line"><span class="cl">   versions, because Xcode needs the folder to symbolicate them. For devices and runtimes, give the simctl command (xcrun
</span></span><span class="line"><span class="cl">   simctl delete &lt;UDID&gt;, or xcrun simctl runtime delete &lt;identifier&gt; after
</span></span><span class="line"><span class="cl">   the same command with --dry-run). For DeviceSupport folders, name the
</span></span><span class="line"><span class="cl">   folder; there is no Apple removal command, and Xcode&#39;s behaviour when
</span></span><span class="line"><span class="cl">   that device reconnects is untested, so propose one folder first. Warn me
</span></span><span class="line"><span class="cl">   that deleting a device removes its apps and data, and that runtime
</span></span><span class="line"><span class="cl">   deletion can shut down booted simulators.
</span></span><span class="line"><span class="cl">6. After a runtime deletion, expect the space to come back late or not
</span></span><span class="line"><span class="cl">   until a restart: reread Container Free Space more than once, and check
</span></span><span class="line"><span class="cl">   whether the image is still mounted (mount | grep -i &lt;platform&gt;).
</span></span><span class="line"><span class="cl">7. Note that a du total is not what deleting frees; only the change in
</span></span><span class="line"><span class="cl">   Container Free Space is.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">Then stop and wait. After I name what to remove, run only those removals,
</span></span><span class="line"><span class="cl">one at a time, with --dry-run first for runtimes, and stop if any output is
</span></span><span class="line"><span class="cl">not what you expected. Then read Container Free Space again and report the
</span></span><span class="line"><span class="cl">difference.</span></span></code></pre></div></div>
  </div>
</div><h2 id="common-failures">Common failures<a class="heading-anchor" href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#common-failures"
     aria-label="Link to section: Common failures" data-pagefind-ignore></a>
</h2>
<h3 id="du-reports-the-coresimulatorvolumes-folder-as-larger-than-the-runtimes">du reports the <code>CoreSimulator/Volumes</code> folder as larger than the runtimes<a class="heading-anchor" href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#du-reports-the-coresimulatorvolumes-folder-as-larger-than-the-runtimes"
     aria-label="Link to section: du reports the CoreSimulator/Volumes folder as larger than the runtimes" data-pagefind-ignore></a>
</h3>
<p><code>du</code> followed the mounts into the runtime images and counted their contents. Measure the runtime images under <code>/System/Library/AssetsV2</code> instead, as in the section on where simulator runtimes live.</p>
<h3 id="runtime-deleted-but-the-space-didnt-come-back">Runtime deleted but the space didn&rsquo;t come back<a class="heading-anchor" href="https://looselydecoupled.com/xcode-storage-simulators-device-support/#runtime-deleted-but-the-space-didnt-come-back"
     aria-label="Link to section: Runtime deleted but the space didn’t come back" data-pagefind-ignore></a>
</h3>
<p><code>xcrun simctl runtime list</code> no longer shows the runtime, yet Container Free Space hasn&rsquo;t risen and the folder under <code>/System/Library/AssetsV2</code> is the same size. The image can stay mounted while a <code>SimLaunchHost</code> process has a file from it open. Check with <code>mount | grep -i &lt;platform&gt;</code> and <code>lsof +D &lt;mount path&gt;</code>. In my run, shutting down all simulators and stopping that process still didn&rsquo;t free it, and I didn&rsquo;t test a restart. See the section on why a deleted runtime can keep its disk space.</p>
]]></content:encoded>
    </item>
    
    <item>
      <title>What&#39;s Taking Up All the Space on My Developer Mac?</title>
      <link>https://looselydecoupled.com/mac-disk-full-developer-caches/</link>
      <guid isPermaLink="true">https://looselydecoupled.com/mac-disk-full-developer-caches/</guid>
      <pubDate>Thu, 15 Oct 2026 00:00:00 +0000</pubDate>
      <dc:creator>Emmanuel Tsouris</dc:creator>
      <category>Disk space</category>
      
      <description>Find which developer tool is filling your Mac&#39;s disk, such as uv, Xcode or Docker, and which cleanup applies.</description>
      <content:encoded><![CDATA[<div class="answer" data-answer="true">
  <p class="answer__label" data-pagefind-ignore>TL;DR</p>
  <p>Record the free space first. Then run <code>du</code> one directory level at a time until a directory belongs to one tool. The tool that owns the directory decides which cleanup you need. Clean the cache with that tool&rsquo;s own command, where the tool has one. Do not run <code>rm</code> on a cache that a tool manages. Record the free space again afterward. The space the cleanup reports is not the space the Mac got back.</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-hd</span> <span class="console__token">1</span> <span class="console__token">~</span> <span class="console__token">2&gt;/dev/null</span> <span class="console__token">|</span> <span class="console__token">sort</span> <span class="console__token">-hr</span> <span class="console__token">|</span> <span class="console__token">head</span> <span class="console__token">-15</span></span></code></pre>
    </div>
  </div></div><div class="tested" id="tested">
  <p class="label label--seam">Tested with</p><dl class="tested__rows">
    <div class="tested__row"><dt>macOS</dt> <dd>27.0.1, MacBook Pro (Apple silicon)</dd></div>
    <div class="tested__row"><dt>Date</dt> <dd>October 2026</dd></div>
  </dl>
</div>

</div>

<p>My Mac had 37.7 GB free on a 1 TB disk. I expected Xcode to be the reason,
since I keep a full set of iOS simulators, and Xcode did hold 79 GiB. The
largest directory was a 132 GiB uv cache, which I had never thought about: most
of the entries in it were environments <code>uvx</code> had built for MCP servers,
covered in <a href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/">why the uv cache is so large</a>.
Which directory is largest on your Mac depends on what you build and which
tools you run. The method for finding it is below, and the
<a href="https://looselydecoupled.com/series/developer-mac-disk-cleanup/">series</a> covers each cause.</p>
<h2 id="record-the-free-space-before-you-start">Record the free space before you start<a class="heading-anchor" href="https://looselydecoupled.com/mac-disk-full-developer-caches/#record-the-free-space-before-you-start"
     aria-label="Link to section: Record the free space before you start" data-pagefind-ignore></a>
</h2>
<p>On a modern Mac, <code>df -h /</code> reports the sealed system volume, so its <code>Used</code>
column is misleading:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">df</span> <span class="console__token">-h</span> <span class="console__token">/</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">Filesystem</span>        <span class="console__token">Size</span>    <span class="console__token">Used</span>   <span class="console__token">Avail</span> <span class="console__token">Capacity</span> <span class="console__token">iused</span> <span class="console__token">ifree</span> <span class="console__token">%iused</span>  <span class="console__token">Mounted</span> <span class="console__token">on</span>
</span><span class="line"><span class="console__token">/dev/disk3s1s1</span>   <span class="console__token">926Gi</span>    <span class="console__token">13Gi</span>    <span class="console__token">40Gi</span>    <span class="console__token">24%</span>    <span class="console__token">484k</span>  <span class="console__token">423M</span>    <span class="console__token">0%</span>   <span class="console__token">/</span></span></code></pre>
    </div>
  </div></div><p><code>/</code> is the sealed system snapshot. Your files live on the Data volume in the
same APFS container. Every volume in a container draws on one pool of free
space, so <code>Used</code> for <code>/</code> counts the system alone, and <code>Avail</code> is the pool. The
container&rsquo;s own figure comes from the startup disk&rsquo;s container only, so an
external APFS drive cannot be mistaken for it:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line">   <span class="console__token">Container</span> <span class="console__token">Free</span> <span class="console__token">Space:</span>      <span class="console__token">65.8</span> <span class="console__token">GB</span> <span class="console__token">(65847853056</span> <span class="console__token">Bytes)</span> <span class="console__token">(exactly</span> <span class="console__token">128609088</span> <span class="console__token">512-Byte-Units)</span></span></code></pre>
    </div>
  </div></div><p>This reading was taken after the cleanup, so it does not match the <code>df</code>
output above, which was taken partway through, or the 37.7 GB before any
cleanup. <code>df -h</code> prints GiB and
<code>diskutil</code> prints GB, so the same moment looks different in the two units. Use one of them for every reading, or the difference
between the units looks like progress. A Mac keeps writing while you work, so
treat a change of a gigabyte or two as noise.</p>
<h2 id="find-whats-taking-up-space-with-du">Find what&rsquo;s taking up space with du<a class="heading-anchor" href="https://looselydecoupled.com/mac-disk-full-developer-caches/#find-whats-taking-up-space-with-du"
     aria-label="Link to section: Find what’s taking up space with du" data-pagefind-ignore></a>
</h2>
<p><code>du</code> reads sizes and changes nothing. <code>2&gt;/dev/null</code> hides the permission
errors that protected directories print.</p>
<!-- style-check: procedure -->
<ol>
<li>
<p>List the largest directories in your home directory:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-hd</span> <span class="console__token">1</span> <span class="console__token">~</span> <span class="console__token">2&gt;/dev/null</span> <span class="console__token">|</span> <span class="console__token">sort</span> <span class="console__token">-hr</span> <span class="console__token">|</span> <span class="console__token">head</span> <span class="console__token">-15</span></span></code></pre>
    </div>
  </div></div></li>
<li>
<p>Skip the first line, which is the total for the directory you ran it on.
Run the same command on the largest directory below it, and repeat until
the directory belongs to one tool. On this Mac, that took three levels:
<code>~/.cache</code>, then <code>~/.cache/uv</code>, then <code>~/.cache/uv/archive-v0</code>.</p>
</li>
<li>
<p>Check the two places that hide the most, even if they didn&rsquo;t top the first
list:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-hd</span> <span class="console__token">1</span> <span class="console__token">~/Library/Caches</span> <span class="console__token">2&gt;/dev/null</span> <span class="console__token">|</span> <span class="console__token">sort</span> <span class="console__token">-hr</span> <span class="console__token">|</span> <span class="console__token">head</span> <span class="console__token">-15</span>
</span><span class="line"><span class="prompt">$ </span><span class="console__token">du</span> <span class="console__token">-hd</span> <span class="console__token">1</span> <span class="console__token">~/Library/Developer</span> <span class="console__token">2&gt;/dev/null</span> <span class="console__token">|</span> <span class="console__token">sort</span> <span class="console__token">-hr</span></span></code></pre>
    </div>
  </div></div></li>
<li>
<p>For a package manager, ask the tool where its cache is rather than
assuming a path. pip on macOS uses <code>~/Library/Caches/pip</code>, not
<code>~/.cache/pip</code>:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">uv</span> <span class="console__token">cache</span> <span class="console__token">dir</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">/Users/&lt;user&gt;/.cache/uv</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">python3</span> <span class="console__token">-m</span> <span class="console__token">pip</span> <span class="console__token">cache</span> <span class="console__token">dir</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">/Users/&lt;user&gt;/Library/Caches/pip</span></span></code></pre>
    </div>
  </div></div></li>
</ol>
<!-- style-check: end procedure -->
<p>A <code>du</code> total is an upper bound on what deleting frees. APFS clones share
their blocks with the original until one of them changes, and <code>du</code> counts a
cloned file at full size wherever it appears.</p>
<h2 id="match-the-directory-to-its-cause">Match the directory to its cause<a class="heading-anchor" href="https://looselydecoupled.com/mac-disk-full-developer-caches/#match-the-directory-to-its-cause"
     aria-label="Link to section: Match the directory to its cause" data-pagefind-ignore></a>
</h2>
<p>These are the directories that were large on this Mac, and the article in this
series that covers each one:</p>
<div class="table-wrap" data-scrollable data-label="Table: Directory and what fills it">
  <table>
    <thead>
      <tr><th scope="col">Directory and what fills it</th><th class="align-right" scope="col">Size here</th><th scope="col">Covered in</th></tr>
    </thead>
    <tbody>
      <tr><td><code>~/.cache/uv</code><br>Environments that <code>uvx</code> builds for MCP servers</td><td class="align-right">132 GiB</td><td><a href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/">The uv cache</a></td></tr>
      <tr><td><code>~/Library/Developer/CoreSimulator/Devices</code><br>iOS simulators and the apps installed in them</td><td class="align-right">44 GiB</td><td><a href="https://looselydecoupled.com/xcode-storage-simulators-device-support/">Xcode storage</a></td></tr>
      <tr><td><code>~/Library/Developer/Xcode/iOS DeviceSupport</code><br>Debug symbols for each device and iOS version you&rsquo;ve connected</td><td class="align-right">35 GiB</td><td><a href="https://looselydecoupled.com/xcode-storage-simulators-device-support/">Xcode storage</a></td></tr>
      <tr><td><code>~/Library/Containers/com.docker.docker</code><br>Docker Desktop&rsquo;s VM disk, <code>Docker.raw</code></td><td class="align-right">32 GiB</td><td><a href="https://looselydecoupled.com/docker-desktop-disk-space-mac/">Docker.raw</a></td></tr>
      <tr><td><code>~/.npm/_npx</code><br>Packages that <code>npx</code> runs, MCP servers among them</td><td class="align-right">8.9 GiB</td><td>The npx directory, not yet published</td></tr>
      <tr><td><code>.build</code>, <code>node_modules</code>, <code>.venv</code> in your projects<br>Build output and dependencies, including projects you no longer work on</td><td class="align-right">varies</td><td><a href="https://looselydecoupled.com/delete-build-folders-old-projects-mac/">Old build folders</a></td></tr>
      <tr><td><code>~/Library/Caches/Homebrew</code><br>Cached downloads of formulae and casks</td><td class="align-right">1.1 GiB</td><td><a href="https://looselydecoupled.com/mac-disk-full-developer-caches/#clear-homebrew-downloads-and-ollama-logs">Below</a></td></tr>
      <tr><td><code>~/.ollama/logs</code><br>Ollama&rsquo;s server and app logs</td><td class="align-right">947 MB</td><td><a href="https://looselydecoupled.com/mac-disk-full-developer-caches/#clear-homebrew-downloads-and-ollama-logs">Below</a></td></tr>
    </tbody>
  </table>
</div>
<p>For the uv cache, read <a href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/">Why the uv Cache Is So Large on a Mac, and How to Prune It Safely</a>
before you prune: a running coding session holds a lock that makes the prune
wait, and the prune reports far more than the disk gets back. The other parts
are listed on the series page.</p>
<p>Some directories stay whatever their size. A Docker volume holds an app&rsquo;s
data, not cache. An app&rsquo;s <code>Application Support</code> directory holds its state.</p>
<h2 id="clear-homebrew-downloads-and-ollama-logs">Clear Homebrew downloads and Ollama logs<a class="heading-anchor" href="https://looselydecoupled.com/mac-disk-full-developer-caches/#clear-homebrew-downloads-and-ollama-logs"
     aria-label="Link to section: Clear Homebrew downloads and Ollama logs" data-pagefind-ignore></a>
</h2>
<p>Two directories on the list need no part of their own.</p>
<p><code>brew cleanup -s</code> removes old versions and the cached downloads of anything no
longer installed. It keeps the downloads of what is installed now, so on this
Mac it freed about 270 MB of the 1.1 GiB:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">brew</span> <span class="console__token">cleanup</span> <span class="console__token">-s</span></span></code></pre>
    </div>
  </div></div><p>An app can keep its data somewhere else and still write its logs to the
internal disk. My Ollama models live on an external SSD, linked into place:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">ls</span> <span class="console__token">-ld</span> <span class="console__token">~/.ollama/models</span></span></code></pre>
    </div>
  </div><div class="code-block code-block--wrap console__output">
    <p class="console__output-label">Output</p>
    <div class="code-block__scroll"><pre><code><span class="line"><span class="console__token">lrwxr-xr-x</span>  <span class="console__token">1</span> <span class="console__token">&lt;user&gt;</span>  <span class="console__token">staff</span>  <span class="console__token">...</span> <span class="console__token">/Users/&lt;user&gt;/.ollama/models</span> <span class="console__token">-&gt;</span> <span class="console__token">/Volumes/&lt;drive&gt;/ollama/models</span></span></code></pre>
    </div>
  </div></div><p>The logs aren&rsquo;t linked. List them first:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">ls</span> <span class="console__token">-lh</span> <span class="console__token">~/.ollama/logs</span></span></code></pre>
    </div>
  </div></div><p>Here they had reached 947 MB in two files, <code>server-1.log</code> and <code>app-1.log</code>.
Yours may have other names. Ollama has no cleanup command for them, so quit
Ollama and delete the files that list showed, by name:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">rm</span> <span class="console__token">~/.ollama/logs/server-1.log</span> <span class="console__token">~/.ollama/logs/app-1.log</span></span></code></pre>
    </div>
  </div></div><p>Deleting a log leaves the models and the settings as they are.</p>
<p>Ollama wasn&rsquo;t in Open at Login, but App Background Activity, under System
Settings &gt; General &gt; Login Items, allowed it to run in the background. I
turned that off. I didn&rsquo;t check whether background runs are what filled the
logs.</p>
<h2 id="record-the-free-space-again">Record the free space again<a class="heading-anchor" href="https://looselydecoupled.com/mac-disk-full-developer-caches/#record-the-free-space-again"
     aria-label="Link to section: Record the free space again" data-pagefind-ignore></a>
</h2>
<p>Run the same command you started with:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">diskutil</span> <span class="console__token">info</span> <span class="console__token">/</span> <span class="console__token">|</span> <span class="console__token">grep</span> <span class="console__token">&#34;Container</span> <span class="console__token">Free</span> <span class="console__token">Space&#34;</span></span></code></pre>
    </div>
  </div></div><p>Here it went from 37.7 GB before any cleanup to 65.8 GB after the uv prune.
The cleanup commands had reported more than 140 GB between them. A cleanup
command reports what it removed from its own storage; only the container&rsquo;s
figure says what the Mac got back.</p>
<h2 id="do-this-with-a-coding-agent">Do this with a coding agent<a class="heading-anchor" href="https://looselydecoupled.com/mac-disk-full-developer-caches/#do-this-with-a-coding-agent"
     aria-label="Link to section: Do this with a coding agent" data-pagefind-ignore></a>
</h2>
<p>Paste this prompt into your own local coding agent. It finds and reports, and
it deletes nothing:</p>
<div class="code-block" data-copyable data-copy-label="Text">
  <div class="code-block__head"><span class="code-block__lang">Text</span>
  </div>
  <div class="code-block__scroll">
    <div data-copy-source><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Find what is taking up space on this Mac&#39;s internal disk. Measure and report
</span></span><span class="line"><span class="cl">only; delete, prune or clean nothing. Stay in my home directory, and don&#39;t
</span></span><span class="line"><span class="cl">follow links to external drives.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">1. Report free space with diskutil info / (Container Free Space) and
</span></span><span class="line"><span class="cl">   df -h /, and say which units each prints.
</span></span><span class="line"><span class="cl">2. Run du -hd 1 on my home directory, then on the largest subdirectory it
</span></span><span class="line"><span class="cl">   lists (not the total line for the directory itself), and keep going down
</span></span><span class="line"><span class="cl">   until each large directory belongs to one tool. Also check
</span></span><span class="line"><span class="cl">   ~/Library/Caches and ~/Library/Developer. Ask package managers for their
</span></span><span class="line"><span class="cl">   cache paths (for example uv cache dir, python3 -m pip cache dir) instead of
</span></span><span class="line"><span class="cl">   assuming them.
</span></span><span class="line"><span class="cl">3. For each directory over 1 GB, report its size, which tool owns it, what
</span></span><span class="line"><span class="cl">   fills it, and the tool&#39;s own cleanup command if it has one.
</span></span><span class="line"><span class="cl">4. Mark anything that is in use or holds work: running processes using the
</span></span><span class="line"><span class="cl">   directory (lsof), open coding-agent or editor sessions, uncommitted or
</span></span><span class="line"><span class="cl">   unpushed changes in any git checkout, Docker volumes, app data under
</span></span><span class="line"><span class="cl">   Application Support. Say what would be lost if each were removed.
</span></span><span class="line"><span class="cl">5. Note that du counts APFS clones at full size, so a total is an upper bound
</span></span><span class="line"><span class="cl">   on what deleting frees.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">Then stop and wait. I will choose what to clean.</span></span></code></pre></div></div>
  </div>
</div><h2 id="common-failures">Common failures<a class="heading-anchor" href="https://looselydecoupled.com/mac-disk-full-developer-caches/#common-failures"
     aria-label="Link to section: Common failures" data-pagefind-ignore></a>
</h2>
<h3 id="free-space-barely-moved-after-a-cleanup">Free space barely moved after a cleanup<a class="heading-anchor" href="https://looselydecoupled.com/mac-disk-full-developer-caches/#free-space-barely-moved-after-a-cleanup"
     aria-label="Link to section: Free space barely moved after a cleanup" data-pagefind-ignore></a>
</h3>
<p>Docker reports space inside its VM disk, and <code>du</code> and <code>uv cache size</code> count
cloned files at full size. Measure the container with <code>diskutil info /</code>
before and after; that is the only figure that says what the Mac got back.</p>
<p>With Time Machine on, a local snapshot can keep a deleted file&rsquo;s space in use.
Time Machine keeps hourly snapshots for 24 hours and deletes them as they age
or as space is needed, per <a href="https://support.apple.com/en-us/102154" rel="external noopener" target="_blank">Apple&rsquo;s Time Machine guide<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/mac-disk-full-developer-caches/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a>.
List them; on this Mac the list was empty:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">tmutil</span> <span class="console__token">listlocalsnapshots</span> <span class="console__token">/</span></span></code></pre>
    </div>
  </div></div><h3 id="uv-cache-prune-waits-then-times-out">uv cache prune waits, then times out<a class="heading-anchor" href="https://looselydecoupled.com/mac-disk-full-developer-caches/#uv-cache-prune-waits-then-times-out"
     aria-label="Link to section: uv cache prune waits, then times out" data-pagefind-ignore></a>
</h3>
<p><code>uv cache prune</code> waits while any other uv process is running, and every <code>uvx</code>
server counts. After five minutes by default (<code>UV_LOCK_TIMEOUT</code>) it gives up;
the <a href="https://docs.astral.sh/uv/concepts/cache/" rel="external noopener" target="_blank">uv cache documentation<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><use href="https://looselydecoupled.com/mac-disk-full-developer-caches/#i-external-link"/></svg><span class="visually-hidden"> (opens in a new tab)</span></a> covers
the lock. Quit the coding sessions that started the servers, then run it again.
To see what holds the lock:</p>
<div class="console"><div class="code-block code-block--wrap console__command" data-copyable data-copy-label="command">
    <div class="code-block__head"><span class="code-block__lang">Command</span></div>
    <div class="code-block__scroll"><pre data-copy-source><code><span class="line"><span class="prompt">$ </span><span class="console__token">lsof</span> <span class="console__token">&#34;$(uv</span> <span class="console__token">cache</span> <span class="console__token">dir)/.lock&#34;</span></span></code></pre>
    </div>
  </div></div><p><a href="https://looselydecoupled.com/uv-cache-huge-mac-uvx-mcp-servers/">Why the uv Cache Is So Large on a Mac, and How to Prune It Safely</a> shows how to find which session
holds it.</p>
<h3 id="npm-cache-clean-left-npm-large">npm cache clean left ~/.npm large<a class="heading-anchor" href="https://looselydecoupled.com/mac-disk-full-developer-caches/#npm-cache-clean-left-npm-large"
     aria-label="Link to section: npm cache clean left ~/.npm large" data-pagefind-ignore></a>
</h3>
<p><code>npm cache clean --force</code> empties npm&rsquo;s package cache, <code>_cacache</code>. The space
is in <code>_npx</code>, where npx
keeps the packages it runs. The series&rsquo; article on the npx directory, not yet
published, covers it.</p>
]]></content:encoded>
    </item>
    
  </channel>
</rss>
