Jul 17, 2021 9 min read

How to Use Docker Inspect Command

Docker inspect command allows you to get information about Docker containers, volumes and networks. Learn to use this command.

One of the essential Docker commands is docker inspect. It lets you extract information about various docker objects, knowing how to use it is something EVERYONE should know about.

In case you were wondering, Docker objects or resources are simply things like containers, volumes, networks etc.

The main strength of inspect comes from its formatting capabilities.

For example, you can extract the IP address of a running container by inspecting it, and formatting in a specific way.

➟ docker container inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' nginx
172.17.0.2

Docker uses go-templates for formatting its output.

In this article, first I'll go through the basics of Docker inspect command, and then I'll focus on how to format the output to your specific needs.

What does Docker inspect do?

Inspect provides you with a bunch of metadata about all the different objects managed by docker. The kind of information varies from object to object.

For example, if you inspect a volume, you'll get information related to when it was created, the volume driver in use, location in the host filesystem, labels etc.

If it is a network that you're inspecting, then you'll get things like its subnet, gateway, connected containers and their IP addresses, labels and other information.

To understand better what inspect provides for a given object, I recommend you run the commands and see for yourself.

What are the objects that can be inspected?

In docker, an object or object type is all the constructs that are controlled by docker. This includes the following:-

  1. Containers.
  2. Images.
  3. Networks.
  4. Volumes.
  5. Contexts.
  6. Plugins.
  7. Nodes (swarm object).
  8. Services (swarm object).
  9. Secrets (swarm object).
  10. Configs (swarm object).

Using Docker inspect command

There are two ways you can use the inspect sub-command.

  1. docker inspect [object] [options]
  2. docker [object_type] inspect [object] [options]

The second method is the one you should be using always. The inspect sub-command provides a JSON output, I'll get into that in a moment.

Create a volume named unique.

docker volume create unique

Now create a network named the same, unique.

docker network create unique

Now let's try to inspect the object named unique using the first syntax.

docker inspect unique

My output:-

➟ docker inspect unique
[
    {
        "Name": "unique",
        "Id": "09a7e2163ee058b1057d95599f764d571ec6a42a5792803dc125e706caa525b0",
        "Created": "2021-05-07T15:47:20.341493099+05:30",
        "Scope": "local",
        "Driver": "bridge",
        "EnableIPv6": false,
        "IPAM": {
            "Driver": "default",
            "Options": {},
            "Config": [
                {
                    "Subnet": "172.21.0.0/16",
                    "Gateway": "172.21.0.1"
                }
            ]
        },
        "Internal": false,
        "Attachable": false,
        "Ingress": false,
        "ConfigFrom": {
            "Network": ""
        },
        "ConfigOnly": false,
        "Containers": {},
        "Options": {},
        "Labels": {}
    }
]

In my system, as you can see inspect inspected the network, but what if I intended to inspect the volume?

This is the problem with docker inspect, when you have two different objects named the same, you can't just use docker inspect [object_name]. To inspect exactly what you want, you'll need to either use the ID of the object, or use the --type=[object_type] option. You can write the previous command with the --type option like so:-

docker inspect --type=volume unique

Although this works, I believe this is unnecessary since we already have the other syntax. You can just use the object specific sub-command like I'm doing here:-

docker volume inspect unique

It is less to write, and a lot easier to read.

Some useful Docker inspect command examples

In this section, I'm going to record a list of common queries and what the relevant inspect command would look like to get those information.

Container queries

For the examples, I'll have a sample nginx container running, and all the commands will be run against this running container. The command I used to run this container:-

docker container run \
	--rm --name nginx \
    -p target=80,published=127.0.0.1:8081,protocol=tcp \
    -p target=80,published=[::1]:8081,protocol=tcp \
    -e ENV_VAR=somevalue \
    -e ENV_VAR2=linux \
    -v $PWD:/mnt:ro \
    -v /tmp:/tmp:ro \
    -d nginx

1. ID of a container by name

You can get the ID of the container using the following command:-

docker container inspect -f '{{.Id}}' [container_name]

Example:-

➟ docker container inspect -f '{{.Id}}' nginx
0409779fc2d976387170d664a6aed5ee80a460f8a8dd02c44a02af97df0bb956

2. Container's main process

The main container process is basically ENTRYPOINT + CMD.

docker container inspect -f '{{printf "%s " .Path}}{{range .Args}}{{printf "%s " .}}{{end}}' [container_name|id]

Example:-

➟ docker container inspect -f '{{printf "%s " .Path}}{{range .Args}}{{printf "%s " .}}{{end}}' nginx
/docker-entrypoint.sh nginx -g daemon off;

3. Listing the port bindings

The following command lists all the container-to-host port bindings.

docker container inspect -f '{{range $target, $published := .NetworkSettings.Ports}}{{range $published}}{{printf "%s -> %s:%s\n" $target .HostIp .HostPort}}{{end}}{{end}}' [container_name|id]

Example:-

➟ docker container inspect -f '{{range $target, $published := .NetworkSettings.Ports}}{{range $published}}{{printf "%s -> %s:%s\n" $target .HostIp .HostPort}}{{end}}{{end}}' nginx
80/tcp -> ::1:8081
80/tcp -> 127.0.0.1:8081
You can achieve the same with docker container port command.

4. Listing its IP addresses

A container can be connected to multiple networks, instead of printing one of those many IP addresses, you can print all of those IP addresses with this command.

docker container inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' [container_name|id]

Example:-

➟ docker container inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' nginx
172.17.0.2

5. Listing the environment variables

You can list the environment variable of a container as well.

docker container inspect -f '{{range .Config.Env}}{{printf "%s\n" .}}{{end}}' [container_name|id]

Example:-

➟ docker container inspect -f '{{range .Config.Env}}{{printf "%s\n" .}}{{end}}' nginx
ENV_VAR=somevalue
ENV_VAR2=linux
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
NGINX_VERSION=1.19.10
NJS_VERSION=0.5.3
PKG_RELEASE=1~buster

6. Listing the volumes/bind mounts along with the mode

The following command prints the bind mounts in this format, "[source] -> [destination], mode: [mode]".

docker container inspect -f '{{range .Mounts}}{{printf "%s -> %s, mode: %s\n" .Source .Destination .Mode}}{{end}}' [container_name|id]

Example:-

➟ docker container inspect -f '{{range .Mounts}}{{printf "%s -> %s, mode: %s\n" .Source .Destination .Mode}}{{end}}' nginx
/home/debdut -> /mnt, mode: ro
/tmp -> /tmp, mode: ro

Volume queries

There's not much to inspecting a volume except for knowing the host location, which is in data-dir/volumes. You can get that information with the following command:-

docker volume inspect -f '{{.Mountpoint}}' [volume_name|id]

Example:-

➟ docker volume create unique 
unique
~ 
➟ docker volume inspect -f '{{.Mountpoint}}' unique 
/var/lib/docker/volumes/unique/_data

Network queries

There are two queries that I personally find myself going for frequently, one is knowing a networks subnet and all the containers that are connected to that network and the IPs associated with them.

For this I created a simple network with the docker network create unique command.

1. Getting the subnet

To get the subnet, use the following command:-

docker network inspect -f '{{range .IPAM.Config}}{{.Subnet}}{{end}}' [network_name|id]

Example:-

➟ docker network inspect -f '{{range .IPAM.Config}}{{.Subnet}}{{end}}' unique 
172.21.0.0/16

2. Listing the containers connected along with their IP addresses

The command looks like this,

docker network inspect -f '{{range .Containers}}{{printf "%s -> %s\n" .Name .IPv4Address}}{{end}}' [network_name|id]

Example:-

➟ docker network inspect -f '{{range .Containers}}{{printf "%s -> %s\n" .Name .IPv4Address}}{{end}}' unique 
cranky_wescoff -> 172.21.0.5/16
nginx -> 172.21.0.2/16
upbeat_carson -> 172.21.0.3/16
objective_jones -> 172.21.0.4/16

Formatting the output of Docker inspect command

inspect provides us with a JSON array for the output, which you can filter using something like jq. So if you're experienced in jq, you might want to just use it. The problem with jq is that it doesn't come preinstalled in most of the Linux distributions, while the default formatting mechanism of docker .. inspect is already there, and it is very powerful.

Docker uses go-templates to format its output. This article is not going to be about go-templates, but if you want to learn more, you can read about it here.

Internally JSONs are represented using various Go data structures. That's why go templates actually work with go data types. Since I don't want to explain what these data structures are, instead of using those terms, I'll use JSON terms to make it more understandable.

Read the full story

The rest of the article is available to LHB members only. You can sign up now for FREE to read the rest of this article along with access to all members-only posts. You also get subscribed to our fortnightly Linux newsletter.

Subscribe
Already have an account? Sign in
Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Linux Handbook.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.