Introduction

In Docker Registry HTTP API V2, the closest thing to "list all images" is listing repositories through the catalog endpoint and then listing tags for each repository. That distinction matters because a registry stores repositories and tags, not a single flat list of image names in the way many people first expect.

Use the Catalog Endpoint to List Repositories

To get repository names, call the _catalog endpoint on the registry.

curl https://registry.example.com/v2/_catalog

A typical response looks like this:

1{
2  "repositories": [
3    "backend/api",
4    "frontend/web",
5    "tools/worker"
6  ]
7}

Those repository names are what many users casually call "images," but each repository can still contain multiple tags.

List Tags for Each Repository

After you know the repository name, query its tags explicitly.

curl https://registry.example.com/v2/backend/api/tags/list

Example response:

1{
2  "name": "backend/api",
3  "tags": ["1.0.0", "1.1.0", "latest"]
4}

If your goal is inventory, you usually need both steps: list repositories, then list tags for each repository.

Handle Authentication Properly

Private registries often require authentication. For basic auth, curl can send credentials directly:

curl -u username:password https://registry.example.com/v2/_catalog

Some registries instead require a bearer token flow. In those setups, the registry first challenges you, then you request a token and retry with an Authorization: Bearer ... header. The exact token flow depends on the registry and its auth service, so check that registry's operational documentation if a plain curl call returns 401 Unauthorized.

Use Pagination for Large Registries

Large registries may paginate the catalog response. The V2 API supports query parameters such as n for page size, and the registry can return a Link header telling you how to request the next page.

curl 'https://registry.example.com/v2/_catalog?n=100'

If a Link header is returned, follow that URL to continue until you have the full repository list. The same operational idea applies when inventories get too large for one response.

Know the Limits of the Catalog API

Not every registry deployment exposes the full catalog endpoint to all users. Some hosted registries or proxy layers restrict it for performance or security reasons. In those environments, you may need to rely on provider-specific APIs, UI tooling, or an allowlisted repository namespace rather than expecting _catalog to work globally.

That is why "Docker Registry V2" and "a Docker-compatible registry product" are not always operationally identical in practice.

Build a Practical Inventory Workflow

A reliable inventory process usually looks like this:

1. query _catalog
2. iterate through repository names
3. query /tags/list for each repository
4. record the results in your tooling

That gives you repository and tag visibility without requiring a Docker daemon on the machine performing the inventory.

Common Pitfalls

• Assuming _catalog already includes tag information.
• Forgetting that private registries may need bearer-token authentication instead of basic auth.
• Ignoring pagination and concluding that the first page is the full registry.
• Treating all Docker-compatible registries as if they expose the exact same endpoints operationally.
• Asking the registry for a flat "list of images" without deciding whether you really need repositories, tags, or manifests.

Summary

• Use /v2/_catalog to list repository names in a Registry V2 API.
• Use /v2/<repository>/tags/list to list tags for each repository.
• Handle authentication before assuming the endpoint is unavailable.
• Follow pagination when the registry returns partial results.
• Decide whether your inventory needs repositories, tags, or deeper manifest details before designing the query flow.