The message docker: 'compose' is not a docker command means the Docker CLI cannot find its Compose V2 plugin. On Linux, install the docker-compose-plugin package from Docker’s repository, then confirm it with docker compose version. The command with a space (docker compose) and the older hyphenated command (docker-compose) are separate tools.
Antihost offers VPS plans with one-click Docker, NVMe storage and a 14-day free trial.
What the error means
Docker Compose V2 is not a daemon setting or a shell alias. It is a plugin that extends the Docker CLI. When you type docker compose, the first word starts the Docker client and the second word names a subcommand supplied by that plugin. If the plugin is absent, or is installed somewhere the CLI does not search, Docker treats compose as an unknown command and prints:
As an Amazon Associate I earn from qualifying purchases.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstalldocker: 'compose' is not a docker commandThis usually occurs when Docker Engine was installed without the Compose package, when Docker’s package repository is missing or configured for the wrong Linux release, or when a manually installed plugin is in the wrong directory. It is a client-side discovery problem: adding an option to the Docker daemon will not register the command.
Check the exact command and current installation
Before changing packages, check which Docker executable is being used and whether a Compose binary is already present:
#1 Best Overall
docker --version
docker compose version
docker-compose --versiondocker --versionconfirms that the Docker CLI itself is available.- If
docker compose versionrepeats the unknown-command error, the V2 plugin is not being discovered. docker-compose --versionchecks for the older standalone, hyphenated program. Its presence does not makedocker composework.
Do not “fix” this by changing a script from one spelling to the other without checking what the script expects. docker compose and docker-compose are different command interfaces. A project can continue to call the hyphenated executable even after the V2 plugin is installed, while a newer project or instruction can require the space-separated form.
Preferred fix on Debian and Ubuntu
For Debian- and Ubuntu-family systems, the normal solution is to install Docker’s Compose plugin package through Docker’s official APT repository. The repository must be configured for the release you are actually running. If APT cannot locate the package, repository setup or the distribution codename is the first thing to correct; repeatedly running the install command will not solve a repository mismatch.
1. Confirm Docker’s APT repository
Check that Docker’s official repository is enabled and targets your installed Debian or Ubuntu release. A repository entry for a different codename can leave Docker packages unavailable even though the rest of the system updates normally. If you installed Docker using a convenience script or a distribution package, verify which repository supplied the current CLI before adding another source.
2. Refresh package metadata
sudo apt-get updateRead the output rather than ignoring warnings. Errors about an unavailable release, an unreachable repository, or a missing signing key need to be resolved before package installation. A successful update does not by itself prove that the Docker repository is configured correctly; it only means APT refreshed the sources it knows about.
3. Install the plugin
sudo apt-get install docker-compose-pluginAccept the package installation when prompted. The package adds the V2 CLI plugin; it is not the Docker daemon itself. If APT reports that docker-compose-plugin has no installation candidate, return to the repository and release check rather than substituting an unrelated package name.
4. Verify from the same account and shell
docker compose versionA working installation prints a Compose V2 version (a value beginning with v2). Run the command as the user who will run your Compose projects. If it works only with sudo, the package may be installed system-wide but your non-root Docker executable or plugin search path may differ; inspect the executable being selected with command -v docker and correct the installation rather than permanently using sudo for every Compose command.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Fix on Fedora, RHEL, and CentOS
On Fedora and the Red Hat Enterprise Linux family, enable Docker’s repository for the operating system and then install the matching plugin package. The package manager differs by release:
sudo dnf install docker-compose-pluginOn systems that still use YUM, the equivalent command is:
sudo yum install docker-compose-pluginUse the package manager already supported by your release, and make sure the Docker repository is enabled before installing. If the package cannot be found, check the repository configuration and release compatibility first. After installation, verify with:
docker compose versionThe expected result is a Compose V2 version string. Package names and repository setup can vary across RPM-family releases, so do not copy a repository definition intended for another distribution or version.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Manual installation when packages are unavailable
A manual binary is a fallback for machines where the package manager cannot be used. Compose V2 must be placed in a Docker CLI-plugin directory, not merely somewhere on your shell’s PATH. Use one of these locations:
| Scope | Plugin path | Operational consequence |
|---|---|---|
| One user | ~/.docker/cli-plugins/docker-compose |
Only that user receives the plugin. |
| All users | /usr/local/lib/docker/cli-plugins/docker-compose |
The plugin is installed system-wide in the documented CLI-plugin location. |
Place and enable the binary
Copy a Compose V2 binary appropriate for your Linux architecture to the selected path, then make it executable:
chmod +x ~/.docker/cli-plugins/docker-composeFor a system-wide installation, apply the same operation to the file under /usr/local/lib/docker/cli-plugins/, using administrator privileges when required. The filename must be docker-compose inside the cli-plugins directory. A binary named only docker-compose in an arbitrary directory is not automatically registered as the docker compose subcommand.
Verify discovery
docker compose versionIf Docker still says that Compose is not a command, check each part of the manual installation:
Recommended Free Tools
- The file exists exactly at one of the supported plugin paths.
- The filename is
docker-compose, with no extra suffix. - The executable bit is set.
- You are running the same Docker CLI installation for which the plugin was installed.
- Your user can read and execute the file.
Manual installation transfers update responsibility to you. Unlike a package-managed plugin, it will not receive upgrades through your normal system update process. Record the binary’s version and replace it deliberately when you need a newer Compose V2 release.
Package install or manual binary: which should you choose?
| Option | Best fit | Advantages | Trade-off |
|---|---|---|---|
| APT package | Debian or Ubuntu with Docker’s repository available | Uses the system package manager and supports normal package updates | Requires a correctly configured Docker repository |
| DNF or YUM package | Fedora, RHEL, or CentOS with Docker’s repository available | Integrates with the host’s RPM package workflow | Repository configuration depends on the specific RPM-family release |
| Per-user plugin | A single account or a machine where system changes are restricted | Does not require a system-wide plugin location | Other users cannot use it, and upgrades are manual |
| System-wide plugin | Several users need the same Docker CLI plugin | One installation is available to all users who can execute it | Requires administrator access and manual upgrades |
Prefer the package-managed route when the correct Docker repository is available. Use a manual path when packaging is impossible, then treat version maintenance as part of operating the host.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot after installation
APT says the package cannot be found
This normally indicates that Docker’s official repository is absent, disabled, or configured for the wrong codename. Run sudo apt-get update after correcting the source and retry the install. Do not assume that an Ubuntu or Debian base system automatically includes Docker’s Compose plugin in its default repositories.
The package installed, but the command is unchanged
Confirm that the shell is invoking the expected Docker binary:
command -v docker
docker --versionA second Docker installation can be selected earlier in PATH, while the plugin was installed for another CLI location. Use the same account and executable for both the package installation and the verification command. Starting a new shell can also remove stale command lookup results after package changes.
The manual binary is ignored
Recheck the complete path and permissions. Docker searches its CLI-plugin directories; it does not treat every executable on PATH as a subcommand. The per-user path is under the invoking user’s home directory, while the system-wide path is under /usr/local/lib/docker/cli-plugins/. Installing into one account’s home directory and testing as another account will produce the same “not a docker command” message.
Best Value
docker compose version works, but a project command fails
That is a different stage of the problem. A successful version check proves that the CLI can discover Compose. A later failure from docker compose up, config, or another project command may concern the project file, image access, environment variables, or Docker Engine connectivity. Keep the plugin-discovery fix separate from those runtime errors so that you do not undo a working installation.
Do not apply unrelated legacy fixes
Older troubleshooting posts sometimes suggest adding "experimental": true to /etc/docker/daemon.json. That setting is not the remedy for an unregistered Compose CLI subcommand. The error is produced because the client cannot find the Compose plugin; changing daemon configuration does not install or expose that client extension.
Free tools Windows power users keep installed
One-click scans. No signup required.
Likewise, Homebrew-based instructions target macOS and are not a Linux package solution. On Linux, use the Docker repository with the host’s package manager or place the Compose V2 binary in a supported CLI-plugin directory.
A repeatable repair checklist
- Run
docker compose versionand confirm that the failure is the unknown-subcommand message. - Check
docker --versionandcommand -v dockerso you know which CLI is being tested. - On Debian or Ubuntu, verify Docker’s official APT repository matches the installed release.
- Run
sudo apt-get update, thensudo apt-get install docker-compose-plugin. - On Fedora, RHEL, or CentOS, enable Docker’s repository and run the appropriate
dnforyuminstall command. - If packages are unavailable, put the Compose V2 binary at
~/.docker/cli-plugins/docker-composeor/usr/local/lib/docker/cli-plugins/docker-compose. - Run
chmod +xon the binary and test as the same user who will run Compose. - Finish with
docker compose version; a V2 version confirms that the CLI plugin is registered.
Bottom line
“Compose is not a docker command” on Linux almost always means that Docker Compose V2 is missing or outside the Docker CLI’s plugin search paths. Install docker-compose-plugin from Docker’s official repository when possible, use the supported manual plugin path only when necessary, and verify the repair with docker compose version. Keep the space-separated V2 command distinct from the older docker-compose executable.
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.
