Docker Cleanup

How to see what Docker is using and remove it safely: containers, images, networks, volumes and build cache, plus log rotation so the disk does not fill again. The order matters. Volumes hold data, so they get their own warnings.

Documentation: docker system prune · Prune unused objects · JSON File logging driver

Verification: the container prune --filter until=, builder prune (--keep-storage, --filter until=, -a) options and the daemon.json log options were checked against the Docker docs. The rest is from the CLI reference. No command was executed. Review what a prune would delete before you run it, and never run --volumes on a host whose data lives in anonymous volumes you still need.

See also: Docker · Docker Troubleshooting · Docker Registry · Docker-Compose · Storage and Filesystems

See What Takes Space #

Safe Order #

Work from least to most risky. Run the matching ls first.

docker system prune runs steps 1 to 4 together (containers, networks, dangling images, dangling cache). It asks for confirmation; -f skips that.

Prune With Filters #

until takes a duration (24h), a timestamp or a Unix time. Add -f to skip the prompt in scripts.

Containers #

Images #

An image used by a stopped container is not removed by image prune -a until that container is removed.

Volumes (Careful) #

Volumes hold databases and app data. Deleting them cannot be undone.

Rules of thumb:

• A volume counts as “unused” if no container (running or stopped) references it. Stopped containers protect their volumes. If you removed the stack with compose down, its volumes become prunable.
• Back up first: docker run --rm -v VOLUME:/data -v "$PWD":/backup busybox tar czf /backup/VOLUME.tgz -C /data . (see Docker).
• Name important volumes and label them (labels: keep: "true" in Compose) so filters can protect them.

Build Cache #

In CI, run docker builder prune --filter until=168h -f weekly instead of wiping the cache every run.

Log Rotation #

The default json-file driver keeps logs forever. One chatty container can fill the disk.

Global default, in /etc/docker/daemon.json (merge with existing keys, then sudo systemctl restart docker). It only applies to new containers, so recreate existing ones:

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

local stores compact, compressed logs (defaults 20 MB x 5). json-file with the same log-opts also works, and keeps docker logs plus plain JSON on disk.

Per container or per Compose service:

docker run -d --log-opt max-size=10m --log-opt max-file=3 IMAGE

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

Do not rm the log file of a running container: the daemon keeps it open and the space stays used. Truncate it instead.

Automate It #

A weekly systemd timer (systemd) running a conservative prune:

/etc/systemd/system/docker-prune.service:

[Unit]
Description=Prune unused Docker objects

[Service]
Type=oneshot
ExecStart=/usr/bin/docker system prune -f --filter "until=168h"
ExecStart=/usr/bin/docker builder prune -f --filter "until=168h"

/etc/systemd/system/docker-prune.timer:

[Unit]
Description=Weekly Docker prune

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target

sudo systemctl daemon-reload
sudo systemctl enable --now docker-prune.timer

This leaves volumes and in-use images alone. Pair it with image update tools such as Watchtower or Renovate, which leave old image versions behind.

Moving Docker’s Data Directory #

If /var/lib/docker sits on a small disk, move it:

sudo systemctl stop docker docker.socket
sudo rsync -aHAX /var/lib/docker/ /mnt/bigdisk/docker/
# in /etc/docker/daemon.json: {"data-root": "/mnt/bigdisk/docker"}
sudo systemctl start docker
docker info | grep 'Docker Root Dir'

Keep the old directory until you have checked that containers and volumes work, then delete it.