Change a Docker Plugin Setting Without Losing the Old Value

You will finish with a controlled way to change a Docker managed plugin setting, verify the new value, and put the old value back if the plugin does not behave as expected. The examples use the Docker CE CLI 29.8.1 installed here. Docker plugin settings are persistent plugin configuration, not temporary options for one container.

Allow about ten minutes for a simple environment-variable change. You need an installed plugin, access to the Docker daemon, and a maintenance window if the plugin provides storage, networking or another service used by running workloads. The command usually needs either membership of the host's Docker group or elevated access such as sudo; use the access method already approved on your host.

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

The command has no setting-specific flags. Its first argument is the installed plugin name or ID, followed by one or more KEY=VALUE assignments. If the version or help output differs, use the syntax shown by your installed client rather than copying this page blindly.

Checkpoint: if the version command reports a daemon or permission error, fix that before touching plugin state. Adding sudo may solve a local permission problem, but it will not make a missing plugin or an invalid setting valid.

2. Find the exact 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

The IDs, names and descriptions are host-specific. Use the exact value from your output in place of PLUGIN_NAME. The plugin must be disabled before docker plugin set will accept a change. Disabling can interrupt workloads that use the plugin, so do not force it merely 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

If Docker refuses because the plugin has references, stop and assess those references. The -f or --force option exists for disabling an active plugin, but forcing a service-disrupting change is a separate operational decision and is not part of this routine.

3. Inspect and record the current setting

Use docker plugin inspect before changing anything. The setting key depends on the plugin's declared configuration. 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 somewhere appropriate for the change record. In this example, 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 selecting a key. For example:

$ 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

A blank or failed template lookup is a reason to inspect the full object and the plugin documentation, not a reason to invent a key. Configuration names are declared by each plugin.

4. Change one setting while the plugin is disabled

Change a harmless, documented value using 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

Only use names and values supplied by the plugin documentation or your deployment configuration. A filesystem path must exist and have suitable permissions when the plugin needs it. A device path can expose sensitive host hardware. These changes are security-sensitive even though the syntax is short.

5. Verify before re-enabling

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

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

The exact 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]

If the value is wrong, set it back to the recorded old value while the plugin is still disabled. Do not enable a plugin simply to test a value that has not been confirmed.

6. Re-enable and test the real operation

Once the inspection matches the 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.

If the test fails, disable the plugin, restore the recorded value with docker plugin set, inspect the restored value, and enable it again only when the rollback has been verified. If workloads are affected, follow the host's incident or maintenance procedure rather than repeatedly toggling the plugin.

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. The 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.