docker-disk-reclaim

Reclaim disk space from Docker Desktop on WSL2 — the space that pruning alone never gives back.

npx docker-disk-reclaim

The problem

Docker Desktop on Windows keeps everything inside a single dynamically expanding virtual disk:

%LOCALAPPDATA%\Docker\wsl\disk\docker_data.vhdx

That file grows but never shrinks on its own. When you delete a volume or prune images, the space is freed inside the Linux filesystem of the VM — but the .vhdx on your Windows drive stays exactly the same size, now full of dead blocks. docker system prune will happily report gigabytes reclaimed while your C: drive gains nothing.

This tool closes that gap. It prunes what you choose, runs fstrim so the virtual disk learns which blocks are actually free, then compacts the .vhdx so Windows gets the space back.

Usage

Run it with no arguments and it shows you what is using space, then asks how far you want to go:

┌  docker-disk-reclaim  Reclaim disk space from Docker Desktop
│
◇  Current usage ──────────────────────────────────────────────────────╮
│                                                                      │
│  Images                              3.36 GB   17.19 GB reclaimable  │
│  Containers                        286.60 MB   286.60 MB reclaimable │
│  Volumes                            51.66 GB   11.79 GB reclaimable  │
│  Build cache                        10.21 GB   4.24 GB reclaimable   │
│                                                                      │
│  Virtual disk (.vhdx)              121.56 GB                         │
│  Used inside the VM                 84.00 GB                         │
│  Dead blocks stuck in the file      37.56 GB                         │
│  Free on host drive                  8.72 GB                         │
│                                                                      │
├──────────────────────────────────────────────────────────────────────╯
│
◆  How far do you want to go?
│  ● Prune images + build cache, then compact
│    Frees ~65 GB. Keeps every volume, so your databases stay intact.
│  ○ Compact only, delete nothing
│  ○ Full cleanup, including unused volumes
│  ○ Let me pick what goes
└

Scopes

| Scope | What it does | |---|---| | compact | Only returns already-dead blocks to Windows. Deletes nothing. | | images | Stopped containers, unused images and build cache, then compacts. Volumes untouched. | | all | Everything above plus every volume with no container attached. Destructive. | | custom | Lists each unused volume with its size so you pick one by one. |

Options

-s, --scan          Only show the report, change nothing
    --scope <name>  Skip the menu and run a scope directly
-y, --yes           Assume yes for every confirmation (for scheduled runs)
    --no-compact    Prune only, never touch the virtual disk
    --keep-images   Keep tagged images, remove only dangling ones
    --dry-run       Show what would happen without doing it
    --lang <pt|en>  Force the interface language
    --json          Print the final report as JSON

The interface speaks English or Portuguese, picked from your system locale. Override with --lang or the DOCKER_DISK_RECLAIM_LANG environment variable.

Running it periodically

--yes skips every prompt, which makes it safe to schedule:

npx docker-disk-reclaim --scope images --yes

To run it monthly with Windows Task Scheduler:

$action  = New-ScheduledTaskAction -Execute 'npx' -Argument 'docker-disk-reclaim --scope images --yes'
$trigger = New-ScheduledTaskTrigger -Weekly -WeeksInterval 4 -DaysOfWeek Sunday -At 9am
Register-ScheduledTask -TaskName 'Docker disk reclaim' -Action $action -Trigger $trigger -RunLevel Highest

-RunLevel Highest matters: without it the compaction step raises a UAC prompt that an unattended task cannot answer. Use --no-compact if you would rather not grant that.

What it actually runs

Nothing is hidden or magic — in order:

1. docker container prune -f
2. docker image prune -af (or -f alone with --keep-images)
3. docker builder prune -af
4. docker volume rm <name> for volumes you explicitly selected
5. fstrim -av inside the Docker VM, so the virtual disk sees the freed blocks
6. Optimize-VHD -Mode Full, falling back to diskpart compact vdisk, in an elevated PowerShell

Step 6 needs administrator rights and stops Docker Desktop first; the tool warns you and offers to start it again afterwards. Steps 1–5 never require elevation.

Development

Written in TypeScript, linted with oxlint.

npm install       # also builds, via the prepare script
npm run build     # tsc -> dist/
npm run typecheck # tsc --noEmit
npm run lint      # oxlint
npm run check     # lint + typecheck
npm start -- --scan

The lint setup runs correctness, suspicious, perf, style and pedantic as errors — 369 rules. restriction is deliberately left off: it is a pick-list rather than a preset, and enabling it wholesale is self-contradictory (import/no-named-export versus import/prefer-default-export) and incompatible with a Node CLI (oxc/no-async-await, import/no-nodejs-modules). The handful of individually disabled rules are listed in .oxlintrc.json, each because it fights this codebase rather than improving it — unicorn/no-null, for instance, because null is load-bearing in the --json report shape, where undefined would silently drop keys.

Requirements

• Node.js 20+
• Docker Desktop
• Windows with the WSL2 backend, for the compaction step

On macOS and Linux the pruning steps still work, but compaction is skipped — the tool says so instead of pretending.

Safety

• Volumes are never deleted unless you pick the all scope or select them by hand, and you get a confirmation showing the count and total size first.
• --dry-run prints the exact plan without touching anything.
• --scan is strictly read-only.
• The compaction step reports the file size before and after, so you can see what was actually returned.

A 13 MB alpine image is pulled when needed to run fstrim inside the VM. Pruning removes it and the next run pulls it again; that is expected.

docker-disk-reclaim (pt-BR)

Recupera espaço em disco do Docker Desktop no WSL2 — o espaço que a poda sozinha nunca devolve.

O problema

O Docker Desktop no Windows guarda tudo dentro de um único disco virtual dinâmico (docker_data.vhdx). Esse arquivo cresce mas nunca encolhe sozinho. Quando você apaga um volume ou poda imagens, o espaço é liberado dentro do sistema de arquivos da VM — mas o .vhdx no seu disco continua do mesmo tamanho, agora cheio de blocos mortos. O docker system prune informa gigabytes recuperados enquanto o seu C: não ganha nada.

Esta ferramenta fecha essa lacuna: poda o que você escolher, roda fstrim para o disco virtual saber quais blocos estão livres e compacta o .vhdx para o Windows receber o espaço de volta.

Uso

npx docker-disk-reclaim

Sem argumentos, ele mostra o que está ocupando espaço e pergunta até onde você quer ir. Os escopos são:

| Escopo | O que faz | |---|---| | compact | Só devolve ao Windows os blocos já mortos. Não apaga nada. | | images | Containers parados, imagens sem uso e cache de build, depois compacta. Não toca em volumes. | | all | Tudo acima mais todo volume sem container ligado. Destrutivo. | | custom | Lista cada volume sem uso com o tamanho para você escolher um a um. |

Para uso agendado, --yes pula todas as perguntas:

npx docker-disk-reclaim --scope images --yes

A compactação exige privilégio de administrador e encerra o Docker Desktop antes; a ferramenta avisa e oferece subir o Docker de novo ao terminar. As etapas de poda nunca precisam de elevação.

Licença

MIT