podman-disk-reclaim
Skill0 starsChanged 31 days agoMITView on GitHub
Use this skill when Podman eats too much disk on Windows, macOS, or Linux. Triggers include "podman storage too big", a Podman machine disk or ext4.vhdx that keeps growing, a drive filling up, too many container images, or any request to prune, clean up, shrink, or compact Podman. One cross-platform Python script prunes unused images (stopped containers and volumes only on request), runs fstrim inside the Podman machine, and on Windows compacts the WSL vhdx with diskpart so the space actually returns to the host. Pruning alone does NOT shrink a WSL vhdx; this skill handles every step.
In this repository8 other files it gives its agents.
- dependency-vuln-explainerSkill
- design-coreSkill
- design-flowSkill
- doc-style-builderSkill
- pdf-operationsSkill
- poc-spec-driven-builderSkill
- prompt-cache-kitSkill
- thai-mock-namingSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 68
Test: python tests/test_reclaim.py or pytest tests.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Podman Disk Reclaim
scripts/reclaim.py uses only the Python standard library (3.9+). What it does depends on the OS:
| OS | Where Podman storage lives | Steps the script runs |
| Linux | Host filesystem, native Podman | prune |
| macOS | Podman machine, sparse raw disk | prune, fstrim in the machine |
| Windows | Podman machine, WSL2 ext4.vhdx | prune, fstrim, stop, wsl --shutdown, diskpart compact, start |
On Windows, the WSL vhdx grows but never shrinks. podman system prune frees space inside the VM, but the host file stays the same size until it is compacted.
Workflow
1. Measure first (always)
python scripts/reclaim.py --dry-runThis prints podman system df, the vhdx size on the host (Windows only), and the planned steps. It changes nothing. Read the output:
- The vhdx is much bigger than the in-use SIZE. Compaction alone recovers most of the space. Suggest
--skip-pruneif the user wants to keep every image. - RECLAIMABLE is high on Images. A default run is the right call.
2. Confirm before deleting
Pruning images is destructive. Public images are cheap to pull again, but locally built ones are not. Before a real run, show the user what will be removed and get a yes. Ask separately before using either of these flags:
--containersremoves stopped containers along with their writable layers. A stopped dev database is one example of what this deletes.--volumesremoves volumes that no container references. If you combine it with--containers, it also removes the volumes of the containers that were just pruned. That is data loss.
3. Windows: run elevated
diskpart needs Administrator rights. If the current shell is not elevated, give the user the exact command to run in an Administrator terminal:
python <repo>\skills\podman-disk-reclaim\scripts\reclaim.pyWarn the user that the script calls wsl --shutdown. That stops every WSL distro (Ubuntu, Docker Desktop, and others), not just Podman. If they do not want that, --skip-compact prunes without admin rights, but the host file stays the same size.
4. Report
Report the before and after output of podman system df. On Windows, also report the final line: VHDX on host: X GB -> Y GB (freed Z GB).
Flags
| Flag | Effect |
--dry-run | Show sizes and the plan, change nothing |
--skip-prune | Reclaim only, delete nothing |
--skip-compact | Prune only. No admin rights needed, no wsl --shutdown |
--containers | Also prune stopped containers |
--volumes | Also prune unused volumes |
--machine <name> | Target a machine other than podman-machine-default |
Notes
- Do not recreate the machine with a smaller
--disk-sizeto save space. The disk size is a cap, not space that is already allocated. - Windows support covers the WSL machine provider only. A Hyper-V provider machine fails with "WSL distro not found".
- On Windows Home,
Optimize-VHDis missing because there is no Hyper-V module.diskpartships with every edition, which is why the script uses it. - Test:
python tests/test_reclaim.pyorpytest tests.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.