Home / Alt manpages / docker-plugin-disable(1)

  • docker-plugin-disable(1)
  • User command
  • linux

Turn Off a Docker Plugin with docker plugin disable

docker plugin disable stops an installed plugin without removing it, handy when the thing starts misbehaving and you need it out of the way fast. Allow about five minutes for the checks. You need Docker CLI access to a running daemon and the name or ID of an installed plugin.

The route

Jump straight to the step you need, or tick off Done means at the end.

Before you start

Disabling a plugin changes the Docker host, so treat it as service-affecting. A volume, network, logging, authorisation or other integration may depend on it. On a shared host, identify the affected containers and arrange a maintenance window before continuing.

The installed command is Docker Community Edition CLI 29.8.1 on this system. Its syntax is:

docker plugin disable [OPTIONS] PLUGIN

The command needs access to the Docker daemon, whether through membership of the docker group, a suitable DOCKER_HOST connection, or elevated privileges depending on the host setup. It does not automatically require sudo; do not add it unless your daemon access requires it.

1. List installed plugins

Start with a read-only inventory. The ENABLED column shows whether a plugin is active, and the NAME column gives the reference to pass to the disable command.

docker plugin ls

A host with no installed plugins produces a header similar to this:

ID        NAME      DESCRIPTION   ENABLED

With a plugin installed, record its complete name, including a tag if Docker shows one. You can usually use its name or ID, but copying the value from this listing avoids a typo.

Checkpoint

Stop here if the target is absent, already disabled, or belongs to a service you cannot interrupt. An absent plugin is not a failed disable; it just means nothing is installed locally under that reference.

2. Check what uses the plugin

Inspect the containers and service definitions that might use the plugin before you change its state. For a quick view of running containers:

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

Then inspect the plugin itself for its declared settings and capabilities:

docker plugin inspect <PLUGIN_REFERENCE>

Replace <PLUGIN_REFERENCE> with the name from step 1, for example vendor/example-plugin:latest. Look for the capability and settings that explain why the plugin was installed in the first place. A volume plugin can be tied to mounts, while a network or logging plugin can sit on a running container's path.

Tip

Docker normally refuses to disable a plugin that still has references, such as volumes or networks. That refusal is a safety boundary. Resolve the references first, and only use the force option once you understand the impact.

3. Disable the plugin normally

Run the command without force first:

docker plugin disable <PLUGIN_REFERENCE>

On success, Docker prints the plugin reference, for example:

vendor/example-plugin

This stops the plugin and marks it inactive. It does not uninstall or remove it, and its configuration stays available for a later enable.

Warning

If Docker reports that the plugin has active references, do not immediately retry with --force. Find the containers, volumes, networks or services using it, then stop or reconfigure those consumers through your normal deployment process. Stopping a consumer can itself interrupt service, so record the change and its rollback before applying it.

4. Verify the disabled state

Ask Docker for the plugin list again and check the target now shows false under ENABLED:

docker plugin ls --filter enabled=false

To make the check unambiguous for one plugin, format the listing as a small, machine-readable line:

docker plugin ls --format '{{.Name}} enabled={{.Enabled}}'

Expected output for the target is similar to:

vendor/example-plugin:latest enabled=false

Checkpoint

Also check the workload that motivated the change. A disabled plugin may leave existing Docker objects in place while making new mounts, networks or other operations fail. A clean CLI result is not proof every consumer is healthy.

When force is appropriate

The only option in the installed command is -f, also written --force. It forces the disable of an active plugin:

docker plugin disable --force <PLUGIN_REFERENCE>

Warning

This is a disruption switch, not a way to fix a misspelled reference or skip investigation. Use it only once the references are understood, the service impact is acceptable, and you have a recovery path. Existing containers or resources may stop working the moment their plugin is unavailable.

Restore the plugin

If the disabled plugin is needed again, enable the existing installation:

docker plugin enable <PLUGIN_REFERENCE>

Docker prints the plugin reference on success. Verify the state:

docker plugin ls --format '{{.Name}} enabled={{.Enabled}}'

Recovery

Look for enabled=true, then test the dependent workload. If enabling fails, inspect the daemon error, confirm the plugin is still installed, and check whether its host paths, devices or permissions are available. Re-enabling does not recreate a plugin that has already been removed.

Done means

  • Right plugin identified. The intended plugin was found from docker plugin ls.
  • Consumers checked. Its dependants and service impact were reviewed before the change.
  • Disabled cleanly. docker plugin disable completed without force, unless a forced change was deliberately approved.
  • State confirmed. The plugin reports enabled=false and the affected workload was tested.
  • Rollback recorded. The enable command and rollback decision are written down for the host.