Inspect Docker Plugins Safely with JSON and Go Templates

You will use docker plugin inspect to examine an installed Docker plugin, save or filter its details, and recognise the common failure when the target is absent. The command is read-only: it does not install, enable, disable or reconfigure a plugin. Allow about ten minutes if Docker is already running and the plugin name is known.

Prerequisites and boundaries

This guide describes Docker Community Edition CLI 29.8.1, installed from the docker-ce-cli package on this machine. The local manual page is dated September 2026. Other Docker releases may format diagnostics differently, so use the exit status and the shape of the result as the reliable checks.

You need a running Docker daemon and a plugin that is already installed. Plugin inspection normally needs no sudo, but your Docker client still needs permission to talk to the daemon. If the client reports a socket permission error, ask your administrator to grant the required Docker access. Do not add yourself to the docker group casually: membership is effectively highly privileged.

Inspection itself changes no Docker state. The commands below therefore do not need a maintenance window. Treat the returned data as sensitive operational information: it can include host paths, device paths, capabilities and environment values.

1. Confirm the client and find the plugin name

Start by checking which Docker binary will run, then list the plugins known to the current daemon:

$ command -v docker
/usr/bin/docker
$ docker --version
Docker version 29.8.1, build 4a63305
$ docker plugin ls
ID        NAME                  DESCRIPTION       ENABLED
abc123    example/plugin:1.0   Example plugin    true

Your IDs, names and descriptions will differ. Copy the exact value from the NAME column, including a tag if the listing shows one. A plugin can be disabled and still be inspectable; an absent plugin cannot.

Checkpoint: set a shell variable from a name you have actually seen. Replace the placeholder before pressing Enter:

$ PLUGIN='example/plugin:1.0'
$ docker plugin ls --format '{{.Name}}'

The second command is only a quick listing check. The local docker-plugin-inspect(1) interface accepts one or more plugin arguments, so do not pass an empty variable by accident. Check it with printf '%s\n' "$PLUGIN" if the value came from a script.

2. Read the complete inspection result

Run the command with the exact plugin reference:

$ docker plugin inspect "$PLUGIN"
[
    {
        "Id": "...",
        "Name": "example/plugin:1.0"
    }
]

The real result contains considerably more detail than this abbreviated example. By default Docker renders the result as a JSON array, even when you inspect one plugin. Depending on the plugin, the object can expose its settings, mounts, devices, network mode, capabilities, environment entries and argument configuration. Read the output before acting on it; a mount source or device path may show access beyond the container filesystem.

For a durable record, redirect standard output to a new file rather than overwriting an existing report:

$ docker plugin inspect "$PLUGIN" > plugin-inspection.json
$ test -s plugin-inspection.json && echo 'inspection saved'
inspection saved

This writes only the inspection response. It does not make a backup of an old file, and shell redirection truncates an existing destination before Docker runs. Use a new filename or a temporary path if the old report matters.

3. Extract one field with a Go template

Use -f or --format when the full JSON is distracting. The documented example extracts the plugin ID:

$ docker plugin inspect --format '{{.Id}}' "$PLUGIN"
8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21

Template field names are case-sensitive and depend on the inspection object. Start with a field shown in the full response, then test it against the same plugin. A blank line is not proof that the plugin is broken: it may mean that the selected field is absent or named differently.

Use the short form when you prefer:

$ docker plugin inspect -f '{{.Name}}' "$PLUGIN"
example/plugin:1.0

Keep the single quotes around a template containing braces. They prevent the shell from interpreting characters before Docker receives them. If you need several values, print labels in the template so a later reader can tell which value is which:

$ docker plugin inspect -f 'name={{.Name}} id={{.Id}}' "$PLUGIN"
name=example/plugin:1.0 id=8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21

Use the official Docker formatting reference for Go template syntax beyond simple fields. Do not paste untrusted plugin data into a shell command: an extracted value is data, not a safe command line.

4. Inspect several plugins together

The command accepts multiple plugin arguments. This is useful for comparing related plugins without changing either one:

$ docker plugin inspect \
    'example/plugin:1.0' \
    'example/backup:2.1' \
    > selected-plugins.json
$ test -s selected-plugins.json && echo 'inspection saved'
inspection saved

The default response is an array with one object per successful target. Keep plugin references quoted when they come from variables or external input. A missing target causes the command to fail, so do not treat a partially useful file as a complete comparison without checking the exit status.

5. Diagnose a failed inspection

Test failures with a deliberately nonexistent name only when you want to confirm the error path:

$ docker plugin inspect definitely-not-installed
Error response from daemon: plugin "definitely-not-installed" not found
$ printf 'exit status: %s\n' "$?"
exit status: 1

The exact wording can vary. The useful signals are a daemon error and a non-zero status. First rerun docker plugin ls and copy the name exactly. Do not run docker plugin install merely because inspection failed: installation pulls code and can request network, device or capability privileges. That is a separate, security-sensitive change.

If every Docker command fails, distinguish a missing plugin from a client-daemon problem. Check docker version and the current context with docker context show. A context can point at a different daemon from the one you expected. Fix the context or daemon access with your normal administrative process, then repeat the read-only inspection.