Complete Guide to Docker Cleanup: Freeing Up Space on Linux

Introduction / Why This Is Needed

Docker is an excellent tool, but over time it can accumulate a significant amount of "junk" data: stopped containers, old and dangling images, unused networks, and volumes. These artifacts can consume anywhere from hundreds of megabytes to several gigabytes of disk space. Regular Docker cleanup is an important practice for maintaining system health, especially on servers with limited disk space or in CI/CD environments. This guide will show you how to safely and effectively perform cleanup on any Linux system.

Requirements / Preparation

Before you begin, ensure the following:

1. Docker Engine (the dockerd daemon) is installed and running on your system.
2. Your user has permissions to execute Docker commands (usually via the docker group). For many cleanup commands, especially full cleanup, sudo privileges will be required.
3. You understand that deleting images and volumes is an irreversible action. Ensure that no important data (e.g., databases) exists in the volumes you plan to delete.
4. It is recommended to first create backups of any critical data or container states (via docker commit) if necessary.

Step-by-Step Guide

Step 1: Check Current Docker Disk Usage

First, let's see what is taking up space. The docker system df command will show a summary by resource type.

docker system df

The output will look something like this:

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          15        3         4.2GB     2.1GB (49%)
Containers      8         2         120MB     80MB (66%)
Local Volumes  12        5         3.5GB     1.8GB (51%)
Build Cache     0         0         0B        0B

Pay attention to the RECLAIMABLE column—this is the approximate amount of space you could free up after cleanup.

Step 2: Remove Stopped Containers

Stopped containers (Exited or Created) consume a small amount of space, but there can be many of them. You can remove all stopped containers with:

docker container prune

By default, the command will ask for confirmation. To skip the prompt, add the -f or --force flag:

docker container prune -f

What this command does: It removes all containers in a created or exited state. Running containers are unaffected.

Step 3: Remove Unused Images

This is the most important step for freeing up space. There are two main options here:

3.1 Remove only "dangling" images Dangling images are images that have no tag and are not parent images for any other images. They typically appear after building new versions or during updates.

docker image prune

This command will remove only dangling images. With the -a or --all flag, it will remove all images not used by any container (including those that have tags).

3.2 Remove ALL unused images (including tagged ones) This is a more aggressive and effective command. It will remove all images that have no references from existing (even stopped) containers.

docker image prune -a

Important: If you have containers created from specific images (even stopped ones), those images will not be deleted. To delete them as well, you must first delete the containers themselves (see Step 2).

You can add a time filter, for example, to remove images unused in the last 24 hours:

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

Step 4: Remove Unused Networks and Volumes

4.1 Network cleanup User-defined networks (not bridge, host, none) can remain after container removal.

docker network prune

This command removes all networks not used by at least one container.

4.2 Volume cleanup Volumes are often the "heaviest" resource in terms of size, especially if they stored database data. Remove only unused volumes:

docker volume prune

Critically important: This command permanently deletes all data in volumes that are not attached to existing containers. Before running, double-check that you do not need any data from these volumes. You can first list all volumes and their sizes:

docker volume ls -q | xargs docker volume inspect --format '{{.Name}} {{.Mountpoint}} {{.UsageData.Size}}' | sort -k3 -h

Or a simpler alternative:

docker system df -v

The output will include a VOLUME NAME block with size indications.

Step 5: Perform Full Cleanup (Optional)

If you want to execute all the above steps with a single command, use docker system prune. This is the "Swiss Army knife" for cleanup.

Basic full cleanup:

docker system prune

This command removes:

• All stopped containers.
• All networks not used by at least one container.
• All dangling images.
• The build cache.

Maximum aggressive cleanup (with the -a flag):

docker system prune -a

This command removes everything that is not in use:

• All stopped containers.
• All unused networks.
• All images without associated containers (even those with tags!).
• The build cache.

With confirmation: By default, the prune command will ask for confirmation. To run without prompts, add --force or -f:

docker system prune -a -f

Warning: The -a flag can delete images you planned to use later. Ensure you have a Dockerfile or a way to quickly rebuild any needed images.

Verify the Result

After cleanup completes, run the command from Step 1 again:

docker system df

Compare the values in the SIZE and especially RECLAIMABLE columns. The RECLAIMABLE value should be close to zero, and the total SIZE should be significantly reduced. You can also check free disk space with the df -h command.

Potential Issues

Issue 1: "Error: No such image" or "conflict: unable to delete..."

• Cause: Attempting to delete an image that is a parent of another image or is in use (even by a stopped container).
• Solution: First, delete all containers based on that image (docker ps -a to find them, docker rm to delete). If the image is "stuck" as a parent, forcing deletion with -f or a full cleanup via docker system prune -a often helps.

Issue 2: Permission denied error

• Cause: Running the command without sudo privileges.
• Solution: Add sudo before the command (e.g., sudo docker system prune -a) or ensure your user is in the docker group (groups $USER), then log out and back in.

Issue 3: Volumes not deleting even after containers are removed

• Cause: Volumes created with the --name flag or via docker volume create are not automatically removed when the container is deleted.
• Solution: Check the list of all volumes (docker volume ls). Volumes not in use (<none> in the CONTAINER column) can be removed manually (docker volume rm <volume_name>) or via docker volume prune.

Issue 4: Not enough space to perform operations

• Cause: The disk is 100% full, and Docker cannot create temporary files for operations.
• Solution: Temporarily clean up other files (e.g., your package manager cache: sudo apt clean for Ubuntu/Debian, sudo yum clean all for CentOS/RHEL) or manually delete old logs (/var/lib/docker/containers/*/*.log).