Learn Docker With My Newest Course

Dive into Docker takes you from "What is Docker?" to confidently applying Docker to your own projects. It's packed with best practices and examples. Start Learning Docker →

Using Docker's v2 API to Get a List of Tags with the Help of jq


Docker deprecated their v1 API in September 2022, now we can get a lot more details about each tag using the v2 API.

Quick Jump: Demo Video

In the past I’ve made a video about setting up a shell alias to easily list all available tags for a specific Docker image. That post is here. I’ve updated it for v2 but the video no longer matches the alias since the video was made years ago using the v1 API.

Here’d a revised video that uses v2 and goes over the basics of using jq too.

Demo Video


  • 0:15 – Docker turned off their Docker Hub API v1 endpoint in September 2022
  • 0:53 – Parsing the v2 API with this new alias using the jq tool
  • 1:33 – Checking out the dtags alias real quick
  • 4:22 – curling the API manually
  • 5:00 – Using jq to parse the JSON response
  • 6:41 – Sorting the results in a reasonable way
  • 8:00 – Checking out Docker’s API documentation
  • 9:08 – Docker’s documented max per page limit might be wrong

Code snippets

dtags () {
    local image="${1}"

    curl --silent \
        "https://registry.hub.docker.com/v2/repositories/library/${image}/tags?page_size=1000" \
        | jq -r ".results[].name" | sort --version-sort

What other Docker API endpoints do you use regularly?

Never Miss a Tip, Trick or Tutorial

Like you, I'm super protective of my inbox, so don't worry about getting spammed. You can expect a few emails per month (at most), and you can 1-click unsubscribe at any time. See what else you'll get too.