できない.dev

docker-compose コマンドが見つからない(command not found)

docker-compose: command not found は、Compose V1 が廃止され docker compose に統合されたために出る。
呼び出しをハイフン無しのサブコマンド形式へ書き換えれば直る。

公開: 更新:

症状できない · exit 127
docker-compose version
sh: /recipe.sh: line 0: docker-compose: not found
解決後できた · exit 0
docker compose version
Docker Compose version v5.5.1

2026-09-17 に docker:cli(Docker 29.8.1) で実際に打って取った出力。検証環境の詳細

要約

docker-compose: command not found の主因は、ハイフン付きの Compose V1 が 2023 年に End of Life となり、現在の Docker では docker compose(スペース区切りのサブコマンド)に統合されたことだ。
まず docker compose version を実行し、こちらが動くなら呼び出し側を新形式へ書き換えれば解決する。

実行例

docker:cli イメージから単体の docker-compose を外し、Compose がプラグインとしてだけ入っている状態で始めている。
docker-compose version も、それを直接呼ぶスクリプトも、not found で終了コード 127 になった。
一方で cli-plugins には docker-compose が置かれていて、docker compose version は v5.5.1 を返した。
呼び出しを docker compose に書き換えたスクリプトは、サービス名 web を出力して終了コード 0 で通った。

$ docker-compose version
sh: /recipe.sh: line 0: docker-compose: not found
$ echo $?
127
$ ls /usr/local/libexec/docker/cli-plugins
docker-buildx
docker-compose
$ docker compose version
Docker Compose version v5.5.1
$ echo $?
0
$ cat deploy.sh
#!/bin/sh
docker-compose config --services
$ sh deploy.sh
deploy.sh: line 2: docker-compose: not found
$ echo $?
127
$ cat deploy.sh
#!/bin/sh
docker compose config --services
$ sh deploy.sh
web
$ echo $?
0

— 2026-09-17 時点の出力

検証環境Git 2.54.0 / Docker 29.8.1 / 2026-09-17 検証
検証日
実行環境
docker:cli Alpine Linux v3.24
バージョン
  • Git 2.54.0
  • Docker 29.8.1

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. V2 形式に置き換える

最も確実なのはコマンド呼び出しを新形式へ変えることである。

# 旧
docker-compose up -d
# 新(推奨)
docker compose up -d

docker compose version が Docker Compose version v2.x や v5.x を返せば、プラグイン形式の Compose は有効だ。
Compose は 2025 年 12 月のメジャーアップデートで v3・v4 を飛ばして v5.0.0(新しいタブで開く) になった(旧 Compose ファイル形式の 2.x / 3.x との混同を避けるため)。
v5 でも呼び出し方は同じ docker compose である。
Compose v1 の扱いは Docker 公式の廃止済み機能の一覧(新しいタブで開く) にある(v1 は保守を終えており、v2 への移行が求められている)。

2. Linux で compose プラグインを入れる

Engine のみの環境では plugin パッケージを追加する。

sudo apt-get update
sudo apt-get install docker-compose-plugin
docker compose version

3. 互換エイリアスを張る

スクリプトを今すぐ変更できない場合は一時的にエイリアスで橋渡しする。

echo 'alias docker-compose="docker compose"' >> ~/.bashrc
source ~/.bashrc

ただし CI では shell の alias が効かないため、最終的にはコマンド本体を docker compose へ書き換えるのが正攻法だ。

よくある原因

  1. V2 だけがインストールされている。
    Docker Desktop や新しい docker-ce には Compose V2 がプラグインとして同梱されるが、docker-compose 単体バイナリは入らない。
  2. compose プラグインを入れていない。
    Linux に Engine だけ入れた場合、docker-compose-plugin を別途インストールしないと両形式とも使えない。
  3. PATH に問題がある。
    プラグインは /usr/libexec/docker/cli-plugins 等に置かれ、ここが壊れているとサブコマンドも認識されない。
  4. 古いスクリプトが残っている。
    既存の Makefile・CI が docker-compose up をハードコードしている。