334

In the docker documentation of docker image prune it is possible to use the -a flag to

Remove all unused images, not just dangling ones

and later

Remove all dangling images. If -a is specified, will also remove all images not referenced by any container.

Can someone explain to me what dangling images are and what's the difference between dangling and unused images?

Liam
  • 27,717
  • 28
  • 128
  • 190
herm
  • 14,613
  • 7
  • 41
  • 62
  • docker image prune (without -a) does exactly the same though – herm Mar 20 '19 at 19:22
  • It fails when you use that in jenkins, we will lose the docker backup in production if we are dependent on docker image cache. `prune` is not recomanded in production/ – Jinna Balu Mar 21 '19 at 14:30
  • This answer https://stackoverflow.com/a/53224187/269514 by @tgogos, helped me elucidated the confusion. – Gilberto Aug 23 '21 at 13:17

7 Answers7

317

An unused image means that it has not been assigned or used in a container. For example, when running docker ps -a - it will list all of your exited and currently running containers. Any images shown being used inside any of containers are a "used image".

On the other hand, a dangling image just means that you've created the new build of the image, but it wasn't given a new name. So the old images you have becomes the "dangling image". Those old image are the ones that are untagged and displays "<none>" on its name when you run docker images.

When running docker system prune -a, it will remove both unused and dangling images. Therefore any images being used in a container, whether they have been exited or currently running, will NOT be affected.

Brian Burns
  • 20,575
  • 8
  • 83
  • 77
Serey
  • 10,173
  • 2
  • 17
  • 22
  • According to the documentation when running docker prune without -a only dangling images are removed. -a will ensure that unused images are also deleted right? https://docs.docker.com/engine/reference/commandline/system_prune/ – herm Jul 17 '17 at 11:55
  • 1
    That is correct, -a will [remove all unused images not just dangling ones](https://docs.docker.com/engine/reference/commandline/system_prune/) – Serey Jul 17 '17 at 12:00
  • 1
    Very interesting. So a dangling image can be used by a container. [Note: Docker warns you if any containers exist that are using these untagged images.](https://docs.docker.com/engine/reference/commandline/images/#filtering) – herm Jul 17 '17 at 12:08
  • 13
    `docker system prune --all --filter "until=24h"` preserves recent images also – Harry Moreno Apr 10 '18 at 22:02
  • 1
    According to https://docs.docker.com/engine/reference/commandline/system_prune/#extended-description `docker system prune -a` removes stopped containers too. So it should remove images associated only with exited containers too, right? – lfk May 14 '18 at 04:36
  • I run `docker system prune`, but when I run `docker images` after, I still have all the untagged (``) images there. Why is that? – lfk Jun 26 '18 at 01:29
  • docker system prune --all --filter is not suggested for production. Be carefull doing this in production server. – Jinna Balu Sep 04 '18 at 18:23
  • Why not @JinnaBalu? It seems like a regular prune is the only way to avoid the disk filling up in production environments where your systemd units autoupdate images. Using the filter flag will help you with caching images that will save resources on future updates. – deed02392 Oct 30 '18 at 13:37
  • because We end up deleting non dangling, we may delete unused, which may be used for rollback to previous version.@deed02392 – Jinna Balu Oct 30 '18 at 17:32
  • It's not just that you didn't give it a tag, there are more ways to _dangle_ an image. E.g.: `docker build -t foo:latest .` then change some code, then `docker build -t foo:latest .` again. This will result in the `foo:latest` tag being applied to the newer image but the tag `foo:latest` can only refer to one image, so the image it previously referred to (from the first build in this example) now has no tag, and becomes _dangling_. Any time a tag is newly applied, there is a chance that whatever image that tag was previously assigned to may now have no other tags and would become _dangling_. – Wyck Oct 23 '21 at 04:51
  • "Therefore any images being used in a container, whether they have been exited or currently running, will NOT be affected". This is just wrong. When running docker system prune -a, it will remove all non running containers, and therefore will also remove the images that use them. – Yossi Sternlicht Feb 14 '22 at 21:37
  • is there a way to list the unused image before prune them? like a dry-run thing? – shamaseen Feb 06 '23 at 13:18
  • `docker system prune -a` removes the following 1. all stopped containers 2. all networks not used by at least one container 3. all images without at least one container associated to them 4. all build cache. I thought it would only remove dangling images, but that is not the case. Be careful! – mrpandey May 16 '23 at 09:19
84

Safest and Easiest way to cleanup Dangling Images

docker images --quiet --filter=dangling=true | xargs --no-run-if-empty docker rmi

Docker images consist of multiple layers. Dangling images, are layers that have no relationship to any tagged images. They no longer serve a purpose and consume disk space.

Note: I recommend not to use prune in production, because docker system prune -a will remove all the images which are not referenced by the container, by which we can't roll back to the previous release.

To list dangling images by adding the filter flag, -f with a value of dangling=true to the docker images.

List Dangling images

docker images -f dangling=true

Remove Dangling Images

docker rmi $(docker images -f dangling=true -q)

OR 

docker images --quiet --filter=dangling=true | xargs --no-run-if-empty docker rmi

When we run any cron jobs to delete tha dangling stuff use the above to make sure the job runs successfully. Like in Jenkins if we run a free style job with beloow commad job will never fail even if no dangling stuff exists in the machine.

This is the safest and easiest way to cleanup dangling images and get back our disk space back for use.

inquisitive
  • 3,738
  • 6
  • 30
  • 56
Jinna Balu
  • 6,747
  • 38
  • 47
  • 4
    what about docker image prune? Docs say: "Remove all dangling images. If -a is specified, will also remove all images not referenced by any container." https://docs.docker.com/engine/reference/commandline/image_prune/#related-commands – herm Apr 12 '18 at 15:06
  • 5
    @herm, from the bottom of the page you referenced "Note: You are prompted for confirmation before the prune removes anything, but you are not shown a list of what will potentially be removed". I think the point in this answer is that you can get a list of the dangling images, which you then explicitly specify to be removed, as opposed to blindly removing all dangling images with prune. – bzier Apr 19 '18 at 23:43
  • The images having name and tag as none in `docker images` are dangled. How to check their size? Also, the images having name and tag as none in `docker images -a` are intermediate images. Can they be deleted and how to check their size? – variable May 05 '20 at 16:55
  • Can these dangling images be fixed? – Bionix1441 Oct 29 '20 at 09:32
  • 1
    Fixing is possible but not needed. Dangling images can be re-tagged back to the image, but when we have multiple images, we don't know which image id belongs to which app. Better to delete dangling images. – Jinna Balu Oct 29 '20 at 17:16
26

Images in docker are referenced by a sha256 digest, often referred to as the image id. That digest is all you need for the image to exist on the docker host. Typically, you will have tags that point to these digests, e.g. the tag 'busybox:latest' currently points to image id c30178c523... on my system.

Multiple tags can point to the same image, and any tag can be changed to point to a different id, e.g. when you pull a new copy of busybox:latest or build a new version of your application image.

Dangling images are images which do not have a tag, and do not have a child image (e.g. an old image that used a different version of FROM busybox:latest), pointing to them. They may have had a tag pointing to them before and that tag later changed. Or they may have never had a tag (e.g. the output of a docker build without including the tag option).

These are typically safe to remove as long as no containers are still running that reference the old image id. The main reason to keep them around is for build caching purposes.

In addition, you may have downloaded images that you are not currently used by containers (including stopped containers). These are entirely different from dangling images and may be safe to remove as long as you don't plan to use them in the future or don't mind downloading another copy when you do need them.

Brian Burns
  • 20,575
  • 8
  • 83
  • 77
BMitch
  • 231,797
  • 42
  • 475
  • 450
  • While a docker build is running (the process in which it creates layers and possible candidates for future dangling images), in a new window if I run docker image prune, then, will it affect the build in progress in any way? – variable May 05 '20 at 12:34
  • @variable there could be a race condition in there, but typically the running container for a build step will result in the image being identified as in use. The worst that might happen is either the prune throws an error, or the build does, and you'd have to rerun it. I'd look into whether you can limit your prune to avoid images you are currently using to build since a successful prune will result in future builds needing to download images again. – BMitch May 05 '20 at 13:25
  • Are intermediary images (those that have none name/tag showing upon running `docker images -a`) also called dangled images? Do they get cleared with docker image prune? – variable May 05 '20 at 17:30
  • I don't have those in my environment anymore (using buildkit here), so I'd recommend trying yourself in a lab environment to see what happens. – BMitch May 05 '20 at 17:32
  • That said, deleting the untagged "images" from the intermediate stages is fairly pointless, unless you delete the final tagged image, all the layers are reused in a later image and can't be deleted. If you do delete them, you destroy your build cache and cause all future images to take more time to build and disk space to store. – BMitch May 05 '20 at 17:37
14

Dangling images are untagged images. The following command gives a list of dangling images.

docker images --filter "dangling=true"

docker image prune deletes all dangling images.

Unused images are images that have tags but currently not being used as a container. You may or may not need it in future.

docker image prune -a delete all dangling as well as unused images.

You generally don't want to remove all unused images until some time. Hence it is better to remove with a filter.

docker image prune -a -f --filter "until=6h"

Venkat Kotra
  • 10,413
  • 3
  • 49
  • 53
  • 1
    1) Does `docker image prune -a -f --filter "until=6h"` also delete dangling images? – variable May 05 '20 at 12:37
  • 1
    2) In your last command you mention `docker image prune -f --filter "until=6h"` - since there is no -a - then how come it will remove unused images? – variable May 05 '20 at 12:38
  • @variable, The sample on the docker documentation shows `$ docker image prune -a --force --filter "until=2017-01-04T00:00:00"`. Using the -a with filter is the right way to go if you want to remove both dangling and unused images. – Kevin Finkenbinder Jun 14 '21 at 15:06
  • 1
    For docker-1.13 on CentOS 7, 'docker image prune' doesn't delete all dangling images as reported by 'docker images -f dangling=true'. The latter shows images that have either the repository or tag as ''. The former deletes only images that have the repository and tag as 'none'. You'll have lots of images with the repository set but tag='none' after the former command. – fencekicker Oct 11 '22 at 10:21
14

Dangling images are layers that have no relationship to any tagged images. They no longer serve a purpose and consume disk space.

An unused image is an image that has not been assigned or used in a container.

To list dangling images:

docker images -f dangling=true
Brian Burns
  • 20,575
  • 8
  • 83
  • 77
subh2273
  • 141
  • 1
  • 3
2

In the images screenshot, "none" name are dangling images. A dangling image just means that you've created the new build of the image, but it wasn't given a new name. So the old images you have becomes the "dangling image". Those old image are the ones that are untagged and displays "" on its name when you run docker images.

docker system prune -a, it will remove both unused and dangling images. Therefore, any images being used in a container, whether they have been exited or currently running, will NOT be affected.

double-beep
  • 5,031
  • 17
  • 33
  • 41
Nirbhay Singh
  • 51
  • 1
  • 1
  • 7
1

I saw useful commands (aliases) for removing dangling images, courtesy of andyneff here: https://forums.docker.com/t/how-to-delete-cache/5753:

alias docker_clean_images='docker rmi $(docker images -a --filter=dangling=true -q)' 
alias docker_clean_ps='docker rm $(docker ps --filter=status=exited --filter=status=created -q)'

The first one cleans all dangling images. This is useful for removing intermediate images left over from multiple builds. The second one is for removing stopped containers. These are aliases I use for routine maintenance

If you want to remove ALL of your cache, you first have to make sure all containers are stopped and removed, since you cannot remove an image in use by a container. So something similar

docker kill $(docker ps -q) docker_clean_ps docker rmi $(docker images
-a -q)

This would kill and remove all images in your cache.

Alex Martian
  • 3,423
  • 7
  • 36
  • 71