Change a Docker Plugin Setting with docker plugin set

Changing a setting with docker plugin set takes one line, and putting the old value back takes another, if you wrote it down first. This guide gets you through the change, the check and the rollback in about ten minutes, using the Docker CE CLI 29.8.1 installed here.

Plugin settings are persistent plugin configuration, not temporary options for one container. So a change sticks until you change it back.

• You need: an installed plugin and access to the Docker daemon (usually Docker group membership or sudo; use whichever access method is approved on your host).
• Book a window: if the plugin provides storage, networking or another service that running workloads use.

1. Confirm the command and Docker access

Check the installed client and the exact syntax first. These are read-only commands:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker plugin set --help
Usage:  docker plugin set PLUGIN KEY=VALUE [KEY=VALUE...]

Change settings for a plugin

There are no setting-specific flags. The first argument is the installed plugin name or ID, followed by one or more KEY=VALUE assignments. If your version or help output differs, trust your installed client over this page.

2. Find the plugin and check its state

List installed plugins and identify the one you intend to change:

$ docker plugin ls
ID             NAME                         DESCRIPTION       ENABLED
xxxxxxxxxxxx   example/vendor-plugin:1.2   Example plugin    false

IDs, names and descriptions are host-specific. Use the exact value from your output wherever this page says PLUGIN_NAME.

The plugin must be disabled first. docker plugin set will not accept a change while it is enabled. Disabling can interrupt workloads that use the plugin, so do not force it just to get past an error.

If the plugin is enabled, first establish what uses it. For a planned maintenance window, disable it normally:

$ docker plugin disable PLUGIN_NAME
PLUGIN_NAME
$ docker plugin ls --filter enabled=false

3. Inspect and record the current setting

Run docker plugin inspect before changing anything. The setting key depends on what the plugin declares. For an environment variable called DEBUG, inspect the environment list:

$ docker plugin inspect -f '{{.Settings.Env}}' PLUGIN_NAME
[DEBUG=0]

Save the exact old assignment in your change record. Here, the recovery command is docker plugin set PLUGIN_NAME DEBUG=0. Do not treat the example value as a default for your plugin.

Other supported setting types are a mount's source, a device's path and plugin arguments. Inspect the relevant field before choosing a key:

$ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount.Source}}{{end}}' PLUGIN_NAME
/srv/plugin-data
$ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' PLUGIN_NAME
/dev/example

4. Change one setting while the plugin is disabled

Change a harmless, documented value, with the old value as your rollback reference. This example changes the DEBUG environment variable:

$ docker plugin set PLUGIN_NAME DEBUG=1
PLUGIN_NAME

For a mount source, the assignment uses the mount's declared name and the source field:

$ docker plugin set PLUGIN_NAME MOUNT_NAME.source=/srv/new-plugin-data
PLUGIN_NAME

Device paths use the analogous path field:

$ docker plugin set PLUGIN_NAME DEVICE_NAME.path=/dev/new-device
PLUGIN_NAME

5. Verify before re-enabling

Inspect the same field again and compare it with what you intended:

$ docker plugin inspect -f '{{.Settings.Env}}' PLUGIN_NAME
[DEBUG=1]

Output is plugin-specific. For an argument setting the result is an array, so verify the complete array rather than looking for one substring:

$ docker plugin inspect -f '{{.Settings.Args}}' PLUGIN_NAME
[foo bar baz]

6. Re-enable and test the real operation

Once the inspection matches your change record, enable the plugin:

$ docker plugin enable PLUGIN_NAME
PLUGIN_NAME
$ docker plugin ls --filter enabled=true

Now run the smallest safe operation that exercises the plugin, such as a non-destructive health check or a test container defined by your deployment. A successful enable only shows that Docker started the plugin. It does not prove that a mount source is writable, a device is usable or an external service accepts the new configuration.

Common traps

• Changing an enabled plugin. The documented workflow requires the plugin to be disabled first. Treat the error as a safety boundary.
• Using a container environment variable. docker plugin set changes the plugin's declared settings, not an individual container's docker run -e environment.
• Guessing the key. Use the plugin's declared environment, mount, device or argument name. A supported setting type does not guarantee that every plugin declares every type.
• Forgetting quoting. Quote values containing spaces or shell metacharacters. Keep untrusted input out of the command line until it has been reviewed.
• Skipping the rollback record. Before changing a live configuration, capture the old value and the plugin name in the change ticket.