186

I'm confused as to the difference between docker registries and repositories. It seems like the Docker documentation uses the two words interchangeably. Also, repositories are sometimes referred to as images, such as this from their docs:

In order to push a repository to its registry, you need to have named an image or committed your container to a named image as we saw here.

Now you can push this repository to the registry designated by its name or tag.

How can you push a repository to a registry? Aren't you pushing the image to the repository?

Kingamere
  • 9,496
  • 23
  • 71
  • 110
  • 5
    what about docker images vs docker repositories? – Charlie Parker Dec 15 '16 at 06:21
  • 1
    for images vs repositories: https://stackoverflow.com/questions/31115098/in-docker-what-is-the-difference-between-an-image-and-a-repository – wisbucky Sep 07 '17 at 18:24
  • 4
    if you know `git`, then - Docker *Registry* (default is `hub.docker.com`) => GitHub (`github.com`); - Docker *Repository* => Git Repository; - Docker *Tag* => Git Ref (Branch/Tag) – go2null Nov 19 '19 at 00:50
  • To better map Docker to Git: • Docker Registry = Git Server • Docker Repository = Git Repository • Docker Tag = Git Tag (more or less) – Simon Woodside Jun 29 '20 at 17:53

8 Answers8

220

Docker registry is a service that is storing your docker images.

Docker registry could be hosted by a third party, as public or private registry, like one of the following registries:

or you can host the docker registry by yourself
(see https://docs.docker.com/ee/dtr/ for more details).

Docker repository is a collection of different docker images with same name, that have different tags. Tag is alphanumeric identifier of the image within a repository.

For example see https://hub.docker.com/r/library/python/tags/. There are many different tags for the official python image, these tags are all members of the official python repository on the Docker Hub. Docker Hub is a Docker Registry hosted by Docker.

To find out more read:

Mohsen Abasi
  • 2,050
  • 28
  • 30
Nemanja Trifunovic
  • 3,017
  • 1
  • 17
  • 20
  • 12
    Artifactory is one to add to the list ;) We use that – buildmaestro Apr 05 '16 at 22:04
  • 3
    And that's the link for Artifactory - https://www.jfrog.com/confluence/display/RTF/Docker+Registry – JBaruch Sep 14 '16 at 22:22
  • 2
    what is the difference between repository and images in docker? – Charlie Parker Dec 15 '16 at 06:21
  • 1
    Repository can store multiple different images marked by tags. – Nemanja Trifunovic Dec 15 '16 at 09:18
  • 2
    Why does it make sense to have a single image have multiple tags? – Charlie Parker Dec 16 '16 at 00:01
  • 1
    Does this mean when I install docker and build them locally I have a local repository (which isn't public)? – basickarl Feb 15 '17 at 11:12
  • Also consider VMware's Project Harbor which is an enterprise-class registry server that stores and distributes Docker images: http://vmware.github.io/harbor/ – Sophie Gairo May 31 '17 at 15:59
  • there is some specific advantage to host the registry by oneself ? and does it means host it locally n my computer ? thanks – Webwoman Sep 04 '18 at 19:33
  • Thanks you, a very precise and understandable post, I've found it very helpful – OfirYaron Oct 23 '18 at 07:05
  • 1
    Very helpful! This statement was gold for me understanding the terms: `"Docker repository is a collection of different docker images with same name, that have different tags."` – akagixxer Dec 31 '19 at 16:46
  • The images don't *have* to be related. I found out that I was limited in the number of private repositories I could create on DockerHub, so I couldn't have one repo per product, but I could upload any number of images to one repository with arbitrary tag names, then I just used one repository called `monorepo` and my tag names are comprised of both _product_ and _version_. e.g.: `company/monorepo:product-one-v1.0.0`, and `company/monorepo:product-two-v1.0.0`, etc. Clearly *not* what Docker intended me to do though, as I feel like I've circumvented something in doing so. – Wyck May 25 '21 at 03:55
80

From the book Using Docker, Developing and deploying Software with Containers

Registries, Repositories, Images, and Tags

There is a hierarchical system for storing images. The following terminology is used:

Registry

A service responsible for hosting and distributing images. The default registry is the Docker Hub.

Repository

A collection of related images (usually providing different versions of the same application or service).

Tag

An alphanumeric identifier attached to images within a repository (e.g., 14.04 or stable ).

So the command docker pull amouat/revealjs:latest will download the image tagged latest within the amouat/revealjs repository from the Docker Hub registry.

Community
  • 1
  • 1
  • 1
    so can one have multiple tags for a single image? – Charlie Parker Dec 16 '16 at 00:02
  • 1
    @charlie Yes. For example, right now `ubuntu:latest` and `ubuntu:16.04` have the same `Image ID`, which means they are just multiple tags for the same image. – wisbucky Sep 07 '17 at 17:58
  • Where this breaks down is in the documentation for `docker pull`, which reads in part: "To download a particular image, or set of images (i.e., a repository), use `docker pull`. If no tag is provided, Docker Engine uses the `:latest` tag as a default." How, then, would one "download a…set of images (i.e. a repository)"? – Laird Nelson Sep 19 '17 at 03:33
  • 1
    random info: the default registry url is docker.io – yosefrow Aug 29 '19 at 13:29
  • 1
    I visualize this like a tree with registry being the root that has several children repositories and each of these repositories has images:tag as its children. Each of these levels has a particular role - a registry is like a hosting location and a repository is a directory of images. Is my understanding correct? – Ultrablendz Oct 14 '19 at 22:25
  • Confusion starts with the definition of tag: "An .. identifier attached to images..." Tha tis what humans most often refer to when they refer to tags. E.g. `latest` is the default tag. – Jürgen Weigert May 20 '22 at 16:01
16

Complementing the information:

  • You usually push a repository to a registry (and all images that are part of it). But you can push a single image to a registry. In all cases, you use docker push.
  • An image has a 12-hex-digit Image ID, but is also identified by: namespace/repo-name:tag
  • The image full name can be optionally prefixed by the registry host name and port: myregistryhost:5000/namespace/repo-name:tag
  • A common naming convention is to use your registry user-name as what I called "namespace".
Paulo Merson
  • 13,270
  • 8
  • 79
  • 72
  • 4
    I get what you're saying, but technically there is no such thing as `image-name`. The format should be `user-name/repo-name:tag`, according to [Docker documentation](https://docs.docker.com/docker-hub/repos/#pushing-a-repository-image-to-docker-hub). (I wish Docker had used better terminology, it's pretty confusing, and they're not even consistent all the time). – wisbucky Sep 07 '17 at 18:24
  • @wisbucky Thanks! I updated my answer. Indeed the documentation was not that good when I answered this question a year ago. For example, back then I created an issue on the docker github repo because the docker glossary did not contain "layer" and "namespace"(!) – Paulo Merson Sep 08 '17 at 16:46
  • 1
    And how does docker work out the IP address of a public registry when you just put something like nimmis/docker-alpine-java:latest – Adam Nov 23 '17 at 15:46
  • 1
    Oooops - `docker info |grep Registry` – Adam Nov 23 '17 at 16:27
4

A docker repository is a cute combination of registry and image. 

docker tag foo <registry>/<image>:<tag>

is the same as

docker tag foo <repository>:<tag>
dhulihan
  • 11,053
  • 9
  • 40
  • 45
1

Docker Registry is a service, which you can either host yourself (Trusted and Private) or you can let docker hub be the host for this service. Usually, if your software is commercial, you will have hosted this as a "Private and Trusted" registry. For Java Developers, this is somewhat analogous to Maven Artifactory setup.

Docker Repository is a set of "Tagged" images. An example is that you might have tagged 5 of ubuntu:latest images:

a) Nano editor (image1_tag:v1)

b) A specific software 1 (image1_tag:v2)

c) Sudo (image1_tag:v3)

d) apache http daemon (image1_tag:v4)

e) tomcat (image1_tag:v5)

You can use docker push command to push each of the above images to your repository. As long as the repository names match, they will be pushed successfully, and appear under your chosen repository and correctly tagged.

Now, your question is, "So where is this repository hosted/who is managing the service"? That is where Docker Registry comes into picture. By default you will get a docker hub registry (Open Source) which you can use to keep your private/public repository. So without any modification, your images will be pushed to your private repository in docker hub. An example output when you pushing your image tags are the following:

docker@my-docker-vm:/$ docker push mydockerhub/my-helloworld-repo:my_tag
The push refers to repository [docker.io/mydockerhub/my-helloworld-repo]
bf41e934d39d: Pushed
70d93396f87f: Pushed
6ec525dfd060: Pushed
705419d10b13: Pushed
a4aaef726d02: Pushed
04964fddc946: Pushed
latest: digest: sha256:eb93c92351bce785aa3ec0de489cfeeaafd55b7d90adf95ecea02629b376e577 size: 1571
docker@my-docker-vm:/$

And if you type immediately docker images --digests -a you can confirm that your pushed image tags are now showing new signature against the private repository managed by docker hub registry.

ha9u63a7
  • 6,233
  • 16
  • 73
  • 108
  • "docker push command to push each of the above images to your repository" -- you don't push images to repositories, but repositories to registries. Or am I wrong? – The Impaler Jun 13 '19 at 17:17
1

A Docker image registry is the place to store all your Docker images. The image registry allows you to push and pull the container images as needed.

Registries can be private or public. When the registry is public, the images are shared with the whole world whereas in the private registry the images are shared only amongst the members of an enterprise or a team.

A registry makes it possible for the Docker daemon to easily pull and run your Docker images.

Steffi Keran Rani J
  • 3,667
  • 4
  • 34
  • 56
0

Docker Hub and other third party repository hosting services are called “registries”. A registry stores a collection of repositories.

As a registry can have many repositories and a repository can have many different versions of the same image which are individually versioned with tags.

a3y3
  • 1,025
  • 2
  • 10
  • 34
Abhishek Jain
  • 3,815
  • 2
  • 26
  • 26
0

The confusion starts with this definition of a tag: "An alphanumeric identifier attached to images in a repository"

I'd rather call that alphanumeric identifier that you append with a ':' a tag-suffix for now. When somebody says "'latest' is the default tag", then this kind of tag-suffix is meant.

In reality, the :latest' suffix is technically part of the tag. The entire name is a tag. All these are tags (possibly referring to the same image):

myimagename myimagename:latest username/theirimagename:1.0 myrepo:5000/username/imagename:1.0

(I say imagename here, just to illustrate the other main source of confusion. That's the repositoryname, of course. Sorry.)

Examples:

a) When you want to name your image while building, you use docker build -t thisname ... -- that is -t for tag, (not -n for name).

b) When you want to push that image to a registry, you need to have the full URL (starting with registryname and ending with a tag-suffix) as a tag:

docker tag thisname mylocalregistry:5000/username/repoimagething:1.0

Now you push the image known as thisname by saying:

docker push mylocalregistry:5000/username/repoimagething:1.0

Naming things is hard. Alas! A repository is not a "container" (aaargh...) where you put things in, that is what muggles think...

Jürgen Weigert
  • 2,618
  • 1
  • 16
  • 13
  • I'd refer to "the whole thing" as a reference, not a tag. Leave the definition of tag as only the part after the `:`. – BMitch May 20 '22 at 16:57