Docker Compose 설치 오류는 현재 기준으로 docker-compose가 아니라 Docker CLI에 통합된 docker compose를 써야 한다는 점부터 확인하면 풀리는 경우가 많아요. Windows는 WSL2·가상화, Linux는 Compose 플러그인 경로와 Docker socket 권한, macOS는 Apple Silicon용 arm64 패키지 여부를 먼저 점검하면 해결 속도가 빨라져요.

Docker Compose 설치 오류는 무엇인지부터 구분해야 해요

Docker Compose 설치 오류는 먼저 ‘어떤 방식의 설치 문제인지’부터 구분해야 해요.AI로 생성된 이미지입니다
Docker Compose 설치 오류는 먼저 ‘어떤 방식의 설치 문제인지’부터 구분해야 해요.

Docker Compose 설치 오류는 단순히 설치 파일이 없다는 뜻이 아니라, 3가지 층위에서 나뉘어요. 첫째는 명령 자체를 못 찾는 오류예요. 예를 들어 docker: 'compose' is not a docker command 같은 메시지는 Compose v2 플러그인 경로나 설치 방식 문제일 수 있어요. 둘째는 설치는 됐지만 실행 권한이 없는 경우예요. Linux에서는 Docker Engine, Compose plugin, 사용자 socket 권한이 모두 맞아야 해요. 셋째는 운영체제 전제 조건이 부족한 경우예요. Windows에서는 WSL2, Hyper-V, BIOS 가상화 설정이 꺼져 있으면 Docker Desktop과 Compose가 함께 실패할 수 있어요.

지금 검색이 많은 이유도 예전 문서와 현재 배포 방식이 달라졌기 때문이에요. Compose v2는 별도 Python 패키지가 아니라 Docker CLI 플러그인으로 배포돼요. 그래서 오래된 튜토리얼처럼 pip install docker-compose를 따라 하면 버전 충돌이나 실행 파일 경로 문제가 생길 수 있어요. 최신 표준은 docker-compose가 아니라 docker compose예요.

Docker Compose 설치 오류는 운영체제별로 순서대로 점검하면 돼요

운영체제별로 필요한 조건을 하나씩 확인하면 원인을 빠르게 좁힐 수 있어요.AI로 생성된 이미지입니다
운영체제별로 필요한 조건을 하나씩 확인하면 원인을 빠르게 좁힐 수 있어요.

Docker Compose 오류 해결은 현재 Compose v2 기준으로, 명령어 확인 → 설치 방식 확인 → 운영체제 전제 조건 확인 → 권한 확인 순서로 진행하면 돼요. 아래 명령은 점검용 예시예요.

  1. 먼저 docker compose version을 실행해요. 여기서 버전이 나오면 Compose v2 플러그인은 인식된 상태예요. 반대로 docker-compose --version만 되고 docker compose가 안 되면 예전 방식이 남아 있을 수 있어요.

  2. Linux라면 Docker Engine 설치 여부와 Compose 플러그인 경로를 함께 확인해요. 플러그인 경로는 /usr/lib/docker/cli-plugins/ 또는 ~/.docker/cli-plugins/를 먼저 봐요. 경로가 틀리면 docker: 'compose' is not a docker command가 나올 수 있어요.

  3. Linux라면 현재 사용자가 Docker socket에 접근 가능한지도 봐요. 설치가 정상이어도 socket 권한이 없으면 permission denied 오류가 발생해요.

  4. Ubuntu/Debian 계열이라면 저장소 등록 방식도 확인해요. 레거시 apt-key는 비권장이라 저장소 설정이 꼬이면 Docker나 플러그인 설치가 실패할 수 있어요.

  5. Windows라면 Docker Desktop 버전과 WSL2 상태를 같이 확인해요. WSL2 비활성화, Hyper-V 미설정, BIOS Virtualization 비활성화는 설치·실행 오류의 대표 점검 항목이에요.

  6. macOS라면 Intel용 x86_64 패키지와 Apple Silicon용 arm64 패키지를 혼동하지 않았는지 봐요. Apple Silicon에서 아키텍처가 어긋나면 설치 후 실행 단계에서 충돌하거나 일부 이미지에서 오류가 날 수 있어요.

  7. 최근 설치 문제가 특정 빌드에서만 보인다면 Windows/macOS에서는 Docker Desktop 안정판으로 되돌려 재확인해요. 최신 안정판과 프리릴리스 채널은 분리 배포되기 때문에 채널 차이도 원인이 될 수 있어요.

bash
# 1) Compose v2 인식 확인
docker compose version

# 2) 예전 명령 잔존 여부 확인
which docker-compose

# 3) Linux 플러그인 경로 예시 확인
ls -al /usr/lib/docker/cli-plugins/
ls -al ~/.docker/cli-plugins/

# 4) Docker Engine 동작 확인
docker version

docker info

# 5) Linux 권한 문제 확인 예시
ls -l /var/run/docker.sock

# 6) Compose 파일 실행 테스트
docker compose config

Docker Compose 설치 방식은 예전 방법과 현재 권장 방법을 비교해서 봐야 해요

예전 방식과 현재 권장 방식을 구분하면 설치 혼동을 줄일 수 있어요.AI로 생성된 이미지입니다
예전 방식과 현재 권장 방식을 구분하면 설치 혼동을 줄일 수 있어요.

Docker Compose 오류는 설치 방식 차이를 이해하면 빠르게 줄일 수 있어요. 현재 권장 방식은 Docker CLI 플러그인으로 제공되는 Compose v2예요. 예전 방식인 docker-compose 독립 실행 파일이나 Python 패키지는 검색 결과에 아직 많이 남아 있지만, 지금 환경과 충돌할 수 있어요.

구분현재 권장 방식예전 대안주의할 점
명령어docker composedocker-compose최신 표준은 공백 방식이에요.
배포 형태Docker CLI 플러그인독립 바이너리 또는 Python 패키지pip install docker-compose는 버전 충돌을 만들 수 있어요.
Linux 설치 포인트Engine + plugin + socket 권한단일 바이너리 수동 설치플러그인 경로와 권한을 함께 확인해야 해요.
Windows/macOSDocker Desktop 포함 구성이 일반적개별 수동 구성Desktop 버전, 채널, WSL2·가상화 조건을 함께 봐야 해요.
Compose 파일 문법version: 없이도 동작 가능오래된 튜토리얼의 version: 중심 문법경고가 나도 치명적 오류가 아닌 경우가 있어요.

Docker Compose 설치 오류에서는 자주 헷갈리는 실수를 먼저 빼야 해요

첫 번째 실수는 명령어를 혼용하는 거예요. 현재 표준은 docker compose인데, 블로그 글 1개를 보고 docker-compose up를 치고 다른 글 1개를 보고 docker compose up를 섞으면 어떤 바이너리가 실행되는지 달라져요. 특히 PATH에 예전 실행 파일이 남아 있으면 문제 추적이 어려워져요.

두 번째 실수는 Linux에서 설치와 권한을 같은 문제로 보는 거예요. permission denied는 설치 실패가 아니라 socket 권한 문제인 경우가 있어요. 반대로 docker: 'compose' is not a docker command는 권한보다 플러그인 경로 또는 설치 방식 문제일 가능성을 먼저 봐야 해요. 이 두 오류는 원인이 다르니 확인 순서도 달라져야 해요.

세 번째 실수는 Windows에서 Docker Desktop만 다시 설치하는 거예요. 최근 릴리스 노트에서도 Windows/WSL2 연동, 가상화, 권한 문제가 반복적으로 개선됐어요. 즉 설치 파일만 바꾸는 것보다 WSL2 커널 상태, Hyper-V, BIOS Virtualization을 함께 봐야 해요. 같은 이유로 프리릴리스 채널을 쓰는 중이라면 안정판으로 되돌려 비교하는 것도 유효해요.

네 번째 실수는 Compose 파일 경고를 설치 오류로 오해하는 거예요. 최신 Compose 파일 형식에서는 version: 필드 없이도 동작해요. 오래된 예제를 복사했을 때 version: 관련 경고가 보여도, 그 경고 자체가 설치 실패 원인은 아닐 수 있어요. 먼저 설치 인식과 실행 환경부터 확인하는 편이 빨라요.

Docker Compose 설치 오류는 짧은 체크리스트로 재발을 줄일 수 있어요

설치 오류를 다시 만나지 않으려면 5가지 원칙만 기억하면 돼요. 첫째, 문서는 docker compose 기준으로 맞춰요. 둘째, Linux에서는 Engine·plugin·socket 권한 3가지를 항상 같이 봐요. 셋째, Ubuntu/Debian 계열은 비권장 apt-key 문서를 피하고 공식 저장소 등록 절차를 확인해요. 넷째, Windows는 WSL2와 가상화 설정을 Docker Desktop 버전과 묶어서 점검해요. 다섯째, macOS Apple Silicon은 arm64 패키지 사용 여부를 먼저 봐요.

실제로 문제를 좁힐 때는 오류 문장을 1개만 기준으로 잡는 게 좋아요. 예를 들어 not a docker command, permission denied, WSL2 is not installed, Virtualization must be enabled처럼 메시지 1줄이 원인 그룹을 나눠줘요. 그런 다음 명령어 방식, 플러그인 경로, 권한, 가상화, 아키텍처 순서로 확인하면 검색 시간을 줄일 수 있어요.

FAQ

왜 `docker-compose` 대신 `docker compose`를 써야 하나요?

현재 권장 방식이 Compose v2이기 때문이에요. Compose v2는 Docker CLI 플러그인으로 통합되어 배포되고, 최신 표준 명령은 하이픈 없는 docker compose예요.

`docker: 'compose' is not a docker command` 오류는 왜 나오나요?

Compose 플러그인이 설치되지 않았거나, Linux에서 /usr/lib/docker/cli-plugins/ 또는 ~/.docker/cli-plugins/ 같은 플러그인 경로가 잘못된 경우에 나올 수 있어요.

Linux에서 `permission denied`가 나오면 재설치해야 하나요?

항상 그렇지는 않아요. 설치는 정상인데 현재 사용자에게 Docker socket 권한이 없어서 생기는 경우가 있어요. 이때는 재설치보다 권한 점검이 먼저예요.

Windows에서 Docker Compose 설치가 안 되면 무엇부터 봐야 하나요?

Docker Desktop 버전만 보지 말고 WSL2 활성화, Hyper-V 설정, BIOS Virtualization 상태를 함께 확인해야 해요. 이 3가지는 설치·실행 오류와 직접 연결돼요.

Compose 파일의 `version:` 경고도 설치 오류인가요?

보통은 아니에요. 최신 Compose 파일 형식은 version: 없이도 동작해요. 오래된 튜토리얼 문법 때문에 경고가 나더라도, 치명적 설치 오류가 아닌 경우가 있어요.