SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor · Updated 2026-10-14

How to Free VPS Disk Space Wey Docker Dey Use

VPS disk full? Use docker system df to find images, containers, build cache or volumes wey hold space, then prune only wetin safe without losing data.

Find out wetin dey use the disk space before you prune anything

Docker dey use disk space for VPS in four places: images, stopped containers, build cache, and local volumes. Run docker system df first to find out which one dey hold the space, then run the narrowest prune wey go clear am. Order dey matter, because the last command for this guide, docker volume prune -a, dey delete data and you no fit undo am.

Start with the filesystem, no be Docker.

df -h /
sudo du -xh --max-depth=1 /var/lib/docker | sort -h
sudo du -xh --max-depth=1 /var/lib/containerd | sort -h

df dey tell you how bad the situation be. du dey tell you where the space go. The -x flag dey make du stay for one filesystem, so e no go follow mount enter separate volume and count am twice. The directories wey matter depend on the storage backend. For fresh Docker Engine 29.0 or later installation, containerd image store na the default, and image contents plus container snapshots dey live for /var/lib/containerd. Na why the second du line dey there. With either backend, two directories under /var/lib/docker matter: volumes dey hold volume data, while containers dey hold container metadata and log files. Host wey dem upgrade from older Docker dey keep the classic overlay2 layout until you switch am. For that layout, three more directories matter: overlay2 dey hold image and container layers, buildkit dey hold the build cache, and image dey hold layer metadata. docker info | grep -i driver-type dey print io.containerd.snapshotter.v1 for containerd image store and nothing for overlay2. Containerd image store dey keep both the compressed copy and extracted copy of each layer, so the same images dey use more disk than dem use under overlay2.

Make we talk about sudo and shell wildcards, because this one dey waste plenty people time. Root own /var/lib/docker, and your normal user no fit read am, so ls /var/lib/docker returns Permission denied. Command like sudo du -sh /var/lib/docker/* go fail too, because your shell expands * before sudo run, and your shell no fit read that directory. Every command below dey use find or --max-depth instead of wildcard for exactly this reason.

Now make we check Docker own view.

docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          24        6         12.4GB    8.91GB (71%)
Containers      31        6         1.42GB    1.39GB (97%)
Local Volumes   14        5         6.03GB    4.11GB (68%)
Build Cache     212       0         9.87GB    9.87GB

Those figures come from one machine and dem no tell you anything about your own machine. Read the pattern instead. TOTAL dey count objects, ACTIVE dey count the ones wey dey use now, and RECLAIMABLE na Docker estimate of wetin prune fit free from that row.

Two things about RECLAIMABLE dey confuse people. E dey count shared image layers once for every image wey use dem, so the image row usually promise more than wetin you go actually get. And e no ever include container log files, because Docker no treat log file as object wey prune fit reclaim. When du report directory wey big pass wetin docker system df show, na log files cause am, and one section below dey explain this.

Add -v for breakdown of each object.

docker system df -v

This one dey split the summary into one section for each object type. The image section add SHARED SIZE and UNIQUE SIZE columns, so you fit see the real disk space one image dey use. The volume section add a LINKS count. This na the number of containers wey attach to that volume. Remember LINKS, because value of 0 mean no container dey use the volume, and na this condition every volume prune command dey start from.

Dangling images and unused images

These two terms look like say dem mean the same thing, but dem no. The filters behave differently because the objects no be the same.

A dangling image na image wey no get tag. E dey show as <none> for docker images. You create one for every rebuild: docker build -t myapp:latest . moves the myapp:latest tag go the new image, while the old image keeps all its layers but loses its name. Nothing dey reference am, and nothing cleans am up by itself.

An unused image na any image, whether e get tag or not, wey no container currently dey refer to. A postgres:16 wey you pulled last month and no container dey refer to, whether the container dey run or stopped, na unused image, but e no be dangling image.

docker image prune        # dangling images only
docker image prune -a     # every image no container refers to

The second one go ask first.

WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N]

Read that prompt well. "Associated to them" mean an existing container object, whether e dey run or stopped. If you run docker compose down, the containers don disappear, so every image wey those services use don become unused, and -a go delete all of dem. You no lose anything wey you no fit get back, but the next docker compose up -d go pull or rebuild everything again. This one go use bandwidth and build time for small VPS. Na one practical reason to know wetin docker compose down dey remove and wetin stop dey leave running before you prune anything.

A filter fit leave recent images outside the scope.

docker image prune -a --filter "until=240h"

That one removes unused images wey dem create more than 240 hours (10 days) ago and leaves newer ones alone. The until value dey take a Go duration string like 240h, or an absolute timestamp like 2026-08-01T00:00:00.

Wetin build cache be and why e dey grow reach big size

BuildKit na the builder wey Docker dey use by default for docker build and docker compose build since Docker Engine 23.0. E dey cache the result of every step for every Dockerfile wey e run, and for the classic overlay2 layout, e dey keep that cache for /var/lib/docker/buildkit. Na the cache dey make your second build finish within seconds, so e dey do the work wey dem design am for. Docker Engine dey run garbage collection for am by default: e dey remove cache wey nobody don use for 60 days, and e only trim the remaining cache after e pass limits wey Docker Engine calculate from disk size. For small VPS, this fit mean say disk don nearly full already. If you build the same image fifty times with one COPY step wey dey change every time, you go keep fifty sets of layers until collection start.

Build cache no dey show inside docker image prune. E na separate object type wey get its own command.

docker builder prune                        # dangling cache
docker builder prune -a                     # all unused cache
docker builder prune --filter until=168h    # cache untouched for 7 days

None of these go touch your images or your data. The only cost of clearing build cache na say the next build go run slowly one time. For VPS wey dey rebuild images regularly, Build Cache often dey be the biggest row for docker system df, so na the safest big thing wey you fit delete.

Prune commands, wey dey move from safe reach destructive

Work down this list, and stop immediately df -h / don look healthy again. Every command go print one Total reclaimed space: line when e finish.

  1. docker container prune dey remove containers wey don stop. E go remove their writable layers too, so anything wey container write outside a volume go delete with am. E no dey touch volumes.
  2. docker image prune dey remove only dangling images. This na the safest image command.
  3. docker builder prune dey remove dangling build cache. The cost na one slow build.
  4. docker image prune -a dey remove every image wey no container dey refer to. The cost na to pull am again or rebuild am.
  5. docker system prune dey do the first three together and add unused networks.
  6. docker volume prune dey remove unused anonymous volumes.
  7. docker volume prune -a dey remove unused volumes, including named ones. Na this command dey delete databases.

docker system prune go state its own scope before e run.

WARNING! This will remove:
        - all stopped containers
        - all networks not used by at least one container
        - all dangling images
        - unused build cache
Are you sure you want to continue? [y/N]

We leave volumes out of that list deliberately. If you add --volumes, anonymous volumes go enter the scope again. If you add -a, the image step go expand from dangling images reach every unused image. Full docker system prune -a --volumes -f for production host na how people dey lose data when dem dey try free space.

Why pruning volumes dey delete your database

This na the section wey you suppose read twice.

A volume count as unused when no container dey attached to am. Na the whole test be that. Docker no check whether the volume empty, whether compose file still declare am, or whether na the only copy of your database e hold. LINKS 0 for docker system df -v mean unused, and docker volume prune -a treat every unused volume as fair game unless a label filter wey you add exclude am.

Now put two ordinary actions one after another. You run docker compose down to restart stack cleanly. E remove the containers and leave the named volumes for where dem dey, exactly as the documentation talk say e suppose do. Your Postgres volume no dey attached to anything again. Ten minutes later, you run docker volume prune -a to free space, and the database don disappear. Both commands work correctly. Na the sequence destroy the data.

Since Docker Engine 23.0 (API version 1.42), the plain command no dey touch as much as e used to.

WARNING! This will remove anonymous local volumes not used by at least one container.

An anonymous volume na one wey Docker create for you, usually because an image declare VOLUME and you no give am name. Those ones normally hold data wey you no ask to keep. Docker only remove a named volume, the type wey you write for your compose file, when you add -a. Older Docker versions remove both types with the plain command, so no trust habits wey you form for a machine wey you don upgrade since. This difference only make sense when you know how named volumes different from bind mounts, because bind mount no be Docker volume at all and no prune command go ever touch am.

Check before you delete. Replace myapp_pgdata with the volume name wey you dey check.

docker volume ls -f dangling=true
docker volume inspect myapp_pgdata
sudo ls -la /var/lib/docker/volumes/myapp_pgdata/_data

The dangling=true filter for a volume mean say nothing dey reference am, not say e empty. Listing _data go show you wetin really dey inside. If you see a pgdata or mysql directory inside, stop and make a copy before you continue. The same destruction fit happen through docker compose down -v, wey remove the named volumes wey compose file declare, except any wey dem mark external, and e no ask you anything first.

A volume na the one thing for Docker host wey rebuild no fit recreate. Na why volume data suppose dey inside a restic backup wey dey run outside the server, where mistyped flag no fit reach am.

When nothing prunes: container log files

You don prune everything, docker system df show say almost nothing fit free, but disk still full. Check the logs.

sudo find /var/lib/docker/containers -name '*-json.log' -exec du -h {} + | sort -h | tail -10

Every container dey write e standard output and standard error inside JSON file for /var/lib/docker/containers/. For default install, max-size no set. That mean e get no limit. So one container wey dey stuck for crash loop fit write until partition full. No prune command dey remove these files, because the containers wey dey produce dem still dey run. By definition, dem no fit prune.

No delete the file. If you run rm on log file wey still open, e no free anything. Docker daemon still hold open file descriptor, and kernel keep those blocks allocated until that handle close. df no go move at all. Truncate the file instead. This one keep the same inode and allow the daemon continue to write.

sudo find /var/lib/docker/containers -name '*-json.log' -exec truncate -s 0 {} +
df -h /

Na temporary fix be that. docker logs for those containers go now return nothing, and the files go start grow again immediately. The real fix na rotation, wey dey for the next section.

Measure before and after, every time

No dey guess wetin prune do. Take one reading, run one command, then take another reading.

df -h /
docker system df
docker builder prune -f --filter until=168h
docker image prune -f
docker system df
df -h /

Compare the two df outputs. Na only this number decide whether your server go continue to serve. docker system df go then tell you which row actually move, and every prune go print im own Total reclaimed space: figure.

If df no move but docker system df say space don free, one open file handle dey hold deleted blocks. Na the log file problem wey we talk above be this. If both move and disk fill up again within one day, na growth problem be this, no be cleanup problem. The answer na rotation plus one scheduled job.

How to stop the disk from filling up again

Cap the log size. Create or edit /etc/docker/daemon.json.

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

That one go hold every container wey dem create after restart to 30 MB of logs. Every value under log-opts must be string, including the numeric ones. Check whether the file parse correctly before you restart, because malformed daemon.json go stop the daemon from starting at all and e go bring every container down too.

python3 -m json.tool /etc/docker/daemon.json
sudo systemctl restart docker
docker info | grep -i 'logging driver'

docker info suppose now report Logging Driver: json-file. The limits themselves go show for the LogConfig section of docker inspect on container wey dem create after restart. Na this detail matter: this setting only apply to new containers. Existing containers keep the configuration wey dem build with, so recreate dem.

docker compose up -d --force-recreate

You fit also set the same limit per service inside compose file. This one better when one noisy service need its own number.

services:
  app:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Schedule a narrow prune. Run am weekly, and limit am to dangling images and old build cache. Never put -a or --volumes inside scheduled job, because if the job run while stack dey down, e go delete the images for that stack. With --volumes, e go start work on your data.

sudo tee /etc/cron.weekly/docker-prune >/dev/null <<'EOF'
#!/bin/sh
docker image prune -f
docker builder prune -f --filter until=168h
EOF
sudo chmod +x /etc/cron.weekly/docker-prune
sudo /etc/cron.weekly/docker-prune

That last line run the script once by hand, so you fit see the output before e ever run unattended. The file must be executable, and its name must not contain dot, because run-parts skips anything wey no be executable and anything wey get extension.

Alarm on free space. Prune wey you run after disk don fill na recovery. Alert at 80 percent na prevention.

usage=$(df --output=pcent / | tr -dc '0-9')
[ "$usage" -ge 80 ] && echo "root filesystem at ${usage} percent full"

Put am for cron with any notifier wey you already dey use. Free space na only half of the matter, so join the alarm with disk health monitoring for your VPS, because failing disk and full disk both fit stop your containers, but dem need different fixes.

Everything above assume standard install wey get data root for /var/lib/docker. If you move am with the data-root key for daemon.json, replace the path for every command with your own path. For containerd image store, data-root no move the image and container data for /var/lib/containerd, because root for /etc/containerd/config.toml dey set that location. Getting this layout correct for fresh box na part of setting up Docker for a VPS, and e much easier to decide before you get 40 GB of containers sitting for wrong partition.

FAQ

Docker system prune dey delete my volumes?

No. The plain command dey remove stopped containers, unused networks, dangling images, and unused build cache. E confirmation prompt list exactly those things. Volumes only enter when you add --volumes. Since Docker Engine 23.0, that flag dey cover anonymous volumes, no be named ones. docker volume prune -a and docker compose down -v dey remove named volumes. Na these two commands you must handle with care.

Why my disk still full after I run docker prune?

Two common causes dey. The first one na container log files under /var/lib/docker/containers/. No prune command dey touch dem, and dem go keep growing without limit until you set max-size. The second one na deleted file wey process still hold open. If you remove log with rm while e container still dey run, the daemon keep the file descriptor. The kernel no release the blocks, so df report no change. Compare sudo du -xh --max-depth=1 /var/lib/docker with docker system df to see which one dey affect you.

Wetin be the difference between docker image prune and docker image prune -a?

The plain command dey remove dangling images only. That means images wey lose their tag, almost always because of rebuild. The -a form dey remove every image wey no existing container dey refer to, including tagged images wey you deliberately pull. After docker compose down, the containers don go, so -a go carry that stack images comot too. Nothing lose permanently, because the next start go pull or rebuild dem again. But if the link slow, you go wait long.

How I fit stop Docker logs from filling the disk?

Set max-size and max-file under log-opts inside /etc/docker/daemon.json. Then restart the daemon with sudo systemctl restart docker. The setting only apply to containers wey you create after that restart. So recreate the ones wey dey run with docker compose up -d --force-recreate. You fit set the same two options for each service inside compose file under a logging key. Use this when one service dey produce far more logs than the others.

E safe to run docker system prune inside cron job?

The plain docker system prune -f safe for host where every stack dey stay up. But e dey remove stopped containers, so e go delete container wey you stop intentionally and plan to restart later. The safer scheduled job na docker image prune -f plus docker builder prune -f --filter until=168h. E free the two resources wey dey grow fastest, and e no fit touch volume. Never schedule -a or --volumes.

Dis article help you?