---
title: "Reclaim Disk Space by Cleaning Up /var/lib/docker/overlay2"
description: "Learn how to safely reclaim disk space on your Docker host when /var/lib/docker/overlay2 grows large, using supported cleanup commands and careful troubleshooting."
date: 2026-05-04
categories: ["vps"]
tags: ["docker"]
---

<Notice type="warning" title="Do not delete overlay2 folders manually">
Avoid deleting anything inside `/var/lib/docker/overlay2` by hand. Manual deletion can corrupt Docker's metadata and break running containers/images. Use the supported Docker cleanup commands in this guide, and only take "reset Docker data dir" actions if you fully understand the impact.
</Notice>

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](https://www.bitdoze.com/sever-monitoring/)

## Check the space used

Start by checking Docker's view of disk usage:

```sh
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:

```sh
du -sh /var/lib/docker/overlay2
```

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

```sh
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:

```sh
docker system df -v
```

Then remove unused objects.

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

```sh
docker system prune -f
```

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

```sh
docker system prune -a -f
```

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

```sh
docker volume prune -f
```

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

```sh
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:

```sh
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.