Docker Orphan Containers Cleanup Guide

In this tutorial, you'll learn about Docker Orphan Containers Cleanup Guide. We cover key concepts, practical examples, and best practices.

Docker orphan containers are containers no longer associated with any service in your docker-compose file, or leftover containers from failed builds and stopped services that accumulate and consume disk space over time.

The Problem

docker ps -a

Shows dozens or hundreds of exited containers:

CONTAINER ID   IMAGE          COMMAND    STATUS
abc123         project_web    "python"   Exited (1) 2 days ago
def456         project_web    "python"   Exited (1) 3 days ago
ghi789         project_db     "mysql"    Exited (0) 5 days ago

These containers are not running but still occupy disk space with their layers, volumes, and metadata.

Wrong Approach (Manual Removal)

# WRONG — time-consuming and error-prone
docker rm abc123 def456 ghi789

Right Approach (Cleanup Commands)

# Remove all exited containers
docker container prune -f

Or target orphans from a specific compose project:

docker-compose down --remove-orphans

Expected output:

Removing network project_default
Removing container project_web_1
Removing container project_db_1
Removed orphan containers

Step-by-Step Cleanup

Step 1: List all containers including orphans

# Show containers not defined in the current compose file
docker-compose down --remove-orphans --dry-run

Step 2: Remove all stopped containers

docker container prune

You will be prompted to confirm. Add -f to skip the prompt.

Expected output:

Deleted Containers:
abc123abc123
def456def456

Total reclaimed space: 1.5GB

Step 3: Remove all unused resources

docker system prune -a --volumes

This removes all stopped containers, unused networks, dangling images, and build cache.

Step 4: Clean up specific compose orphans

docker-compose -f docker-compose.yml down --remove-orphans

Step 5: Automate cleanup with a cron job

0 3 * * 0 docker system prune -f --filter "until=72h"

Prevention Tips

• Always run docker-compose down --remove-orphans after changing compose files
• Use unique project names with -p flag in CI/CD pipelines
• Set up automatic pruning with docker system prune --filter "until=24h"
• Monitor container count with docker ps -a -q | wc -l
• Use --rm flag for temporary containers

Common Mistakes with orphan containers

1. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
2. Using head and tail instead of pattern matching, causing runtime errors on empty lists
3. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks

These mistakes appear frequently in real-world DOCKER code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ