Problem: docker-compose / docker compose says command not found —— Trove problem library

What you will run into

Two typical forms: in WSL, docker-compose --version says The command 'docker-compose' could not be found in this WSL 2 distro (a Docker Desktop shim talking), or docker compose says docker: unknown command: docker compose.

Compose is not a built-in docker subcommand — it is a separate plugin: installing docker does not install compose.

Why this happens

The Docker CLI plugin mechanism: docker <subcommand> looks for an executable named docker-<subcommand> in ~/.docker/cli-site docs and /usr/libexec/docker/cli-site docs Compose is exactly that plugin: not installed = unknown command.

The WSL "could not be found in this WSL 2 distro" message comes from the Docker Desktop shim installed in the Windows PATH — it checks whether the current distro has Desktop integration enabled or a native plugin installed.

docker compose = the docker CLI discovers and executes the docker-compose plugin binary; docker-compose (standalone) = executes the same-named binary directly. Both paths ultimately require a compose binary in a CLI plugin directory or on PATH.

The Ubuntu docker-compose-v2 package installs to /usr/libexec/docker/cli-site docs so docker compose` works immediately;

meanwhile a leftover Docker Desktop shim (/mnt/c/Program Files/Docker/Docker/resources/bin/) hit first in WSL checks WSL integration before deciding what to report.

Deterministic takeaway: figure out who is answering — unknown command: docker compose means the plugin directory lacks it (install docker-compose-v2 or drop the official plugin binary into `~/.docker/cli-site docs;

could not be found in this WSL 2 distro means the Desktop shim wins (enable Desktop WSL integration, or install the native plugin so the shim steps aside).

Step by step

1. Confirm docker itself works — Must do

docker --version

2. Branch on the error form — By diagnosis

• docker: unknown command: docker compose → install the plugin: sudo apt-get install -y docker-compose-v2 (Debian/Ubuntu) or download the official plugin binary to `~/.docker/cli-site docs (other distros, see the official Docker Compose install docs).
• The command 'docker-compose' could not be found in this WSL 2 distro → a Desktop shim is answering: either enable WSL integration for this distro in Docker Desktop settings (use Desktop's compose), or install the native plugin and check type docker-compose so the shim no longer wins.

3. Verify the wiring — Must do

docker compose version
# Expected: Docker Compose version v2.x.x (verified 2.40.3)

How to confirm it works

docker compose version prints a version and exits 0; in a directory with docker-compose.yml, docker compose config resolves the service list.

Other environments

Symptom

# Form 1: Desktop shim in WSL
The command 'docker-compose' could not be found in this WSL 2 distro.
We recommend to activate the WSL integration in Docker Desktop settings.

# Form 2: native CLI without the plugin
docker: unknown command: docker compose

Run 'docker --help' for more information

Signature: docker itself works; only compose-related commands fail. Form 2 = CLI present, plugin missing; Form 1 = Windows-side shim present, WSL integration/native plugin missing.

Cause

Compose is a docker CLI plugin (a docker-compose binary in a CLI plugin directory), not part of docker itself. Missing plugin = unknown command; in WSL the Desktop shim shows the "activate WSL integration" guidance. The fix is to install the compose plugin where the CLI can discover it.

Solution

1. Native: sudo apt-get install -y docker-compose-v2 (Debian/Ubuntu), or the official plugin binary in `~/.docker/cli-site docs;
2. Desktop users: enable WSL integration in settings;
3. Verify: docker compose version.

Related canonicals

Read in order: precondition -> same root / same domain / related:

• Related (similar errors, different cause):
• Docker daemon unreachable (compose talks to the same daemon socket)