Docker Disk Full: Free Space with System Prune and Log Rotation

What Consumes Docker Disk Space

Docker’s disk usage grows from several independent sources, each requiring a different cleanup approach:

1. Container images — every ‘docker pull’, ‘docker build’, and image tag creates or retains image layers on disk. Images from previous deployments, old base image versions, and pulled-but-unused images accumulate. ‘docker images’ shows all stored images; ‘docker image prune -a’ removes all images not referenced by any container (running or stopped).

2. Container writable layers — every stopped container retains its writable layer (filesystem changes made during the container’s lifetime). On a system that creates containers frequently (CI runners, one-shot tasks), stopped containers can accumulate rapidly. ‘docker container prune’ removes all stopped containers.

3. Build cache — every layer created during ‘docker build’ is cached to speed up subsequent builds. On a build server, the cache can reach many gigabytes. ‘docker builder prune’ removes all build cache; ‘–filter until=24h’ removes only cache older than 24 hours.

4. Volumes — named volumes not attached to any running or stopped container are ‘dangling’. Anonymous volumes created with ‘docker run -v /data’ become dangling when their container is removed without ‘–volumes’. ‘docker volume prune’ removes dangling volumes — use caution as this is irreversible.

5. Container logs — Docker’s json-file log driver writes container stdout/stderr to /var/lib/docker/containers//-json.log with no rotation by default. High-volume logging containers can create multi-gigabyte log files. Log rotation must be configured explicitly.

Diagnosing and Reclaiming Docker Disk Space

# Step 1: See total disk usage by category
docker system df
# Output:
# TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
# Images          42        8         18.2GB    14.1GB (77%)
# Containers      5         3         1.2GB     890MB (74%)
# Local Volumes   12        4         8.4GB     6.1GB (72%)
# Build Cache     0         0         0B        0B

# Step 2: Verbose view (shows individual items)
docker system df -v

# Step 3: Safe prune — removes only clearly unused resources
# (does NOT remove volumes by default)
docker system prune

# Step 4: Nuclear option — remove everything not attached to running containers
# WARNING: removes all unused images, stopped containers, dangling volumes, build cache
docker system prune -a --volumes

# Step 5: Category-specific pruning (safer, more controlled)
docker container prune              # remove stopped containers
docker image prune                  # remove dangling images only
docker image prune -a               # remove all unused images
docker volume prune                 # remove dangling volumes
docker builder prune                # remove build cache
docker builder prune --filter until=24h  # remove cache older than 24h

‘docker system prune’ without ‘-a’ removes only dangling images (untagged layers from builds), stopped containers, unused networks, and build cache. It does NOT remove images that have a tag, even if no container is using them. Adding ‘-a’ extends cleanup to all images not referenced by any container — this is the most effective space reclamation but requires re-pulling images on next use. Adding ‘–volumes’ extends to dangling volumes — use only when you are certain the volumes contain no needed data.

Prune Commands and Their Scope

Managing Docker Disk Space in Production

Configuring Container Log Rotation

Docker’s default json-file log driver has no size limit. A single verbose container can write gigabytes of logs. Configure log rotation globally in the Docker daemon config or per-container at run time.

# Global log rotation: edit /etc/docker/daemon.json
# (restart Docker daemon after changes)
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  }
}

# Apply the new daemon config
sudo systemctl restart docker

# Per-container log rotation at run time:
docker run -d \
  --log-opt max-size=50m \
  --log-opt max-file=3 \
  --name myapp \
  myapp:latest

# In Docker Compose:
services:
  app:
    image: myapp:latest
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "3"

# Check current log file size for a container
du -sh /var/lib/docker/containers/<container-id>/*-json.log

# Find large log files across all containers
du -sh /var/lib/docker/containers/*/*-json.log | sort -h | tail -10

Scheduled Cleanup with Cron

Run ‘docker system prune’ automatically on a schedule to prevent disk accumulation. The command is safe to run while containers are running — it only removes resources that are definitively unused.

# Add to crontab (runs at 3 AM daily)
crontab -e
# Add:
# 0 3 * * * /usr/bin/docker system prune -f >> /var/log/docker-prune.log 2>&1

# For more aggressive cleanup (weekly, removes all unused images):
# 0 2 * * 0 /usr/bin/docker image prune -a -f --filter until=168h >> /var/log/docker-prune.log 2>&1

# Prune with age filter (keep last 3 days of unused images):
docker image prune -a --filter until=72h -f

# Prune stopped containers older than 1 day:
docker container prune --filter until=24h -f

# Check disk usage before and after:
df -h /var/lib/docker
docker system df

Protecting Volumes from Prune

Use labels to mark volumes that should not be pruned. The ‘docker volume prune’ command respects label filters, allowing you to keep important data volumes while removing truly orphaned ones.

# Label important volumes to protect them from pruning
docker volume create \
  --label keep=true \
  --label description=postgres-data \
  postgres-data

# Or in Docker Compose (volumes section):
volumes:
  postgres-data:
    labels:
      keep: "true"

# Prune only volumes WITHOUT the keep label:
docker volume prune --filter label!=keep -f

# List all volumes with their labels:
docker volume ls --format 'table {{.Name}}\t{{.Labels}}'

# List dangling volumes before pruning:
docker volume ls -f dangling=true

Disk Full Impact on Production Systems

Practical Examples

Emergency Disk Recovery Procedure

# Emergency procedure when disk is full (in order of safety)

# 1. Check how much space each Docker category is using
docker system df
df -h /var/lib/docker

# 2. Remove build cache first (safe, no data loss)
docker builder prune -f
# Check recovered space:
df -h /var/lib/docker

# 3. Remove stopped containers (safe if you don't need debug info)
docker container prune -f

# 4. Remove unused images (safe for running containers)
# Keep images used in last 48 hours:
docker image prune -a --filter until=48h -f

# 5. Check for large log files
du -sh /var/lib/docker/containers/*/*-json.log 2>/dev/null | \
  sort -h | tail -5

# 6. Truncate a specific large log file (safe while container runs)
# WARNING: this destroys historical logs
sudo sh -c '> /var/lib/docker/containers/<container-id>/<container-id>-json.log'

# 7. ONLY IF SAFE: remove dangling volumes
# List first:
docker volume ls -f dangling=true
# Then only remove clearly safe ones:
docker volume rm <volume-name>

Run these steps in order from least to most risky. Build cache and dangling images have zero data loss risk. Stopped container writable layers are usually safe to remove. Log truncation loses historical log data. Volume pruning has permanent data loss risk — list and audit before running.

Quick Reference: Key Commands and Options

# Inspect current configuration
docker inspect <container> --format='{{json .HostConfig}}' | python3 -m json.tool

# View container resource usage
docker stats <container> --no-stream

# Check container logs
docker logs <container> --tail 50 --timestamps

# Verify running processes inside container
docker exec <container> ps aux

# Check container environment variables
docker exec <container> env | sort

These diagnostic commands work across all container scenarios: ‘docker inspect’ shows the full HostConfig including all runtime parameters, ‘docker stats’ shows real-time resource consumption, and ‘docker logs’ shows output from the main process. Use these as the starting point for any container investigation before diving into more specific tooling.

Disk Space Troubleshooting

Prune Regularly, Rotate Logs, Monitor Disk Usage

Docker disk accumulation is predictable and preventable. The four main contributors — unused images, stopped containers, build cache, and unrotated logs — each have straightforward management strategies. Setting up log rotation in daemon.json and running ‘docker system prune’ on a cron schedule prevents disk full emergencies. When disk does fill up, address build cache and images first (no data loss risk) before considering volumes.

• Configure log rotation in /etc/docker/daemon.json with max-size and max-file before deploying any container. The default json-file driver with no limits will fill disk on any moderately verbose application.
• ‘docker system df’ shows disk usage broken down by category with reclaimable amounts — always run this first to understand where the space is before choosing a prune command.
• Never run ‘docker volume prune’ in an emergency without first listing dangling volumes and verifying they contain no needed data. Database volumes can appear dangling during maintenance and be destroyed irreversibly.