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

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

Install a Docker Plugin with docker plugin install

docker plugin install pulls a managed plugin, shows you exactly what it wants to access, and asks before it gets any of it. 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 daemon, longer if you need to investigate registry or permission problems.

The route

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

Before you start

  • A reachable Docker Engine via your current Docker context.
  • Network access to the registry if the plugin is not already local.
  • The exact plugin name from its maintainer's documentation, not pasted from an untrusted message.

The command talks to the Docker daemon, so use an account that can reach it: depending on the host, that means membership of the Docker group or an elevated shell. Do not grant privileges just to make an unfamiliar plugin start. A managed plugin can request host networking, devices, mounts, or Linux capabilities, and those permissions apply to code running 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.

1. Install with the privilege prompt

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

docker plugin install OWNER/PLUGIN

Docker uses a plugin already present on the host when it can, otherwise pulling it from Docker Hub or another configured registry. It then displays the requested privileges and asks you to approve them. Read every 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 that plugin documents:

docker plugin install OWNER/PLUGIN SETTING=value

Warning

Keep values free of shell metacharacters where possible, and quote the complete assignment if a value contains spaces. Do not put passwords or tokens directly into shell history; prefer the plugin's documented secret or configuration mechanism when it has 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 disabled installs below, or check the daemon logs and the plugin's own documentation.

2. Install it without starting it

Use --disable when you need the plugin files in place but are not ready for it to run, useful for a maintenance window, a staged host, or checking the installed metadata first:

docker plugin install --disable OWNER/PLUGIN

The plugin stays 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 mid-operation unless you understand the effect: a volume or network plugin can affect later container operations even though installing it does not itself create a volume or network.

3. 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 relying on it must create the same alias on every host.

4. When the privilege prompt is a problem

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

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

Warning

This is an administrative shortcut, not a diagnostic fix. Use it only after 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 tag, and the registry source instead.

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 daemon logs and the plugin's release notes. Avoid repeatedly reinstalling the same plugin, which can obscure which setting actually caused the failure.

5. Undo an installation

Removing a plugin changes Docker's available drivers and can break containers, volumes, or networks that depend on it. Stop or migrate those dependants first, and make sure any data stored outside the plugin's managed state is safe.

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 those references' users:

docker plugin disable --force OWNER/PLUGIN

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

docker plugin ls

Recovery

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

Done means

  • Trusted reference used. You used the exact plugin reference from a trusted publisher.
  • Permissions reviewed, not rubber-stamped. You read and accepted only the permissions you intended to grant.
  • State confirmed. docker plugin ls shows the expected plugin and enabled state.
  • Configuration recorded. Any alias or KEY=VALUE settings are written down for repeatable host setup.
  • Rollback understood. You know how to disable and remove the plugin without silently disrupting its dependants.