Beranda / Case Studies / Docker

Error docker-compose command not found pada Docker Modern (Compose v2)

Error docker-compose command not found pada Docker Modern (Compose v2)

Error docker-compose command not found muncul ketika sistem operasi tidak dapat menemukan binary atau plugin Docker Compose saat perintah docker-compose dijalankan. Kondisi ini menandakan bahwa Docker Compose tidak terpasang, tidak berada di PATH sistem, atau metode pemanggilan perintah yang digunakan sudah tidak sesuai dengan versi Docker yang terinstal. Error ini bersifat langsung dan menghentikan seluruh proses orkestrasi container sebelum Docker sempat membaca file docker-compose.yml.

Masalah ini sangat umum dialami pada lingkungan Linux server, macOS, maupun pipeline CI/CD yang menggunakan image Docker minimal. Perubahan besar pada arsitektur Docker sejak versi 20.10, khususnya migrasi dari Docker Compose v1 (binary terpisah) ke Docker Compose v2 (plugin terintegrasi), menjadi pemicu utama kebingungan ini. Banyak sistem masih mengikuti dokumentasi lama atau tutorial usang yang tidak lagi relevan dengan runtime Docker modern.

Secara teknis, error ini hampir selalu berkaitan dengan mismatch antara versi Docker Engine, metode instalasi Docker Compose, dan cara pemanggilan perintah di shell. Tanpa memahami konteks ini, upaya perbaikan sering kali salah arah dan justru memperparah masalah.

Penjelasan Error docker-compose command not found

Error command not found berasal dari shell, bukan dari Docker itu sendiri. Error ini muncul pada tahap paling awal eksekusi, sebelum Docker Engine menerima instruksi apa pun. Artinya, shell seperti Bash atau Zsh gagal menemukan executable bernama docker-compose di dalam PATH sistem.

Pada Docker Compose v1, docker-compose adalah binary mandiri yang biasanya berada di /usr/local/bin/docker-compose. Pada Docker Compose v2, perintah tersebut tidak lagi tersedia sebagai binary terpisah. Docker Compose v2 dijalankan sebagai subcommand dari Docker CLI dengan format docker compose, tanpa tanda strip.

Lingkungan yang paling sering terdampak adalah:

  • Linux server yang menginstal Docker Engine dari repository resmi tanpa plugin tambahan

  • macOS dengan Docker Desktop versi terbaru namun masih menggunakan perintah lama

  • Container CI/CD berbasis Alpine atau Debian slim

  • VM cloud yang menggunakan image OS minimal

Dalam semua kasus tersebut, Docker Engine dapat berjalan normal, tetapi orkestrasi multi-container gagal total karena Compose tidak dikenali oleh shell.

Penyebab Utama docker-compose command not found

Docker Compose Tidak Terinstal

Penyebab paling mendasar adalah Docker Compose memang belum pernah diinstal. Docker Engine dan Docker Compose adalah dua komponen berbeda. Menginstal Docker tidak otomatis menyediakan Docker Compose, terutama pada Linux server.

Di lapangan, kondisi ini sering terjadi pada server produksi yang hanya dipasang Docker Engine untuk menjalankan container tunggal, lalu belakangan membutuhkan Docker Compose untuk stack yang lebih kompleks.

Menggunakan Perintah Lama pada Docker Compose v2

Sejak Docker Compose v2, perintah docker-compose tidak lagi menjadi standar. Docker secara resmi menggantinya dengan docker compose. Sistem dengan Docker terbaru akan tetap berjalan normal, tetapi shell tidak akan pernah menemukan docker-compose karena binary tersebut tidak ada.

Kasus ini sangat sering ditemui pada developer yang berpindah mesin atau mengikuti tutorial lama tanpa memeriksa versi Docker.

Binary docker-compose Tidak Ada di PATH

Docker Compose v1 bisa terinstal dengan benar, tetapi tetap tidak bisa dipanggil jika lokasinya tidak termasuk dalam environment variable PATH. Ini umum terjadi pada instalasi manual atau sistem dengan konfigurasi PATH yang dikustomisasi.

Shell akan selalu mengembalikan error meskipun file binary sebenarnya ada di filesystem.

Instalasi Docker yang Tidak Lengkap atau Rusak

Pada beberapa sistem, terutama setelah upgrade OS atau Docker, plugin Docker Compose bisa hilang atau tidak terdaftar dengan benar. Docker Engine tetap berjalan, tetapi plugin Compose tidak dikenali oleh Docker CLI.

Ini sering terjadi pada upgrade mayor Docker atau ketika repository resmi Docker tidak dikonfigurasi ulang dengan benar.

Lingkungan CI/CD Menggunakan Image Minimal

Banyak image Docker populer untuk CI/CD tidak menyertakan Docker Compose secara default. Image seperti docker:latest atau alpine hanya menyediakan Docker CLI dasar tanpa plugin tambahan.

Pipeline akan gagal saat menjalankan docker-compose up meskipun perintah tersebut berjalan normal di mesin lokal.

Cara Memverifikasi Penyebab Error

Memeriksa Versi Docker Engine

Jalankan perintah berikut untuk memastikan Docker terpasang dan versinya:

docker version

Perintah ini memastikan Docker Engine dan Docker CLI tersedia. Jika perintah ini gagal, masalah bukan pada Docker Compose, melainkan pada instalasi Docker itu sendiri.

Memeriksa Ketersediaan Docker Compose v2

Untuk sistem modern, jalankan:

docker compose version

Jika perintah ini berhasil, berarti Docker Compose v2 tersedia dan error disebabkan oleh penggunaan perintah lama docker-compose.

Memeriksa Docker Compose v1

Untuk sistem lama atau instalasi manual, jalankan:

docker-compose version

Jika error tetap muncul, lanjutkan dengan mencari binary secara langsung:

which docker-compose

Atau:

ls /usr/local/bin/docker-compose

Langkah ini memastikan apakah binary ada tetapi tidak terdaftar di PATH.

Memeriksa Plugin Docker

Docker Compose v2 adalah plugin. Verifikasi plugin dengan:

docker info | grep -i compose

Atau:

docker plugin ls

Jika plugin tidak muncul, berarti Docker Compose v2 belum terpasang atau rusak.

Memeriksa Environment CI/CD

Pada pipeline CI/CD, periksa image yang digunakan dan dokumentasinya. Pastikan image tersebut memang menyertakan Docker Compose atau menyediakan mekanisme instalasi tambahan.

Solusi Utama docker-compose command not found

Menggunakan Perintah yang Benar untuk Docker Compose v2

Jika docker compose version tersedia, solusi paling tepat adalah mengganti seluruh penggunaan docker-compose menjadi:

docker compose up
docker compose down
docker compose build

Secara teknis, ini bekerja karena Docker CLI memanggil plugin Compose secara internal tanpa membutuhkan binary terpisah. Pendekatan ini adalah standar resmi Docker saat ini dan direkomendasikan untuk semua sistem baru.

Menginstal Docker Compose v2 di Linux

Jika Docker Compose v2 belum tersedia, instal plugin resmi dengan:

sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 \
  -o /usr/local/lib/docker/cli-plugins/docker-compose
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose

Lokasi ini dipilih karena Docker CLI secara otomatis memuat plugin dari direktori tersebut.

Menginstal Docker Compose v1 (Jika Diperlukan)

Untuk sistem legacy yang masih membutuhkan docker-compose, instal binary v1:

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" \
  -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Solusi ini hanya relevan jika aplikasi atau tooling lama belum kompatibel dengan Compose v2.

Menambahkan Lokasi Binary ke PATH

Jika binary sudah ada tetapi tidak dikenali, tambahkan ke PATH:

export PATH=$PATH:/usr/local/bin

Untuk permanen, tambahkan baris tersebut ke .bashrc atau .zshrc.

Solusi Alternatif Berdasarkan Lingkungan

macOS dengan Docker Desktop

Docker Desktop versi terbaru sudah menyertakan Docker Compose v2. Solusi terbaik adalah menggunakan docker compose dan menghindari instalasi manual yang bisa menyebabkan konflik.

Jika docker-compose tetap dibutuhkan, buat alias sementara:

alias docker-compose="docker compose"

Server Produksi Linux

Pada server produksi, gunakan repository resmi Docker dan pastikan paket berikut terinstal:

sudo apt install docker-compose-plugin

Pendekatan ini lebih stabil dibandingkan instalasi manual dari GitHub.

Pipeline CI/CD

Gunakan image yang sudah menyertakan Docker Compose, atau instal secara eksplisit di pipeline:

apk add docker-cli-compose

atau gunakan image khusus seperti docker/compose.

Pendekatan ini memastikan pipeline konsisten dan tidak bergantung pada environment lokal.

Kesalahan yang Sering Dilakukan

Kesalahan paling umum adalah menginstal ulang Docker berulang kali tanpa memeriksa versi Compose yang digunakan. Docker Engine yang berfungsi tidak menjamin Docker Compose tersedia.

Kesalahan lain adalah mencampur Docker Compose v1 dan v2 dalam satu sistem. Ini sering menyebabkan konflik PATH dan perilaku tidak konsisten antar shell.

Banyak pengguna juga mengandalkan tutorial lama yang masih menggunakan docker-compose tanpa menyadari bahwa perintah tersebut sudah deprecated.

Pendekatan yang benar selalu dimulai dari verifikasi versi Docker dan metode Compose yang didukung oleh sistem tersebut.

Pencegahan Error docker-compose command not found di Masa Depan

Gunakan Docker Compose v2 sebagai standar dan biasakan menggunakan docker compose pada semua dokumentasi internal.

Pastikan environment development, staging, dan production menggunakan metode instalasi Docker yang konsisten.

Di CI/CD, gunakan image yang eksplisit dan terdokumentasi, bukan image generik yang berubah-ubah.

Kelola PATH dengan disiplin dan hindari instalasi manual yang tidak terdokumentasi.

Perbarui dokumentasi internal setiap kali ada perubahan besar pada toolchain Docker.

Penutup

Error docker-compose command not found bukanlah bug pada Docker, melainkan indikasi kuat adanya ketidaksesuaian antara versi Docker, metode instalasi Docker Compose, dan cara pemanggilan perintah. Dengan memahami perbedaan arsitektur Docker Compose v1 dan v2 serta memverifikasi lingkungan secara sistematis, masalah ini dapat diselesaikan secara tuntas tanpa trial and error. Pendekatan yang tepat tidak hanya memperbaiki error saat ini, tetapi juga mencegah kegagalan serupa pada deployment dan pipeline di masa depan.