Recommended Free Tools
The message docker: 'compose' is not a docker command means the Docker CLI cannot find its Compose V2 plugin. Docker Engine may be installed and running, but the separate component that adds the docker compose subcommand is missing or stored somewhere the CLI does not search.
Antihost offers VPS plans with one-click Docker, NVMe storage and a 14-day free trial.
On Debian or Ubuntu, the normal fix is to configure Docker’s official APT repository for your Linux release and install docker-compose-plugin. On Fedora, RHEL, or CentOS, install the same package through Docker’s repository with DNF or YUM. If packages are unavailable, install the Compose V2 binary in a Docker CLI-plugin directory, make it executable, and then verify with docker compose version.
As an Amazon Associate I earn from qualifying purchases.
What the error means
Docker Compose V2 is delivered as a command-line plugin rather than as a built-in Docker Engine subcommand. The Docker client looks for an executable named docker-compose in its CLI-plugin directories. When it cannot find a usable plugin, it parses compose as a requested subcommand and returns:
docker: 'compose' is not a docker commandThis is a client-side discovery problem. Installing or restarting the Docker daemon alone does not register the missing command. A convenience-script installation can leave Docker Engine present while Compose is absent; a report in the Docker Compose issue tracker describes that exact outcome.
#1 Best Overall
The space and hyphen forms are different commands:
| Command | What it is | What the error usually indicates |
|---|---|---|
docker compose |
Compose V2, implemented as a Docker CLI plugin | The V2 plugin is not installed, not executable, or outside the CLI search path |
docker-compose |
The older standalone, hyphenated Compose V1 executable | It may be installed independently, but it does not add the V2 subcommand |
Do not assume that a working docker-compose command proves that docker compose is available. They can coexist, and scripts may call either spelling.
Check the installation before changing it
Run these commands as the same Linux user that receives the error:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
docker --version
command -v docker
docker compose versionThe first two commands identify the Docker client being executed. The third is the definitive check: a successful installation prints a Compose V2 version beginning with v2. If the third command reproduces the error, continue with the package-manager or manual installation below.
If multiple Docker installations exist, the client in your shell may not be the one you expected. For example, a distribution package and a separately installed Docker binary can use different plugin locations. Record the path returned by command -v docker before troubleshooting so you can test the same client after every change.
Install Compose V2 on Debian or Ubuntu
For Debian-family systems, the supported package name is docker-compose-plugin. The package is provided through Docker’s official APT repository. The repository must match your distribution release; an entry for a different codename can make APT report that no installation candidate exists.
1. Confirm the Docker repository
Check the repository configuration used by your system and confirm that Docker’s official repository is enabled for the exact Debian or Ubuntu release you are running. If Docker was installed only from a distribution’s default repositories or by a convenience script, the official repository may not be present. If the repository is configured for the wrong codename or architecture, correct that configuration before installing the plugin.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Do not copy a repository line written for another release without checking its codename. A mismatched entry is a common reason for the “unable to locate package” variant of this problem.
2. Refresh package metadata
sudo apt-get updateRead the output rather than ignoring warnings. Repository signature, DNS, TLS, or release-file errors mean APT did not obtain usable metadata; installing immediately afterward is likely to produce a misleading “package not found” result.
3. Install the plugin
sudo apt-get install docker-compose-pluginAccept the package installation only after APT identifies the package from the intended Docker repository. The plugin is installed separately from the Engine package, so an existing docker-ce or distribution Docker package does not guarantee that Compose is present.
4. Verify in a new shell if necessary
docker compose versionA successful result displays a Compose V2 release. If your shell has cached an old command location, open a new shell and run the verification again. If the error remains, use the troubleshooting branches below instead of repeatedly reinstalling the same package.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Install Compose V2 on Fedora, RHEL, or CentOS
On RPM-based systems, enable Docker’s repository for your distribution and release, then install the package with the native package manager:
sudo dnf install docker-compose-pluginOn systems that still use YUM, the equivalent command is:
sudo yum install docker-compose-pluginThe repository requirement matters here as it does on Debian and Ubuntu. If DNF or YUM cannot find docker-compose-plugin, verify that Docker’s repository is enabled and targets the release you are actually running. Repository setup details vary by RPM-family distribution, so do not substitute a repository definition intended for another product or release.
After installation, run:
docker compose versionThe command should print a V2 version. If it does not, confirm that the shell is invoking the expected Docker client and proceed to the plugin-path checks.
Manual installation when packages are unavailable
A manual install is a fallback for systems that cannot use the package repositories. You need a Compose V2 binary from a trusted Docker release source, the correct CPU architecture, and permission to write to one of the Docker CLI-plugin directories. This method does not provide package-manager lifecycle handling, so you must plan upgrades yourself.
Choose a plugin directory
| Scope | Directory | Effect |
|---|---|---|
| One user | ~/.docker/cli-plugins/docker-compose |
Available to that user without administrator privileges |
| All users | /usr/local/lib/docker/cli-plugins/docker-compose |
Available system-wide when the Docker client searches that location |
The filename is significant: the executable must be named docker-compose inside the cli-plugins directory. Placing a file named only compose, or placing it in an arbitrary bin directory, does not register the docker compose subcommand.
Install for one user
- Create the directory if it does not exist:
mkdir -p ~/.docker/cli-plugins - Copy or download the Compose V2 binary into that directory with the exact filename
docker-compose. - Make it executable:
chmod +x ~/.docker/cli-plugins/docker-compose - Verify discovery:
docker compose version
This option avoids changing files for other users, but each user who needs Compose must have a plugin in their own directory.
Install system-wide
- Create the system plugin directory:
sudo mkdir -p /usr/local/lib/docker/cli-plugins- Copy the binary to
/usr/local/lib/docker/cli-plugins/docker-composeusing administrator privileges. - Set its executable bit:
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose- Run the check as a normal user:
docker compose versionKeep a record of the binary version and repeat the replacement process when a newer Compose V2 release is required. Unlike a package-manager installation, this path does not automatically supply upgrades or removal metadata.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Why installation can appear successful but the command still fails
The package cannot be found
On APT, DNF, or YUM, “package not found” usually means the Docker repository is missing, disabled, or configured for the wrong release codename. Run the repository check first, then refresh metadata with the package manager’s update command. Installing an unrelated package named “compose” will not solve this specific plugin error.
The package is installed, but Docker cannot see it
Check that the plugin file exists in a CLI-plugin directory and that it has execute permission. For a manual installation, the expected filenames are:
Best Value
~/.docker/cli-plugins/docker-compose
/usr/local/lib/docker/cli-plugins/docker-composeA missing execute bit is enough to make discovery fail. Reapply chmod +x, then run docker compose version again. Also compare the Docker path from command -v docker with the installation you modified; a second Docker client can search a different set of locations.
A script still reports the old error
Inspect the script’s command spelling. A script that invokes docker compose needs Compose V2 discoverable by the Docker CLI. A script that invokes docker-compose is calling the standalone hyphenated executable instead. Update the script only after deciding which interface its syntax expects; V1 and V2 are not interchangeable merely because both are called Compose.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsA convenience-script install left Compose out
Installing Docker with a convenience script can produce a working Engine without registering every optional CLI plugin. Treat the missing plugin as a separate installation task: configure the official repository when possible and install docker-compose-plugin, or use the manual plugin path when package installation is not an option.
You changed daemon settings
Older advice sometimes suggests adding "experimental": true to /etc/docker/daemon.json. That setting is not the remedy for a missing Compose subcommand. The error is emitted by the Docker CLI before Compose can run; adding an unrelated daemon flag does not install or expose the plugin.
You followed a macOS workaround
Homebrew-based instructions target macOS and do not configure the Linux Docker CLI-plugin directories described here. On Linux, use the distribution package through Docker’s repository or place the binary in a Linux CLI-plugin directory.
Package manager or manual binary: which fix should you choose?
| Criterion | Package-manager installation | Manual binary installation |
|---|---|---|
| Recommended use | Normal Debian, Ubuntu, Fedora, RHEL, or CentOS hosts with Docker’s repository available | Hosts where package repositories cannot be used |
| Install command | sudo apt-get install docker-compose-plugin, sudo dnf install docker-compose-plugin, or sudo yum install docker-compose-plugin |
Copy the binary to a CLI-plugin directory and run chmod +x |
| Upgrade handling | Managed with the package manager and repository updates | Manual replacement and version tracking required |
| Scope choices | Determined by package installation and system policy | Per-user ~/.docker/cli-plugins or system-wide /usr/local/lib/docker/cli-plugins/ |
| Main failure mode | Repository or release-codename mismatch | Wrong path, wrong filename, wrong architecture, or missing execute permission |
For a maintained workstation or server, the package route is usually the least operational work because updates follow the host’s package-management process. Use the manual route when repository access is genuinely unavailable, and include its upgrade procedure in your system documentation.
Final verification checklist
docker --versionidentifies the Docker client you intend to use.- The Docker repository is enabled for the host’s actual Linux release when using APT, DNF, or YUM.
- The package named
docker-compose-pluginis installed, or the manual binary is in a supported CLI-plugin directory. - The manual binary is named
docker-composeand has execute permission. docker compose versionprints a Compose V2 version rather than the “not a docker command” message.- Automation uses the command spelling it was written for:
docker composefor V2 ordocker-composefor the standalone executable.
What success looks like
The fix is complete when the same user and shell that originally failed can run docker compose version and receive a V2 release string. You do not need to enable an experimental daemon flag, reinstall the entire Docker Engine, or use a macOS package manager. The essential change is making the Compose V2 CLI plugin available and executable where the Linux Docker client looks for plugins.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
