Install a Docker Plugin Without Losing Control of Its Permissions

You will install one Docker Engine managed plugin, decide exactly when it may start, and verify its state afterwards. This guide covers Docker CLI 29.8.1, supplied here by the docker-ce-cli package. Allow roughly 10 minutes for a known plugin and a working Docker daemon, longer if you need to investigate registry or permission problems.

Before you start

You need a Docker Engine that is reachable by your current Docker context, network access to the registry if the plugin is not already local, and the name of the plugin you intend to install. The command talks to the Docker daemon, so use an account that can access that daemon. Depending on the host configuration, that means membership of the Docker group or an elevated shell.

Choose the plugin name from its maintainer's documentation. Do not paste a name from an untrusted message, and do not grant privileges merely to make an unfamiliar plugin start. A managed plugin can request host networking, devices, mounts, or Linux capabilities. Those permissions apply to code that runs alongside the Docker daemon.

Checkpoint: confirm the client version and daemon access before changing anything:

docker --version
docker plugin ls

The first command should report Docker 29.8.1 on the system described by this guide. The second prints the installed plugins and their enabled state. If it cannot contact the daemon, fix that first; installing a plugin will not repair a stopped or inaccessible daemon.

Install with the privilege prompt

For a normal installation, replace OWNER/PLUGIN with the exact plugin reference supplied by its publisher:

docker plugin install OWNER/PLUGIN

Docker uses a plugin already present on the host when possible. Otherwise it pulls the plugin from Docker Hub or another configured registry. It then displays the requested privileges and asks you to approve them. Read each line before entering y. A successful installation enables the plugin by default, and the command prints the plugin name.

Some plugins accept configuration values at install time. Pass them after the plugin reference, using the names documented by that plugin:

docker plugin install OWNER/PLUGIN SETTING=value

Keep values free of shell metacharacters where possible. If a value contains spaces, quote the complete assignment. Do not put passwords or tokens directly into shell history. Prefer the plugin's documented secret or configuration mechanism when it provides one.

Checkpoint: immediately inspect the resulting state:

docker plugin ls

Find the installed plugin in the table and check ENABLED. A successful ordinary install should show true. If it is absent, the install did not complete. If it is present but disabled, continue with the disabled-install section below or investigate the daemon logs and the plugin's own documentation.

Install it without starting it

Use --disable when you need the plugin files installed but are not ready for it to run. This is useful for a maintenance window, a staged host, or a machine where you want to check the installed metadata first:

docker plugin install --disable OWNER/PLUGIN

The plugin remains installed and should appear in docker plugin ls with ENABLED set to false. Enabling it later is a separate state change:

docker plugin enable OWNER/PLUGIN

Check the table again after enabling. Do not enable a plugin while dependent workloads are in a sensitive operation unless you understand the effect. A volume or network plugin may affect later container operations even though installing the plugin does not itself create a volume or network.

Use an alias carefully

An alias gives a long plugin reference a local name. It does not remove the original plugin code or reduce its privileges:

docker plugin install --alias short-name OWNER/PLUGIN

Use the alias consistently in later Docker commands, and record both names in your host documentation. The alias is local to this Docker installation, so a deployment script that relies on it must create the same alias on every host.

When the privilege prompt is a problem

--grant-all-permissions skips the individual approval step and grants all permissions the plugin declares:

docker plugin install --grant-all-permissions OWNER/PLUGIN

This is an administrative shortcut, not a diagnostic fix. Use it only when you have reviewed the plugin's manifest and deliberately accept every requested permission. It is a poor first response to a prompt you do not understand. If the request is unexpected, cancel the installation and check the publisher's documentation, the exact plugin tag, and the registry source.

A plugin can still fail after its permissions are granted. Common causes include a missing host path, an unsupported device, an unavailable capability, incompatible Docker or kernel features, and plugin-specific settings. Check docker plugin ls first, then examine the Docker daemon logs and the plugin's release notes. Avoid repeatedly reinstalling the same plugin: that can obscure which configuration actually caused the failure.

Undo an installation

Removing a plugin changes Docker's available drivers and can break containers, volumes, or networks that depend on it. Before removal, stop or migrate those dependants and make sure you have any data stored outside the plugin's managed state.

For a plugin that is enabled, disable it first:

docker plugin disable OWNER/PLUGIN
docker plugin remove OWNER/PLUGIN

Docker refuses a normal disable when the plugin has references. The disable command has a force option, but forcing it can disrupt users of those references:

docker plugin disable --force OWNER/PLUGIN

Use the force option only after checking the dependency impact. Once removal succeeds, verify that the plugin no longer appears:

docker plugin ls

If you only staged the plugin with --disable, remove it directly after confirming that nothing depends on it. Reinstalling later repeats the privilege review and any plugin-specific configuration.