What is the difference between an image and a repository?

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.

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.

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).

It's easiest to define several terms here because they all interrelate:

Image: This is the filesystem layers and metadata used to package an application in a way to run containers. Each image must have an ID on a docker engine.

Reference: This is a pointer to an image. There are different types of references, either just the image ID, usually the it is a repository and tag, and sometimes you will pin to a specific checksum using a sha256 hash instead of a changeable tag. The important part is that you can have multiple pointers to the same image, and that it is not necessary to have any references to an image other than the image ID. When you delete a reference, docker will just delete that pointer unless it was the last pointer to that image ID.

Registry: This is a server that holds images. Similar to how a Git server holds source code, or an artifact server for binaries, a registry is where you push and pull images to and from.

Repository: The path to a directory of images on a registry server is the repository. This includes the registry hostname and port if you aren't using the default Docker Hub registry. In an image reference, this repository is the part before the final colon and tag.

Tag: A specific image within a repository. If you do not specify a tag, docker will default to the tag name "latest". This is the part after the final colon, and is often used for a version number.

---

To take an example reference:

registry-server:5000/team/service-a:build-42

• "registry-server:5000" is the registry server name (and port) where you would push/pull this image.

• "registry-server:5000/team/service-a" is the repository.

• "build-42" is the tag.

• "registry-server:5000/team/service-a:build-42" is a reference.

Unlike other systems where you push and pull to a server and then specific what files to send there, pushing and pulling docker images to and from a registry server defines the destination and source of the image using a reference that includes the repository and tag in that name. So to push images to a different location, you create a new reference (using the docker tag command) to the same image with the new repository and tag, and then run your push command against that reference.

Typically when someone refers to an "image name" they are referring to either a repository name (if you want to specify a tag separately) or a complete reference that you can use to pull or push an image.

---

> how can I just list my repositories?

docker image ls --format '{{.Repository}}' | sort -u

I included the sort -u to de-dup the output since you may have multiple images with the same repository and different tags.

Images are built by running docker build with a given Dockerfile and are identified by their ID.

Repositories and Tags are just means to name and organize your images in a meaningful hierarchies/architectures.

• A repository typically contains multiple related images

• An image can go into multiple repositories

The following, from this SO answer, gives detailed explanation of docker imagesoutput (This is probably what they should have put in the docs):

> 1. IMAGE ID is the first 12 characters of the true identifier for an image. You can create many tags of a given image, but their IDs will > all be the same (as above).

> 3. The value in the REPOSITORY column comes from the -t flag of the docker build command, or from docker tag-ing an existing image. > You're free to tag images using a nomenclature that makes sense to > you, but know that docker will use the tag as the registry location in > a docker push or docker pull. > 4. The full form of a tag is [REGISTRYHOST/][USERNAME/]NAME[:TAG]. For ubuntu above, REGISTRYHOST is inferred to be > registry.hub.docker.com. So if you plan on storing your image called > my-application in a registry at docker.example.com, you should tag > that image docker.example.com/my-application. > 5. The TAG column is just the [:TAG] part of the full tag. This is unfortunate terminology.

I will try to explain this in a very sharp and clear manner.

Docker Image Name
Docker Image actually doesn’t have a name per se. It has an ID, Repository and a Tag (which, according to Docker docs, stands by the way for Target Image, not the English word tag). So, each time we refer to Docker Image name (either creating, running, removing, pulling it or etc.) we actually refer to the Image Repository:Tag (target image).
We just quite often happen to omit the tag part (by just writing the repository name, which we consider as an Image name), and that’s when docker assumes default tag which is :latest (i.e. Target image latest)

Docker Repository
Docker, when building/creating an Image, creates repository for that image and Image itself, it then adds that current (:latest tag) image into that repository. According to Kubernetes in Action by Marko Luksa, Image tags enable us to have several versions (tags) of the same image under the same image name. So we may have myapp:latest, myapp:v1, myapp:v2 all under one identifier and each tag here will refer to a particular target image, i.e. particular snapshop/version of the same app.
That's why docker names the Image Repository and leaves the differentiation job to tag, as one repository should (and must) probably contain different versions of the same application.

So, if we run docker build -t A ., docker will actually create an Image Repository A and the Image itself (with :latest tag). It will then add that image into repository A. Later on, we’ll be able to push/pull particular snapshots of that image.

P. S.
The way we're used to call Docker Image name, is (and can be assumed as) actually Docker Image Repository[:tagname] and the latter is optional, by default :latest

You can test all this and prove to yourself by trying to remove the image without specifying tag to it and when that image repository doesn't have a default :latest image in it. Just run docker rmi myimage and you'll see, that docker will complain, saying Error: No such image: myiamge as by default (when you don't provide tag) it assumes and implies :latest tag.

Hope this sheds more light on this topic.