How to get a list of images on docker registry v2

Question

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 — Andrew Wolfe, Feb 11 '16 at 16:33
hub.docker.com seems to have a different API, e.g. to list tags of a repository: `curl -sSX GET 'https://hub.docker.com/v2/repositories/library/php/tags?page_size=100'`. Or you can make use of [`docker-hub-api`](https://www.npmjs.com/package/docker-hub-api). — x-yuri, Mar 12 '21 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 '22 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 — Zemmouri Tarek, Sep 12 '22 at 12:08

score 657 · Accepted Answer · edited Apr 20 '21 at 14:00

657

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

edited Apr 20 '21 at 14:00

Andrea Baldini

1,027
1
6
17

answered Jul 31 '15 at 16:04

jonatan

9,011
2
30
34

6

Where do you get the certificate from? – duality_ Jan 26 '17 at 09: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 '17 at 19:10
8

-k, --insecure (SSL) – Ilja Mar 23 '17 at 09:57
3

Check also which port the docker-registry is using, on the host itself. It may be mapped to 5000 internally, but on the outside, using another one. For me that was the case, as it was using 443:5000, and then the command worked with 443 instead. – gorjanz Nov 16 '17 at 09:30
19

Default result only show 100 images record, but if you need to show more you can paginate the result with this query: `http:///v2/_catalog?n=` with count for example 2000. – enrique-carbonell Apr 17 '18 at 14:54
30

If the registry is password protected, use `curl -u : -X GET ...` – nsantos Mar 04 '19 at 10:02
No port number required for me to access azurecr.io – Heath Raftery May 08 '19 at 05:38
just use `-u ` without password on the command line; you will be prompted to type the password, invisibly – Roland Mar 08 '23 at 12:05

score 113 · Answer 2 · answered Feb 14 '17 at 07:31

113

you can search on

http://<ip/hostname>:<port>/v2/_catalog

answered Feb 14 '17 at 07:31

Abhishek Jaiswal

2,524
1
21
24

8

...as of more recently I'd just like to add that https is required instead of just http – Nikola May 16 '17 at 08:15
4

I see no such need for my recently installed Docker Registry! – Enok82 Sep 18 '18 at 07:52
http://localhost:5000/v2/_catalog -- If you have been following the [Deploy a registry server document](https://docs.docker.com/registry/deploying/). – Vijay Nandwana Feb 09 '22 at 13:02
Website is not reachable via browser ... – testing May 05 '22 at 14:20
Docker registry doesnt have any kind of authentication nor authorization (I suspect thats the main selling point of hub.docker) - that why you set up reverse proxy (Traefik, NGINX). And sane reverse proxy will NOT send `WWW-Authenticate: Basic realm="whatever"` (prompt for BASIC credentials) over http - you certainly wouldn't send `name:password` in cleartext over http, wouldn't you... So SSL (https) is (when you use BASIC auth) and is not (when you dont) required - but it has nothing to do with registries, but with your reverse proxy. – Jan 'splite' K. Jul 31 '23 at 07:24

score 68 · Answer 3 · edited Nov 02 '22 at 09:52

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": [
      "busybox",
      "ceph/mds"
   ]
}

you can get the images in every catalog:

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

returns:

{"name":"busybox","tags":["latest"]}

100 entries defined [here](https://github.com/docker/distribution/blob/b6e0cfbdaa1ddc3a17c95142c7bf6e42c5567370/registry/handlers/catalog.go) — litanhua, Mar 24 '17 at 06:41
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". — user2394284, Oct 15 '18 at 11:34
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 '19 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: https://docs.docker.com/registry/spec/api/#listing-image-tags — Momin Bin Shahid, Nov 01 '21 at 05:31

score 28 · Answer 4 · answered Jul 28 '15 at 11:27

The latest version of Docker Registry available from https://github.com/docker/distribution supports Catalog API. (v2/_catalog). This allows for capability to search repositories

If interested, you can try docker image registry CLI I built to make it easy for using the search features in the new Docker Registry distribution (https://github.com/vivekjuneja/docker_registry_cli)

score 26 · Answer 5 · edited Nov 07 '17 at 18:53

This has been driving me crazy, but I finally put all the pieces together. As of 1/25/2015, I've confirmed that it is possible to list the images in the docker V2 registry ( exactly as @jonatan mentioned, above. )

I would up-vote that answer, if I had the rep for it.

Instead, I'll expand on the answer. Since registry V2 is made with security in mind, I think it's appropriate to include how to set it up with a self signed cert, and run the container with that cert in order that an https call can be made to it with that cert:

This is the script I actually use to start the registry:

sudo docker stop registry
sudo docker rm -v registry
sudo docker run -d \
  -p 5001:5001 \
  -p 5000:5000 \
  --restart=always \
  --name registry \
  -v /data/registry:/var/lib/registry \
  -v /root/certs:/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \ 
  -e REGISTRY_HTTP_DEBUG_ADDR=':5001' \
  registry:2.2.1

This may be obvious to some, but I always get mixed up with keys and certs. The file that needs to be referenced to make the call @jonaton mentions above**, is the domain.crt listed above. ( Since I put domain.crt in /root, I made a copy into the user directory where it could be accessed. )

curl --cacert ~/domain.crt https://myregistry:5000/v2/_catalog
> {"repositories":["redis","ubuntu"]}

**The command above has been changed: -X GET didn't actually work when I tried it.

Note: https://myregistry:5000 ( as above ) must match the domain given to the cert generated.

score 24 · Answer 6 · answered Mar 03 '16 at 08:49

24

We wrote a CLI tool for this purpose: docker-ls It allows you to browse a docker registry and supports authentication via token or basic auth.

answered Mar 03 '16 at 08:49

Christian Speckner

241
2
5

score 12 · Answer 7 · answered Nov 27 '18 at 16:07

12

Here is a nice little one liner (uses JQ) to print out a list of Repos and associated tags.

If you dont have jq installed you can use: brew install jq

# This is my URL but you can use any
REPO_URL=10.230.47.94:443

curl -k -s -X GET https://$REPO_URL/v2/_catalog \
 | jq '.repositories[]' \
 | sort \
 | xargs -I _ curl -s -k -X GET https://$REPO_URL/v2/_/tags/list

answered Nov 27 '18 at 16:07

Jeef

26,861
21
78
156

argh, I just wrote this then found yours :S but I'll keep my answer because it shows how to handle Basic auth too, and it explains why it works. Also filters the result into a flat image list. – Craig Ringer Jan 30 '19 at 09:29
Just for in case jq is not in your Linux distro, get it her https://stedolan.github.io/jq/download/ It's a very useful little tool. – ISQ Apr 13 '19 at 16:45

score 10 · Answer 8 · edited Jan 26 '17 at 22:26

10

Install registry:2.1.1 or later (you can check the last one, here) and use GET /v2/_catalog to get list.

https://github.com/docker/distribution/blob/master/docs/spec/api.md#listing-repositories

Lista all images by Shell script example: https://gist.github.com/OndrejP/a2386d08e5308b0776c0

edited Jan 26 '17 at 22:26

Mario S

1,914
1
19
32

answered Sep 22 '15 at 07:27

Ondrej Prochazka

740
8
10

score 10 · Answer 9 · answered Sep 13 '18 at 05:14

I had to do the same here and the above works except I had to provide login details as it was a local docker repository.

It is as per the above but with supplying the username/password in the URL.

curl -k -X GET https://yourusername:yourpassword@theregistryURL/v2/_catalog

It comes back as unformatted JSON.

I piped it through the python formatter for ease of human reading, in case you would like to have it in this format.

curl -k -X GET https://yourusername:yourpassword@theregistryURL/v2/_catalog | python -m json.tool

score 9 · Answer 10 · answered Jan 30 '19 at 09:28

Here's an example that lists all tags of all images on the registry. It handles a registry configured for HTTP Basic auth too.

THE_REGISTRY=localhost:5000

# Get username:password from docker configuration. You could
# inject these some other way instead if you wanted.
CREDS=$(jq -r ".[\"auths\"][\"$THE_REGISTRY\"][\"auth\"]" .docker/config.json | base64 -d)

curl -s --user $CREDS https://$THE_REGISTRY/v2/_catalog | \
    jq -r '.["repositories"][]' | \
    xargs -I @REPO@ curl -s --user $CREDS https://$THE_REGISTRY/v2/@REPO@/tags/list | \
    jq -M '.["name"] + ":" + .["tags"][]'

Explanation:

extract username:password from .docker/config.json
make a https request to the registry to list all "repositories"
filter the json result to a flat list of repository names
for each repository name:
make a https request to the registry to list all "tags" for that "repository"
filter the stream of result json objects, printing "repository":"tag" pairs for each tag found in each repository

Nice. Simple use of the API and plain old shell level tools. — Daniel Holmes, May 25 '21 at 19:01

score 6 · Answer 11 · answered Jun 13 '19 at 09:24

6

Using "/v2/_catalog" and "/tags/list" endpoints you can't really list all the images. If you pushed a few different images and tagged them "latest" you can't really list the old images! You can still pull them if you refer to them using digest "docker pull ubuntu@sha256:ac13c5d2...". So the answer is - there is no way to list images you can only list tags which is not the same

answered Jun 13 '19 at 09:24

user1616472

61
1
1

Absolutely. If there are images that don't possess a single tag, and instead only possess digests e.g. `ubuntu@sha256:ac13c5d2`, those will be omitted from the output. If a registry contained `ubuntu@sha256:ac13c5d2`, `alpine:latest`, and `postgres:15.1`, Output from /v2/_catalog would read as `{"repositories":["alpine","postgres"]}`. – Dbercules Nov 23 '22 at 13:51

score 5 · Answer 12 · answered Feb 11 '17 at 18:39

I wrote an easy-to-use command line tool for listing images in various ways (like list all images, list all tags of those images, list all layers of those tags).

It also allows you to delete unused images in various ways, like delete only older tags of a single image or from all images etc. This is convenient when you are filling your registry from a CI server and want to keep only latest/stable versions.

It is written in python and does not need you to download bulky big custom registry images.

score 4 · Answer 13 · answered Jul 19 '18 at 08:51

If some on get this far.

Taking what others have already said above. Here is a one-liner that puts the answer into a text file formatted, json.

curl "http://mydocker.registry.domain/v2/_catalog?n=2000" | jq . - > /tmp/registry.lst

This looks like

{
  "repositories": [
    "somerepo/somecontiner",
    "somerepo_other/someothercontiner",
 ...
  ]
}

You might need to change the `?n=xxxx' to match how many containers you have.

Next is a way to automatically remove old and unused containers.

Bradley Allen · Answer 14 · 2020-11-12T15:00:25.510

Docker search registry v2 functionality is currently not supported at the time of this writing. See discussion since Feb 2015: "propose registry search functionality #206" https://github.com/docker/distribution/issues/206

I wrote a script, view-private-registry, that you can find: https://github.com/BradleyA/Search-docker-registry-v2-script.1.0 It is not pretty but it gets the information needed from the private registry.

Example of output from view-private-registry:

$ view-private-registry`
busybox:latest
gcr.io/google_containers/etcd:2.0.9
gcr.io/google_containers/hyperkube:v0.21.2
gcr.io/google_containers/pause:0.8.0
google/cadvisor:latest
jenkins:latest
logstash:latest
mongo:latest
nginx:latest
python:2.7
redis:latest
registry:2.1.1
stackengine/controller:latest
tomcat:7
tomcat:latest
ubuntu:14.04.2
Number of images:   16
Disk space used:    1.7G    /mnt/three/docker-registry/registry-data

score 3 · Answer 15 · answered May 21 '20 at 10:14

3

This threads dates back a long time, the most recents tools that one should consider are skopeo and crane.

skopeo supports signing and has many other features, while crane is a bit more minimalistic and I found it easier to integrate with in a simple shell script.

answered May 21 '20 at 10:14

errordeveloper

6,716
6
41
54

1

These are great tools, especially if you have special authentication requirements (e.g. ActiveDirectory). – Max Leske Oct 02 '20 at 09:41

estani · Answer 16 · 2022-07-26T10:33:46.820

One liner bash to list all images with their tags:

curl --user user:pass https://myregistry.com/v2/_catalog | jq .repositories | sed -n 's/[ ",]//gp' | xargs -L1 -IIMAGE curl -s --user user:pass https://myregistry.com/v2/IMAGE/tags/list | jq '. as $parent | .tags[] | $parent.name + ":" + . '

Two lines to search for something in the image name:

search=my_container_part_name
curl --user user:pass https://registry.medworx.io/v2/_catalog | jq .repositories | sed -n '/'"$search"'/{s/[ ",]//gp;}' | xargs -L1 -IIMAGE curl -s --user user:pass https://registry.medworx.io/v2/IMAGE/tags/list | jq '. as $parent | .tags[] | $parent.name + ":" + . '

replace: user, pass and myregistry.com accordingly

uses curl, sed, xargs and jq and is hard to understand... but it does the job. It produces one call per image + 1.

score 3 · Answer 17 · answered Jan 16 '23 at 19:12

3

If, the accepted answer here only returns a blank line, it is likely because of your ssl/tls cert on your registry server. Use the --insecure flag:

curl --insecure https://<registryHostnameOrIP>:5000/v2/_catalog

answered Jan 16 '23 at 19:12

Adam Winter

1,680
1
12
26

score 1 · Answer 18 · answered Oct 12 '22 at 01:45

If you can ssh or attach to the docker registry container, just browse the filesystem to look for things you want, like:

kubectl exec -it docker-registry-0 -- /bin/sh

ls /var/lib/registry/docker/registry/v2/repositories
ls /var/lib/registry/docker/registry/v2/repositories/busybox/_manifests/tags/

score 1 · Answer 19 · answered Jul 09 '23 at 16:02

Here is a simple bash script to view and explore a list of catalogs and tags in a self hosted registry. It uses the API exposed in the registry docker image. If you have jless installed it makes viewing a little bit nicer.

#!/bin/bash
REGISTRY="https://my.registry.internal:5000"

curl -s GET $REGISTRY/v2/_catalog
echo "Enter name to get tags:"
read REPO

if command -v jless &> /dev/null
then
  curl -s GET $REGISTRY/v2/$REPO/tags/list | jless
else
  curl -s GET $REGISTRY/v2/$REPO/tags/list
fi

score 0 · Answer 20 · edited Aug 05 '15 at 17:51

0

Since each registry runs as a container the container ID has an associated log file ID-json.log this log file contains the vars.name=[image] and vars.reference=[tag]. A script can be used to extrapolate and print these. This is perhaps one method to list images pushed to registry V2-2.0.1.

edited Aug 05 '15 at 17:51

Phil Pinkerton

1
3

answered Aug 04 '15 at 15:24

Phil Pinkerton

1

F1Linux · Answer 21 · 2021-12-16T20:10:47.143

If your use-case is identifying only SIGNED and TRUSTED images for production, then this method is handy.

It parses a docker image repo for all SIGNED tags and strips away all the JSON formatting, puking-out only clean image tags. Which of course can be processed further according to your requirements.

Format of Command:

docker trust inspect imageName | grep "SignedTag" | awk -F'"' '{print $4}'

Examples using the nginx & Bitnami Docker repos:

docker trust inspect nginx | grep "SignedTag" | awk -F'"' '{print $4}'

docker trust inspect bitnami/java | grep "SignedTag" | awk -F'"' '{print $4}'

If there are no signed images then No signatures or cannot access imageName will be returned.

Example of a repo WITHOUT signed images (at the time of this writing) using the Wordpress Docker repo:

docker trust inspect wordpress | grep "SignedTag" | awk -F'"' '{print $4}'

score 0 · Answer 22 · answered Jul 06 '22 at 18:31

0

If you want a nice web interface to your registry you can use this registry-browser docker image. This is useful if you just want to look around your registry, different repositories and tags.

answered Jul 06 '22 at 18:31

jai.maruthi

157
5

As it’s currently written, your answer is unclear. Please [edit] to add additional details that will help others understand how this addresses the question asked. You can find more information on how to write good answers [in the help center](/help/how-to-answer). – Community Jul 12 '22 at 18:14

How to get a list of images on docker registry v2

22 Answers22

Get catalogs

Get Images

Linked