The disk is nearly full, Docker is the usual suspect, and docker image prune is right there begging to be run. This guide gets you the space back without deleting the one image you needed for a rollback. Allow about ten minutes for a careful one-off cleanup, longer on a production host. The examples match Docker 29.8.1 and the installed docker image prune(1) manual from the docker-ce-cli package.
sudo where your account is not allowed to use Docker.docker group can grant root-equivalent control, so do not add yourself to it just to make this command convenient.Confirm the Docker client version, then list images with their tags, identifiers and creation times. Listing is read-only and does not need elevated privileges unless the daemon socket requires it.
$ docker --version
Docker version 29.8.1, build 4a63305
$ docker image ls --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}'
REPOSITORY TAG IMAGE ID CREATED AT
example old 0123456789ab 2026-08-01 09:30:00 +0000 UTCYour list will differ. Before removing anything, check that no deployment, rollback plan or stopped container still depends on it. An image that looks old can still be the quickest way to restore a service.
Checkpoint: Record the image names or IDs you intend to keep. If you cannot explain why an image is safe to remove, stop here and investigate its consumers.
Without -a, the command removes dangling images. These are untagged image layers that no container references. They commonly appear after you rebuild an image under the same tag. This is the narrowest useful cleanup:
$ docker image prune
WARNING! This will remove all dangling images.
Are you sure you want to continue? [y/N] y
Deleted Images:
deleted: sha256:0123456789abcdef...
Total reclaimed space: 128.4MBWarning: The confirmation prompt does not show a complete candidate list. Treat y as an irreversible decision for the local image data. If you are only testing the command or reviewing its warning, answer n or press Enter.
Recovery: There is no general undo command for a pruned image. Recovery normally means pulling it again or rebuilding it.
Tip: Use sudo docker image prune only when the unprivileged command fails because your account cannot access the daemon. Running it as root does not make the selection safer.
Docker has no dry-run flag for this command. Instead, use the matching image-list filters to show the candidates, then run prune with the same filter. For dangling images, inspect the narrow set first:
$ docker image ls --filter dangling=true --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}'
REPOSITORY TAG IMAGE ID CREATED AT
<none> <none> 0123456789ab 2026-08-01 09:30:00 +0000 UTCIf the list is acceptable, run docker image prune and confirm interactively. A no-op result is normal:
Total reclaimed space: 0BWarning: Do not confuse docker image prune with docker system prune. The latter also targets other unused Docker objects, so it is outside this guide.
Add --all or -a to remove unused tagged images as well as dangling ones. An image is eligible when no existing container references it. That can include a useful rollback image, even one that still has a tag:
$ docker image prune --all
WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N] y
Deleted Images:
untagged: example:old
deleted: sha256:0123456789abcdef...
Total reclaimed space: 2.1GBBefore accepting this prompt, inspect containers, including stopped ones:
$ docker ps -a --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
NAMES IMAGE STATUS
api-old example:old Exited (0) 2 days agoA stopped container still references its image, so --all will not remove that image.
Warning: Removing the stopped container first would change that relationship and is a separate, destructive action. Do not combine it with image pruning unless you have a tested recovery plan.
The --filter option accepts key=value. The most useful filter is until, which limits removal to images created before a timestamp or duration. The duration is evaluated using the Docker daemon's clock:
$ docker image prune --all --filter 'until=240h'
WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N] n
Total reclaimed space: 0BThis example deliberately answers n, so it changes nothing. Replace 240h with a retention period you have agreed for that host. The filter shrinks the eligible set; it does not turn --all into a dry run.
Labels can narrow the operation further. This one only considers images carrying a retention=temporary label:
$ docker image prune --all --filter 'label=retention=temporary'docker image ls using the same syntax.label!=retention, the image-list command cannot show the complete removal set. Keep the confirmation prompt and review the policy before using one.--force or -f skips confirmation. It suits a controlled maintenance job only when the age or label policy is explicit and the daemon host is the intended target:
$ docker image prune --all --force --filter 'until=720h'
Deleted Images:
deleted: sha256:0123456789abcdef...
Total reclaimed space: 640MBWarning: Do not copy this into a scheduled job without first checking the host's image retention needs, registry availability and rollback process. Keep the scope to image pruning.
A scheduled command should log its output and alert on a non-zero exit status. If the policy was too aggressive, pull the required image from its trusted registry or rebuild it from the recorded source. There is no prune rollback.
--all also removes unused tagged images.until or label filters when a broad cleanup was not appropriate.--force as an automation setting only.