⚡ NEW: Engine/extend - Full Gallery 2025

• Installing and using a plugin
• Developing a plugin
• Debugging plugins

Docker Engine's plugin system lets you install, start, stop, and remove plugins using Docker Engine.

For information about legacy (non-managed) plugins, refer to Understand legacy Docker Engine plugins.

Note

Docker Engine managed plugins are currently not supported on Windows daemons.

Installing and using a plugin

Plugins are distributed as Docker images and can be hosted on Docker Hub or on a private registry.

To install a plugin, use the docker plugin install command, which pulls the plugin from Docker Hub or your private registry, prompts you to grant permissions or capabilities if necessary, and enables the plugin.

To check the status of installed plugins, use the docker plugin ls command. Plugins that start successfully are listed as enabled in the output.

After a plugin is installed, you can use it as an option for another Docker operation, such as creating a volume.

In the following example, you install the rclone plugin, verify that it is enabled, and use it to create a volume.

Note

This example is intended for instructional purposes only.

1. Set up the pre-requisite directories. By default they must exist on the host at the following locations:

   • /var/lib/docker-plugins/rclone/config. Reserved for the rclone.conf config file and must exist even if it's empty and the config file is not present.
   • /var/lib/docker-plugins/rclone/cache. Holds the plugin state file as well as optional VFS caches.

2. Install the rclone plugin.

   The plugin requests 5 privileges:

   • It needs access to the host network.
   • Access to pre-requisite directories to mount to store:
     • Your Rclone config files
     • Temporary cache data
   • Gives access to the FUSE (Filesystem in Userspace) device. This is required because Rclone uses FUSE to mount remote storage as if it were a local filesystem.
   • It needs the CAP_SYS_ADMIN capability, which allows the plugin to run the mount command.

3. Check that the plugin is enabled in the output of docker plugin ls.

4. Create a volume using the plugin. This example mounts the /remote directory on host 1.2.3.4 into a volume named rclonevolume.

   This volume can now be mounted into containers.

5. Verify that the volume was created successfully.

6. Start a container that uses the volume rclonevolume.

7. Remove the volume rclonevolume

To disable a plugin, use the docker plugin disable command. To completely remove it, use the docker plugin remove command. For other available commands and options, see the command line reference.

Developing a plugin

The rootfs directory

The rootfs directory represents the root filesystem of the plugin. In this example, it was created from a Dockerfile:

Note

The /run/docker/plugins directory is mandatory inside of the plugin's filesystem for Docker to communicate with the plugin.

The config.json file

The config.json file describes the plugin. See the plugins config reference.

Consider the following config.json file.

This plugin is a volume driver. It requires a host network and the CAP_SYS_ADMIN capability. It depends upon the /docker-volume-sshfs entrypoint and uses the /run/docker/plugins/sshfs.sock socket to communicate with Docker Engine. This plugin has no runtime parameters.

Creating the plugin

A new plugin can be created by running docker plugin create <plugin-name> ./path/to/plugin/data where the plugin data contains a plugin configuration file config.json and a root filesystem in subdirectory rootfs.

After that the plugin <plugin-name> will show up in docker plugin ls. Plugins can be pushed to remote registries with docker plugin push <plugin-name>.

Debugging plugins

Stdout of a plugin is redirected to dockerd logs. Such entries have a plugin=<ID> suffix. Here are a few examples of commands for pluginID f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62 and their corresponding log entries in the docker daemon logs.

Using runc to obtain logfiles and shell into the plugin.

Use runc, the default docker container runtime, for debugging plugins by collecting plugin logs redirected to a file.

If the plugin has a built-in shell, then exec into the plugin can be done as follows:

Using curl to debug plugin socket issues.

To verify if the plugin API socket that the docker daemon communicates with is responsive, use curl. In this example, we will make API calls from the docker host to volume and network plugins using curl 7.47.0 to ensure that the plugin is listening on the said socket. For a well functioning plugin, these basic requests should work. Note that plugin sockets are available on the host under /var/run/docker/plugins/<pluginID>

When using curl 7.5 and above, the URL should be of the form http://hostname/APICall, where hostname is the valid hostname where the plugin is installed and APICall is the call to the plugin API.

For example, http://localhost/VolumeDriver.List