How to List Docker Images in a Remote Registry

There's no docker images equivalent for remote registries, the Docker CLI only shows what's already pulled to your local machine. To see what's sitting in a remote registry, you have to go through the registry's API or a cloud-specific CLI. The exact method depends on where your images live.

This article covers the four most common situations: self-hosted registries using the standard Docker Registry v2 API, Docker Hub, AWS ECR, and Google Artifact Registry / Azure ACR.

Self-hosted private registry (Registry v2 API)

Any registry that implements the Docker Registry HTTP API v2 spec (Harbor, Nexus, GitLab Container Registry, and the official registry:2 image) exposes a _catalog endpoint that returns the list of repositories.

To list all repositories in your registry, run:

bash

1
curl -X GET https://my-registry.example.com/v2/_catalog

If authentication is enabled, pass credentials with -u:

bash

1
curl -u myuser:mypassword -X GET https://my-registry.example.com/v2/_catalog

The response looks like this:

json

1
{"repositories":["myapp/api","myapp/worker","base/python"]}

That gives you repository names, but not tags. To list tags for a specific image, hit the tags endpoint:

bash

1
curl -u myuser:mypassword -X GET https://my-registry.example.com/v2/myapp/api/tags/list

json

1
{"name":"myapp/api","tags":["latest","v1.2.0","v1.1.3","v1.0.0"]}

For registries with a large catalog, the _catalog endpoint paginates. Add ?n=<count> to control page size and use the last query parameter to advance through pages:

bash

12345
# First page: 50 repos
curl -u myuser:mypassword "https://my-registry.example.com/v2/_catalog?n=50"

# Next page: start after the last repo returned
curl -u myuser:mypassword "https://my-registry.example.com/v2/_catalog?n=50&last=myapp/worker"

The response also includes a Link header pointing to the next page when more results exist, so you can loop until no Link header appears.

Note on _catalog availability: Some managed registries disable the _catalog endpoint entirely for security reasons, since it exposes your full image inventory. AWS ECR, for example, doesn't support it. Check your registry's docs before assuming it'll work.

Docker Hub

Docker Hub runs the v2 registry protocol at registry-1.docker.io, but it uses a separate auth server and has its own API at hub.docker.com that's more practical for listing.

Listing tags for an image

For a quick tag list without authentication, use the Docker Hub API directly:

bash

12
curl -s "https://hub.docker.com/v2/repositories/library/nginx/tags?page_size=100" \
  | jq -r '.results[].name'

For unofficial (non-library) images, substitute the namespace:

bash

12
curl -s "https://hub.docker.com/v2/repositories/grafana/grafana/tags?page_size=100" \
  | jq -r '.results[].name'

Listing tags via the Registry v2 API

If you need to use the standard registry protocol (for example, in tooling that talks to any v2 registry), you first need a bearer token from Docker's auth server:

bash

123456
TOKEN=$(curl -s \
  "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/nginx:pull" \
  | jq -r .token)

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://registry-1.docker.io/v2/library/nginx/tags/list" | jq '.tags[]'

Docker Hub paginates results when an image has many tags. The response includes a Link header when there are more pages.

Listing your own repositories

To list all your repositories (public and private), authenticate first and query the Hub API:

bash

12345678
TOKEN=$(curl -s \
  -H "Content-Type: application/json" \
  -d '{"username":"<your-username>","password":"<your-password-or-pat>"}' \
  "https://hub.docker.com/v2/users/login" | jq -r .token)

curl -s -H "Authorization: JWT ${TOKEN}" \
  "https://hub.docker.com/v2/repositories/<your-username>/?page_size=100" \
  | jq -r '.results[].name'

Use a Personal Access Token instead of your password. It's scoped and revocable.

AWS ECR

ECR doesn't implement the standard _catalog endpoint, so you have to use the AWS CLI.

To list all repositories in your account and region:

bash

12
aws ecr describe-repositories --region us-east-1 \
  --query 'repositories[].repositoryName' --output table

To list images (and their tags) in a specific repository:

bash

1
aws ecr list-images --repository-name my-app --region us-east-1

json

1234567
{
  "imageIds": [
    {"imageDigest": "sha256:99c6fb43...", "imageTag": "v2.1.0"},
    {"imageDigest": "sha256:99c6fb43...", "imageTag": "latest"},
    {"imageDigest": "sha256:4a1c6567...", "imageTag": "v2.0.1"}
  ]
}

If you only want tagged images (skipping untagged layers):

bash

123
aws ecr list-images --repository-name my-app \
  --filter tagStatus=TAGGED \
  --query 'imageIds[].imageTag' --output text

For richer metadata (push timestamps, image sizes, vulnerability scan status), use describe-images instead:

bash

123
aws ecr describe-images --repository-name my-app \
  --query 'sort_by(imageDetails, &imagePushedAt)[-5:]' \
  --output table

That returns the five most recently pushed images, sorted by push time, which is useful if you're auditing what's currently deployed.

ECR is paginated. The CLI handles pagination automatically by default. If you're calling the API directly, handle nextToken yourself.

Google Artifact Registry

Google replaced the old Container Registry (gcr.io) with Artifact Registry. If you're still on gcr.io, the same gcloud commands work, but migrate: Container Registry reached end of life in May 2024.

To list images in a repository:

bash

123
gcloud artifacts docker images list \
  us-central1-docker.pkg.dev/my-project/my-repo \
  --include-tags

123
IMAGE                                                 TAGS      DIGEST          CREATE_TIME
us-central1-docker.pkg.dev/my-project/my-repo/api    latest    sha256:abc123   2026-04-01T12:00:00
us-central1-docker.pkg.dev/my-project/my-repo/api    v1.3.0    sha256:abc123   2026-04-01T12:00:00

To list all repositories in a project:

bash

1
gcloud artifacts repositories list --project=my-project --location=us-central1

Azure ACR

Azure Container Registry uses the az acr CLI. To list all repositories in your registry:

bash

1
az acr repository list --name myregistry --output table

To list tags for a specific image:

bash

1
az acr repository show-tags --name myregistry --repository myapp/api --output table

For detailed manifest metadata including digest, size, and last-modified:

bash

1
az acr manifest list-metadata --name myapp/api --registry myregistry

Cross-registry tools

If you're dealing with multiple registries and want a consistent interface, two tools are worth knowing:

Skopeo can list tags on any OCI-compliant registry without pulling the image:

bash

123
skopeo list-tags docker://my-registry.example.com/myapp/api
skopeo list-tags docker://docker.io/library/nginx
skopeo list-tags docker://123456789.dkr.ecr.us-east-1.amazonaws.com/my-app

crane from Google's go-containerregistry is similarly handy for scripting:

bash

12
crane ls my-registry.example.com/myapp/api
crane ls nginx  # Docker Hub shorthand

Both tools respect your existing Docker credential store, so if docker pull works, these will too.

Common pitfall: `_catalog` doesn't give you tags

A lot of people hit _catalog, get a list of repository names, and think they're done. They're not. Repository names and image tags are separate concepts. _catalog returns ["myapp/api", "myapp/worker"], but to know what versions of myapp/api are available, you still need to hit /v2/myapp/api/tags/list for each one. Don't mistake the catalog for inventory.

Final thoughts

The right tool depends on where your images live. For self-hosted registries, the v2 API is universal and scriptable. For cloud-managed registries, the vendor CLIs are more ergonomic and handle authentication and pagination transparently. For scripting across multiple registries, skopeo or crane give you a single consistent interface.

If you're running images in Kubernetes and want to correlate deployed image versions with what's actually running in production, Dash0's AI Control Plane for Production connects registry metadata to runtime telemetry so you can see exactly what's deployed, whether it matches the latest patched image, and where the gaps are. The Kubernetes ImagePullBackOff guide covers what happens when that gap causes a pull failure, and the Docker container monitoring guide shows how to track resource usage once your images are running.

Start a free trial to see your infrastructure telemetry alongside container and deployment data.