zachbg/docker-gc

By zachbg

•Updated 6 months ago

Docker garbage collector - auto clean unused images, containers, and volumes

Image

1.5K

Overview Tags

zachbg/docker-gc repository overview

⁠docker-gc

Automated Docker garbage collection — keep your disk clean without thinking about it.

⁠Why?

Docker fills your disk. Old images, stopped containers, dangling layers, build cache — it all adds up. This image:

Automatic cleanup — runs on a schedule, zero maintenance
Safe defaults — won't delete volumes (opt-in), respects age filters
Dry run mode — see what would be deleted before committing
Granular control — choose exactly what gets cleaned
Health monitoring — ping Uptime Kuma / Healthchecks.io on success

⁠Quick Start

docker run -d --restart=unless-stopped \
  --name docker-gc \
  -v /var/run/docker.sock:/var/run/docker.sock \
  zachbg/docker-gc

That's it. Old images, containers, networks, and build cache cleaned daily at 3 AM.

⁠Docker Compose

services:
  gc:
    image: zachbg/docker-gc
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - GC_SCHEDULE=0 3 * * *
      - GC_IMAGE_AGE=48h
      - GC_VOLUMES=false  # Safe default — won't delete data
      - HEALTHCHECK_URL=https://hc.example.com/ping/xxx

⁠Environment Variables

Variable	Default	Description
`GC_SCHEDULE`	`0 3 * * *`	Cron schedule (default: daily 3 AM)
`GC_IMAGES`	`true`	Remove unused images
`GC_CONTAINERS`	`true`	Remove stopped containers
`GC_VOLUMES`	`false`	Remove unused volumes (caution!)
`GC_NETWORKS`	`true`	Remove unused networks
`GC_BUILDCACHE`	`true`	Remove build cache
`GC_IMAGE_AGE`	`24h`	Only remove images older than this
`GC_CONTAINER_AGE`	`24h`	Only remove containers older than this
`GC_KEEP_IMAGES`		Comma-separated images to never remove
`GC_DRY_RUN`	`false`	Preview what would be deleted
`HEALTHCHECK_URL`		URL to ping on success

⁠Examples

⁠Aggressive Cleanup (CI/CD runners)

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GC_SCHEDULE="0 * * * *" \
  -e GC_IMAGE_AGE=4h \
  -e GC_VOLUMES=true \
  zachbg/docker-gc

⁠Conservative (production)

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GC_SCHEDULE="0 4 * * 0" \
  -e GC_IMAGE_AGE=168h \
  -e GC_VOLUMES=false \
  -e GC_KEEP_IMAGES="postgres:17,redis:7" \
  zachbg/docker-gc

⁠Dry Run (preview)

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GC_DRY_RUN=true \
  -e GC_SCHEDULE="* * * * *" \
  zachbg/docker-gc

⁠Safety

Volumes are OFF by default — opt-in with GC_VOLUMES=true
Age filters — won't delete recently-used resources
Dry run mode — always preview first
Running containers are never touched — only stopped/dead

⁠License

MIT

Tag summary

Recent tags

Content type

Image

Digest

sha256:626d30862…

Size

20 MB

Last updated

6 months ago

docker pull zachbg/docker-gc