What is the difference between an image and a repository?

Question

I am brand new to Docker and following the Getting Started tutorial. At step 7 it says

type docker images command and press RETURN. The command lists all the images on your local system. You should see docker/whalesay in the list.

$ docker images REPOSITORY           TAG         IMAGE ID            CREATED            VIRTUAL SIZE docker/whalesay      latest      fb434121fc77        3 hours ago        247 MB hello-world          latest      91c95931e552        5 weeks ago        910 B 

but the first column clearly says "repository", not e.g. "image name". I have also noticed on other people's machines that, because an image can have multiple tags, this listing often contains duplicate entries - one for each tag. So is this a list of images, a list of repositories, a list of image-tag combinations or something else? What is the difference between an image and a repository?

Also, given that images and repositories are different things, how can I just list my repositories?

This is nothing to do with containers.

Answer 1

Yes, this is very confusing terminology.

Simplest answer:

Image: a single image.

Repository: a collection of images.

Details:

Image: Uniquely referenced by the Image ID, the 12 digit hex code (e.g. 91c95931e552). ^[1]

Repository: Contains one or more images. So the hello-world repository could contain two different images: 91c95931e552 and 1234abcd5678.

Image alias - I'm going to define image alias to mean an alias that references a specific image. The format of an image alias is repository:tag. This way, you can use a human-friendly alias such as hello-world:latest instead of the 12-digit code.

Example:

Let's say I have these images:

REPOSITORY           TAG         IMAGE ID docker/whalesay      latest      fb434121fc77 hello-world          latest      91c95931e552 hello-world          v1.1        91c95931e552 hello-world          v1.0        1234abcd5678 

The repositories are: docker/whalesay, hello-world.

The images are fb434121fc77, 91c95931e552, 1234abcd5678. Notice that the 2nd and 3rd rows have the same Image ID, so they are the same image.

The image aliases are:

docker/whalesay:latest hello-world:latest hello-world:v1.1 hello-world:v1.0 

So hello-world:latest and hello-world:v1.1 are simply two aliases for the same image.

Additional Details:

• Repository name format can also prepend an optional user or namespace, which is useful when using a public registry like Docker Hub. E.g. docker/whalesay. Otherwise, you will have a lot of repository name conflicts.

• If you leave out the tag when referencing an image alias, it will automatically add :latest. So when you specify hello-world, it will be interpreted as hello-world:latest. Warning: latest doesn't actually mean anything special, it's just a default tag.

• ^[1] Actually, the full Image ID is a 64 digit hex code truncated to 12 digits, but you don't need to care about that.

Answer 2

Quoted from the official Docker documentation:

A repository potentially holds multiple variants of an image.

(see: https://docs.docker.com/userguide/dockerimages)

This means: A Docker image can belong to a repository, e.g. when it was pushed to a Docker registry (with docker push my/reporitory:version1). On the other side, a repository contains multiple versions of an image (= different tags). So when you build an new version of your image, you can give it a tag (docker tag 518a41981a6a my/reporitory:version2) and push it to your repository as the next version (docker push my/reporitory:version2).

Here's an example from the Docker documentation (see the link above). As you can see, it shows one repository called ouruser/sinatra which contains various versions (latest, devel, v2) of the same image:

$ docker images ouruser/sinatra REPOSITORY          TAG     IMAGE ID      CREATED        VIRTUAL SIZE ouruser/sinatra     latest  5db5f8471261  11 hours ago   446.7 MB ouruser/sinatra     devel   5db5f8471261  11 hours ago   446.7 MB ouruser/sinatra     v2      5db5f8471261  11 hours ago   446.7 MB 

In your example, you have two repositories (docker/whalesay and hello-world) which only contains one tagged image (called latest, which just means there is not tag actually and the latest images is shown).