docker docker-registry

How to get a list of images on docker registry v2


I’m using docker registry v1 and I’m interested in migrating to the newer version, v2. But I need some way to get a list of images present on registry; for example with registry v1 I can execute a GET request to http://myregistry:5000/v1/search? and the result is:

  "num_results": 2,
  "query": "",
  "results": [
      "description": "",
      "name": "deis/router"
      "description": "",
      "name": "deis/database"

But I can’t find on official documentation something similar to get a list of image on registry. Anybody knows a way to do it on new version v2?


  • Still not enough. Need the dates of the image creation and image push, and hopefully include/suppress prior tag versions. There’s got to be an actual web interface, too, right? I’m talking to our admin – we’ve only got 2.0

    Feb 11, 2016 at 16:33

  • 1 seems to have a different API, e.g. to list tags of a repository: curl -sSX GET ''. Or you can make use of docker-hub-api.

    – x-yuri

    Mar 12, 2021 at 12:05

  • I can’t believe docker cli does not have this build in 😐 you have already logged in via “docker login”, so why not provide a command like docker images ls --in-repo=XXX

    – Eugene

    May 18 at 15:15

  • I’am trying to acces public hub.docker with my private repository, which i added some images on private, but it don’t work, if you have any ideas

    Sep 12 at 12:08


For the latest (as of 2015-07-31) version of Registry V2, you can get this image from DockerHub:

docker pull distribution/registry:master

List all repositories (effectively images):

curl -X GET https://myregistry:5000/v2/_catalog
> {"repositories":["redis","ubuntu"]}

List all tags for a repository:

curl -X GET https://myregistry:5000/v2/ubuntu/tags/list
> {"name":"ubuntu","tags":["14.04"]}

If the registry needs authentication you have to specify username and password in the curl command

curl -X GET -u <user>:<pass> https://myregistry:5000/v2/_catalog
curl -X GET -u <user>:<pass> https://myregistry:5000/v2/ubuntu/tags/list


  • 5

    Where do you get the certificate from?

    – duality_

    Jan 26, 2017 at 9:43

  • 4

    @duality in case your registry is using either a self-signed certificate, or a certificate signed by an untrusted root CA, you need to supply the certificate to curl to establish a secure connection. To make an insecure connection you could add the ‘–insecure’ flag instead.

    – jonatan

    Jan 26, 2017 at 19:10

  • 6

    -k, –insecure (SSL)

    – Ilja

    Mar 23, 2017 at 9:57

  • 17

    Default result only show 100 images record, but if you need to show more you can paginate the result with this query: http://<registry-url>/v2/_catalog?n=<count> with count for example 2000.

    Apr 17, 2018 at 14:54

  • 30

    If the registry is password protected, use curl -u <user>:<pass> -X GET ...

    – nsantos

    Mar 4, 2019 at 10:02


you can search on




Get catalogs

Default, registry api return 100 entries of catalog, there is the code:

When you curl the registry api:

curl --cacert domain.crt https://your.registry:5000/v2/_catalog

it equivalents with:

curl --cacert domain.crt https://your.registry:5000/v2/_catalog?n=100

This is a pagination methond.

When the sum of entries beyond 100, you can do in two ways:

First: give a bigger number

curl --cacert domain.crt https://your.registry:5000/v2/_catalog?n=2000

Second: parse the next linker url

curl --cacert domain.crt https://your.registry:5000/v2/_catalog

A link element contained in response header:

curl --cacert domain.crt https://your.registry:5000/v2/_catalog

response header:

Link: </v2/_catalog?last=pro-octopus-ws&n=100>; rel="next"

The link element have the last entry of this request, then you can request the next ‘page’:

curl --cacert domain.crt https://your.registry:5000/v2/_catalog?last=pro-octopus-ws

If the response header contains link element, you can do it in a loop.

Get Images

When you get the result of catalog, it like follows:

   "repositories": [

you can get the images in every catalog:

curl --cacert domain.crt https://your.registry:5000/v2/busybox/tags/list




  • 1

    100 entries defined here

    – litanhua

    Mar 24, 2017 at 6:41

  • 3

    This should be the accepted answer. It is the only answer that explains how you get around the dreaded pagination. The currently accepted answer (jonatan) only shows images starting with “a”.

    Oct 15, 2018 at 11:34

  • 1

    and how would you get tags list for ceph/mds? in general, for any repository defined with //v2/_catalog/ceph/mdt/tags/list doesn’t work

    – tymik

    Nov 18, 2019 at 15:56

  • @tymik we can access tags list for repos containing / in their names by using /v2/ceph/mdt/tags/list i.e. by omitting _catalog (works for repos without / as well) ref:

    Nov 1, 2021 at 5:31