This error occurs when Docker fails to install a plugin due to permission issues, network problems, incompatible plugin versions, or daemon configuration issues. The solution depends on the specific underlying cause.
When you run `docker plugin install <plugin-name>`, Docker attempts to download the plugin from Docker Hub (or a private registry), extract it, configure the required capabilities, and enable it. The "error installing plugin" message indicates that one of these steps failed. Docker plugins extend the daemon's functionality by adding volume drivers, network drivers, authorization mechanisms, and other features. Unlike regular containers, plugins run in a privileged context and require explicit permission grants during installation. The actual failure reason is usually provided in additional error text following the main message. Common culprits include insufficient permissions on plugin directories, network connectivity issues preventing download, missing plugin dependencies, or incompatibility between the plugin version and your Docker Engine version.
The generic "error installing plugin" message is usually followed by more specific information. Run the install command with verbose output:
docker plugin install <plugin-name> --debugOr check the Docker daemon logs for detailed error information:
# For systemd-based systems
sudo journalctl -u docker -n 100 --no-pager
# Or check the log file directly
sudo tail -100 /var/log/docker.logThe specific error message will guide your troubleshooting.
Ensure the Docker daemon is running and responsive:
# Check daemon status
sudo systemctl status docker
# Test basic functionality
docker info
# If daemon isn't running, start it
sudo systemctl start dockerIf the daemon is in a bad state, try restarting it:
sudo systemctl restart dockerPlugin installation requires adequate disk space and proper permissions:
# Check available disk space
df -h /var/lib/docker
# Verify plugin directory permissions
ls -la /var/lib/docker/plugins
# If the directory doesn't exist, it will be created during install
# Ensure /var/lib/docker is owned by root
ls -la /var/lib/dockerIf disk space is low, clean up unused Docker resources:
docker system prune -aIf a previous installation attempt failed, corrupted data may prevent reinstallation:
# List all plugins including disabled ones
docker plugin ls -a
# Force remove the problematic plugin
docker plugin rm -f <plugin-name>
# Clear plugin state if it still appears
sudo rm -rf /var/lib/docker/plugins/<plugin-id>Then restart Docker and try installing again:
sudo systemctl restart docker
docker plugin install <plugin-name>Docker plugins often require specific capabilities. When you run docker plugin install, Docker prompts you to grant permissions. Make sure to accept them:
# Install and auto-accept capability grants
docker plugin install <plugin-name> --grant-all-permissionsIf you need to see what capabilities are required first:
# Inspect plugin configuration from Docker Hub
docker plugin inspect <plugin-name>For specific capability grants:
docker plugin install <plugin-name> \
network.host=true \
mount.source=/path/on/host mount.destination=/path/in/pluginPlugin installation requires downloading from Docker Hub or another registry:
# Test connectivity to Docker Hub
curl -I https://registry-1.docker.io/v2/
# If using a proxy, ensure Docker is configured
cat /etc/systemd/system/docker.service.d/http-proxy.confFor air-gapped environments, you may need to:
1. Download the plugin on a connected machine
2. Use docker plugin create to create it locally
3. Or set up a private registry with the plugin
Ensure the plugin is compatible with your Docker version:
# Check your Docker version
docker version
# Check plugin requirements on Docker Hub
# Visit: https://hub.docker.com/search?q=<plugin-name>&type=pluginSome plugins require specific Docker API versions. If there's a version mismatch:
1. Update Docker to a compatible version, or
2. Use an older plugin version:
docker plugin install <plugin-name>:1.0.0### SELinux and AppArmor Considerations
On systems with SELinux or AppArmor, plugin installation may be blocked by security policies:
SELinux (RHEL/CentOS/Fedora):
# Check for SELinux denials
sudo ausearch -m avc -ts recent | grep docker
# Temporarily set SELinux to permissive for testing
sudo setenforce 0
# If that fixes it, create a proper policy instead of disabling SELinuxAppArmor (Ubuntu/Debian):
# Check AppArmor status
sudo aa-status
# Review Docker's AppArmor profile
cat /etc/apparmor.d/docker### Plugin Directory Structure
Docker plugins are stored in /var/lib/docker/plugins/. Each plugin has:
- config.json: Plugin configuration and capabilities
- rootfs/: Plugin's filesystem
- blobsum: Content digest
If you need to manually inspect or clean up:
sudo ls -la /var/lib/docker/plugins/
sudo cat /var/lib/docker/plugins/<plugin-id>/config.json### Common Plugin Types and Requirements
Volume plugins (like REX-Ray, Portworx):
- May require kernel modules for storage backends
- Often need access to /dev and /sys
Network plugins (like Weave, Calico):
- Require NET_ADMIN capability
- May need kernel networking modules
Log plugins (like Splunk, Fluentd):
- Usually have fewer requirements
- May need outbound network access
### Creating Plugins Locally
If you can't pull from a registry, you can create plugins locally:
# Build plugin from a rootfs directory
docker plugin create my-plugin:latest ./plugin-dir
# Enable and use
docker plugin enable my-plugin:latest### Docker in Docker (DinD) Considerations
When running Docker inside Docker, plugin installation may fail due to:
- Nested container limitations
- Missing /var/lib/docker volume mount
- Privileged mode requirements
Ensure DinD containers run with appropriate privileges and volume mounts.
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub