How to search Docker Images using CLI?

    The Docker official registry called Dockerhub contains a plethora of official as well as vendor-specific Docker images. You can leverage these images to run them as a container directly or use these images as base images in your Dockerfile to create your own customized Docker images. Moreover, you can even create your own repositories inside Dockerhub and make them either private or public based on your preferences and push your own images there using the Docker push command. To do so, you need to have an account on Dockerhub and you need to be logged in through your localhost machine’s command line. These images are pushed or pulled from the link “”. This is where all the repositories are found. Certain Docker images such as Ubuntu, CentOS, MySQL, Nginx, Java, Python, etc. are some examples of official Docker images that you can directly use to work inside containers associated with them or you can use them as base images. For each image repository, there are several versions of the image that you can find each with a different tag. For example, for the Fedora repository, you can find tons of images with tags 21, 22, 23, latest, etc. And the same is for all other repositories. Hence, it’s very difficult to find which Docker image you want to use and where to get it from. However, Docker makes this very simple for you. You can directly use the Command-line to search for Docker images based on the different filters that you provide. You can do so with the help of the Docker search command.

    Docker Search Command

    The general syntax of the Docker Search command is -

    $ docker search [OPTIONS] TERM

    You can use several options along with the Docker search command to filter your results. Let’s see what are the available options that we have.

    Name or Shorthand Notation Default Values Description of the Options
    --filter , -f You can provide certain filters to filter the output.
    --format You can format your output using Go language placeholders
    --limit 25 You can limit the number of results in the output.
    --no-trunc Specify this if you don’t want to truncate the output.

    Now, let’s take a look at some of the examples where we will use the Docker search command along with multiple options that we have discussed above.

    1. Search Docker images by their names

    Let’s try to search all the images whose names match with “fedora”. $ Docker Image fedora

    You can see that it has returned the list of all the images that are available in the Dockerhub official registry and either their names are fedora or a part of their names have fedora as a sub-string. Please take a look at the parameters that it has returned. It returns the names of the images along with the repositories that they belong to. It has also returned the description of these images. Moreover, it has also returned the number of stars that their users have provided them which helps us to determine which is the most popular one. Finally, it also returns and checks if the Docker images are official or not. This means whether the images are maintained by the official Docker community or not. Finally, we have another parameter called automated which tells whether the build process will be automated or not.

    2. Using the --no-trunc option

    If you carefully notice above, you will find that the descriptions of all the images are truncated meaning that they are not complete. This has been done so that the output does not look clumsy and messy. To display the complete description, we can use the --no-trunc option to avoid truncating the output.

    $ docker search --no-trunc fedora

    $ docker search --no-trunc fedora

    You can see that this time, it has not truncated the description and the output looks somewhat clumsy.

    3. Limiting the number of results

    We can define the number of results that we want to output. Let’s try to print only the top 5 results of the fedora image search result.

    $ docker search --limit=5 fedora

    $ docker search --limit=5 fedora

    You can see that it has only returned the top 5 results.

    4. Formatting the output

    We can use the Go-template along with certain placeholders that it provides to display only particular columns and format them. This will help us to pretty-print the output. Here are a few placeholders that we can use for the Docker search command.

    Placeholder Description
    .Name Name of the Image
    .Description Description of the Images
    .StarCount Count of stars
    .IsOfficial “OK” for official images
    .IsAutomated “OK” for automated images

    When we use this option (--format), it will output exactly the same way as we declare in the template. Let’s try to print the name of the images along with the star counts in the described format.

    $ docker search --limit=10 --format “The {{.Name}} image has {{.StarCount}} number of stars” fedora

    $ docker search --limit=10 --format “The {{.Name}} image has {{.StarCount}} number of stars” fedora

    If we want to print the output in a table format, we can use the table directive.

    $ docker search --limit=10 --format “table {{.Name}}\t{{.IsOfficial}}” fedora

    $ docker search --limit=10 --format “table {{.Name}}\t{{.IsOfficial}}” fedora

    Here, we can see that the output is in a table format along with the headers of each field.

    5. Filtering the Output

    We can use the --filter or -f option to filter the output based on a set of key-value pairs that we provide. To pass more than one filter, we need to pass multiple filter flags. Right now, the search command supports these filters - start (integer), is-official (boolean), is-automated (boolean). Let’s try to filter all the fedora images that have at least 3 stars and are automated.

    $ docker search --filter stars=3 --filter is-automated=true fedora

    $ docker search --filter stars=3 --filter is-automated=true fedora

    You can see that the desired output has been displayed successfully.

    Wrapping Up!

    To sum up, in this comprehensive guide, we discussed how we can leverage the Docker search command to search for Docker images in the Docker official registry called Dockerhub. We discussed the general syntax of the Docker search command and the several options that we can include to modify our search results. We discussed each of these options including filter, format, no trunc, and limit with the help of detailed examples along with command executions. We hope that with the help of this tutorial on Docker search, you will now be able to get hands-on with it and search for Docker images seamlessly straight through your command-line.

    People are also reading: