{"id":13412476,"url":"https://github.com/spotify/docker-gc","last_synced_at":"2025-03-14T18:31:30.871Z","repository":{"id":18055077,"uuid":"21109776","full_name":"spotify/docker-gc","owner":"spotify","description":"INACTIVE: Docker garbage collection of containers and images","archived":true,"fork":false,"pushed_at":"2021-02-01T19:20:40.000Z","size":159,"stargazers_count":5041,"open_issues_count":22,"forks_count":445,"subscribers_count":107,"default_branch":"master","last_synced_at":"2025-03-09T22:34:30.632Z","etag":null,"topics":["docker","garbage-collection","shell"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spotify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-06-23T00:52:57.000Z","updated_at":"2025-02-28T18:11:56.000Z","dependencies_parsed_at":"2022-09-10T08:40:30.050Z","dependency_job_id":null,"html_url":"https://github.com/spotify/docker-gc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Fdocker-gc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Fdocker-gc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Fdocker-gc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Fdocker-gc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spotify","download_url":"https://codeload.github.com/spotify/docker-gc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243625132,"owners_count":20321238,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","garbage-collection","shell"],"created_at":"2024-07-30T20:01:25.124Z","updated_at":"2025-03-14T18:31:30.064Z","avatar_url":"https://github.com/spotify.png","language":"Shell","readme":"# docker-gc\n\n[![Build Status](https://travis-ci.com/spotify/docker-gc.svg?branch=master)](https://travis-ci.com/spotify/docker-gc)\n[![License](https://img.shields.io/github/license/spotify/docker-client.svg)](LICENSE)\n\n## Status: mature\n\n**We're not developing or accepting new features.**\n\nConsider using [`docker system prune`][prune] instead.\n\n\n* [Building](#building)\n* [Installing](#installing)\n* [Usage](#usage)\n  * [Excluding Images From Garbage Collection](#excluding-images-from-garbage-collection)\n  * [Excluding Containers From Garbage Collection](#excluding-containers-from-garbage-collection)\n  * [Running as a Docker Image](#running-as-a-docker-image)\n    * [Build the Docker Image](#build-the-docker-image)\n    * [Running as a Docker Container](#running-as-a-docker-container)\n\nA simple Docker container and image garbage collection script.\n\n* Containers that exited more than an hour ago are removed.\n* Images that don't belong to any remaining container after that are removed.\n* Optionally, remove volumes that are not associated to any remaining container after removal (Available only for docker \u003e= 1.9.0)\n\nAlthough docker normally prevents removal of images that are in use by\ncontainers, we take extra care to not remove any image tags (e.g., ubuntu:14.04,\nbusybox, etc) that are in use by containers. A naive `docker rmi $(docker images\n-q)` will leave images stripped of all tags, forcing docker to re-pull the\nrepositories when starting new containers even though the images themselves are\nstill on disk.\n\nThis script is intended to be run as a cron job, but you can also run it as a Docker\ncontainer (see [below](#running-as-a-docker-container)).\n\n## Building the Debian Package\n\n\n```sh\nsudo apt-get install git devscripts debhelper build-essential dh-make\ngit clone https://github.com/spotify/docker-gc.git\ncd docker-gc\ndebuild -us -uc -b\n```\n\nIf you get lintian errors during `debuild`, try `debuild --no-lintian -us -uc -b`.\n\n\n## Installing the Debian Package\n\n```sh\nsudo dpkg -i ../docker-gc_0.1.0_all.deb\n```\n\nThis installs the `docker-gc` script into `/usr/sbin`. If you want it to\nrun as a cron job, you can configure it now by creating a root-owned\nexecutable file `/etc/cron.hourly/docker-gc` with the following contents:\n\n```\n#!/bin/bash\n/usr/sbin/docker-gc\n```\n\nTo test that the job will actually run you can use this command\n\n```\nrun-parts --test /etc/cron.hourly\n```\n\n## Manual Usage\n\nTo use the script manually, run `docker-gc`. The system user under\nwhich `docker-gc` runs needs to have read and write access to\nthe `$STATE_DIR` environment variable which defaults to `/var/lib/docker-gc`.\n\n\n### Excluding Images From Garbage Collection\n\nThere can be images that are large that serve as a common base for\nmany application containers, and as such, make sense to pin to the\nmachine, as many derivative containers will use it.  This can save\ntime in pulling those kinds of images.  There may be other reasons to\nexclude images from garbage collection.  To do so, create\n`/etc/docker-gc-exclude`, or if you want the file to be read from\nelsewhere, set the `EXCLUDE_FROM_GC` environment variable to its\nlocation.  This file can contain image name patterns (in the `grep`\nsense), one per line, such as `spotify/cassandra:latest` or it can\ncontain image ids (truncated to the length shown in `docker images`\nwhich is 12.\n\nAn example image excludes file might contain:\n```\nspotify/cassandra:latest\nredis:.*\n9681260c3ad5\n```\n\n### Excluding Containers From Garbage Collection\n\nThere can also be containers (for example data only containers) which\nyou would like to exclude from garbage collection. To do so, create\n`/etc/docker-gc-exclude-containers`, or if you want the file to be\nread from elsewhere, set the `EXCLUDE_CONTAINERS_FROM_GC` environment\nvariable to its location. This file should contain name patterns (in\nthe `grep` sense), one per line, such as `mariadb-data`.\n\nAn example container excludes file might contain:\n```\nmariadb-data\ndrunk_goodall\n```\n\n### Excluding Volumes From Garbage Collection\n\nThere can be occasions where you don't want to remove a dangling volume.\nTo enable this functionality you can create a file named\n`/etc/docker-gc-exclude-volumes` (or specify `EXCLUDE_VOLUMES_IDS_FILE` env var\nwith any path for such file), containing name patterns (in the `grep` sense),\none per line, of volumes that will be excluded from garbage collection.\n\n### Forcing deletion of images that have multiple tags\n\nBy default, docker will not remove an image if it is tagged in multiple\nrepositories.\nIf you have a server running docker where this is the case, for example\nin CI environments where dockers are being built, re-tagged, and pushed,\nyou can enable a force flag to override this default.\n\n```\nFORCE_IMAGE_REMOVAL=1 docker-gc\n```\n\n### Preserving a minimum number of images for every repository\n\nYou might want to always keep a set of the most recent images for any\nrepository. For example, if you are continually rebuilding an image during\ndevelopment you would want to clear out all but the most recent version of an\nimage. To do so, set the `MINIMUM_IMAGES_TO_SAVE=1` environment variable. You\ncan preserve any count of the most recent images, e.g. save the most recent 10\nwith `MINIMUM_IMAGES_TO_SAVE=10`.\n\n### Forcing deletion of containers\n\nBy default, if an error is encountered when cleaning up a container, Docker\nwill report the error back and leave it on disk.  This can sometimes lead to\ncontainers accumulating.  If you run into this issue, you can force the removal\nof the container by setting the environment variable below:\n\n```\nFORCE_CONTAINER_REMOVAL=1 docker-gc\n```\n\n### Excluding Recently Exited Containers and Images From Garbage Collection\n\nBy default, docker-gc will not remove a container if it exited less than 3600 seconds (1 hour) ago. In some cases you might need to change this setting (e.g. you need exited containers to stick around for debugging for several days). Set the `GRACE_PERIOD_SECONDS` variable to override this default.\n\n```\nGRACE_PERIOD_SECONDS=86400 docker-gc\n```\n\nThis setting also prevents the removal of images that have been created less than `GRACE_PERIOD_SECONDS` seconds ago.\n\n### Dry run\nBy default, docker-gc will proceed with deletion of containers and images. To test your command-line options set the `DRY_RUN` variable to override this default.\n\n```\nDRY_RUN=1 docker-gc\n```\n\n\n## Running as a Docker Image\n\nA Dockerfile is provided as an alternative to a local installation. By default\nthe container will start up, run a single garbage collection, and shut down.\n\nThe image is published as `spotify/docker-gc`.\n\n#### Building the Docker Image\nThe image is currently built with Docker 17.09.0-ce, but to build it against a newer\nDocker version (to ensure that the API version of the command-line interface\nmatches with your Docker daemon), simply edit [the `ENV DOCKER_VERSION` line in\n`Dockerfile`][dockerfile-ENV] prior to the build step below.\n\n[dockerfile-ENV]: https://github.com/spotify/docker-gc/blob/fd6640fa8c133de53a0395a36e8dcbaf29842684/Dockerfile#L3\n\nBuild the Docker image with `make -f Makefile.docker image` or:\n\n```sh\ndocker build -t spotify/docker-gc .\n```\n\n#### Running as a Docker Container\n\nThe docker-gc container requires access to the docker socket in order to\nfunction, so you need to map it when running, e.g.:\n\n```sh\ndocker run --rm --privileged -v /var/run/docker.sock:/var/run/docker.sock -v /etc:/etc:ro spotify/docker-gc\n```\n\nThe `/etc` directory is also mapped so that it can read any exclude files\nthat you've created.\n\nIf you want to remove volumes, you can do so by passing REMOVE_VOLUMES env var set to 1.\n\n```sh\n$ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v /etc:/etc -e REMOVE_VOLUMES=1 spotify/docker-gc\n```\n\nIf you want to remove volumes only for a specified driver, you can do it by passing VOLUME_DELETE_ONLY_DRIVER env var set to the driver name.\n\nIf your docker daemon is configured to run with user namespace, you will need to\nrun the container with [user namespace disabled][disable-user-namespace]:\n\n```sh\ndocker run --rm --userns host -v /var/run/docker.sock:/var/run/docker.sock -v /etc:/etc spotify/docker-gc\n```\n\n[disable-user-namespace]: https://docs.docker.com/engine/reference/commandline/dockerd/#disable-user-namespace-for-a-container\n[prune]: https://docs.docker.com/engine/reference/commandline/system_prune/\n","funding_links":[],"categories":["Shell","Development with Docker","Dev Tools","shell"],"sub_categories":["Garbage Collection"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspotify%2Fdocker-gc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspotify%2Fdocker-gc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspotify%2Fdocker-gc/lists"}