Reclaim Disk Space by Cleaning Up /var/lib/docker/overlay2

Docker stores image and container data in /var/lib/docker/overlay2. This directory keeps growing if you build images often, pull multiple tags, or leave stopped containers around. Eventually it fills up your disk and Docker starts failing.

What you have in /var/lib/docker/overlay2

overlay2 is Docker’s copy-on-write filesystem for Linux. The directory holds:

• Layer directories: content-addressed folders with the actual filesystem diffs
• Container “upperdir” data: writable layers where containers write data (this is usually what gets big)
• Metadata and linkage: structures Docker uses to track which layers belong to which images

The folder names are random hashes, not readable identifiers. You can’t just look at a folder name and know what image it belongs to. Use Docker commands instead of trying to guess from directory names.

Reasons for /var/lib/docker/overlay2 using a lot of space

The directory grows for several reasons:

1. Unused Images and Containers: Stopped containers and old images still take up space if you don’t remove them.

2. Cached Layers: Docker caches layers to make builds faster, but this cache keeps growing if you don’t prune it.

3. Large Images and Containers: Some images are just large, especially ones that include big binaries or data files.

4. Inefficient Image Layers: Images with too many layers or unnecessary files waste space.

In case you are interested to monitor server resources like CPU, memory, disk space you can check: How To Monitor Server and Docker Resources

Check the space used

Start by checking Docker’s view of disk usage:

docker system df
docker system df -v

This shows space usage for images, containers, volumes, and build cache. The -v flag gives more detail.

Then check the actual disk usage:

du -sh /var/lib/docker/overlay2

To see which directories are largest (just for information, not for deleting):

du -sh /var/lib/docker/overlay2/* 2>/dev/null | sort -hr | head -10

Notes:

• Large overlay2 directories often come from container writes or build cache, not just unused images
• Focus on which category is growing (images, containers, volumes, or cache) rather than specific IDs
• That’s why docker system df -v is the first thing to run

Cleanup /var/lib/docker/overlay2

1) Quick win: remove unused Docker objects

This is the most common cleanup sequence. Start with a read-only report:

docker system df -v

Then remove unused objects.

Remove stopped containers, unused networks, dangling images, and build cache:

docker system prune -f

If you also want to remove all images not currently used by a container (more aggressive):

docker system prune -a -f

If you want to reclaim unused volumes (be careful: volumes can hold important data):

docker volume prune -f

If you run BuildKit builds, the build cache can be the biggest issue; prune it explicitly:

docker builder prune -f
docker builder prune -a -f

2) Identify what is growing (containers vs images vs volumes vs cache)

A large overlay2 directory often comes from container writes or build cache, not just unused images.

• If docker system df -v shows large Local Volumes usage, focus on volumes first.
• If it shows large Build Cache usage, use docker builder prune.
• If it shows large Containers usage, check for containers that are writing into their writable layers.

3) Map overlay2 usage to Docker objects (advanced)

I’ve created a utility script that helps visualize overlay2 disk usage:

curl -sSL https://utils.bitdoze.com/scripts/docker-overlay2-view.sh | bash

All scripts can be found at: https://utils.bitdoze.com/

Note: this mapping is best-effort. overlay2 is an internal structure, and not every directory has a clean “this belongs to image X” relationship. Use this output as guidance for what to investigate via Docker commands, not as a list of directories to delete.

Why are there overlay2 subfolders not matching an image even after docker system prune -a?

You’ll often see directories in /var/lib/docker/overlay2 that don’t match a current image ID. Here’s why:

1. Container writable layers: Running or stopped containers have a writable layer in overlay2. If you have containers, you have overlay data.

2. Build cache: Modern builds (BuildKit) create cache data. docker system prune -a doesn’t always remove all of it. Use docker builder prune to target it.

3. Shared or referenced layers: Images share layers, and Docker won’t remove anything that’s still referenced by an existing image or container. The directory name in overlay2 won’t match what you see in docker image ls.

4. Init layers and internal metadata: The *-init directories and metadata structures are part of how Docker sets up containers and layers.

5. Leaked or orphaned data (rare): Power loss, daemon crashes, or storage corruption can leave leftovers. If you suspect this, check Docker’s reporting (docker system df -v) and logs, then consider a controlled cleanup.

Important: avoid manual deletion

Even if a directory looks unused, deleting overlay2 directories by hand can corrupt Docker’s state.

If you need a fresh start, reset the Docker data directory with Docker stopped, and only after backing up what you need.

Controlled reset approach (last resort)

1. Stop or remove containers you don’t need.
2. Back up anything important (especially volumes and bind-mounted data).
3. Stop the Docker daemon.
4. Move /var/lib/docker to a backup location.
5. Start Docker again (it will recreate /var/lib/docker).

Then re-pull images and restore only what you need. This is disruptive, but safer than deleting random overlay directories.

Summary

A growing /var/lib/docker/overlay2 directory usually means:

• Unused or stopped containers and images
• Build cache growth (especially with BuildKit)
• Containers writing large amounts of data to their writable layer
• Large or unmanaged volumes

Use Docker’s disk reports (docker system df -v) and supported prune commands first. Don’t delete anything inside /var/lib/docker/overlay2 manually. If you need a full reset, move /var/lib/docker while Docker is stopped after backing up important data.