맥 M1/M2 Docker 설치 후 ‘docker’ 명령어 안 먹힐 때 설정 방법

M1/M2 맥북에 도커 데스크탑을 깔았는데, 설치는 잘 된 것 같은데 ‘docker run hello-world’ 같은 명령어는 꿈쩍도 안 하고, 터미널에 ‘docker’라고 쳐도 ‘command not found’ 에러만 떠서 당황스러우셨나요?

이는 주로 Docker Desktop이 시스템 PATH에 제대로 등록되지 않았거나, 내부 설정이 완료되지 않아 발생하는 문제입니다.

이 글에서는 M1/M2 맥 환경에서 Docker Desktop을 완벽하게 설치하고 초기 설정하는 5단계 가이드부터 흔히 겪는 ‘docker’ 명령어 오류 해결책, 그리고 필요 시 깔끔하게 초기화하는 방법까지 자세히 설명합니다.

M1/M2 맥 Docker Desktop 설치 및 초기 설정

M1/M2 맥은 Intel 기반과 아키텍처가 다르기 때문에, 반드시 Apple Silicon용 Docker Desktop을 설치해야 합니다. 구 버전이나 잘못된 아키텍처를 설치하면 예상치 못한 오류에 직면할 수 있습니다. 공식 웹사이트에서 정확한 버전을 다운로드하는 것이 첫걸음입니다.

설치 파일(.dmg)을 다운로드한 후 애플리케이션 폴더로 드래그하여 옮기는 것은 일반적인 맥 앱 설치 과정과 동일합니다. 이후 Docker Desktop을 처음 실행하면 초기 설정 마법사가 나타나는데, 여기서 권한 요청을 허용하고 백그라운드 서비스를 시작하도록 설정해야 합니다. 이 과정에서 필요한 네트워크 및 파일 시스템 접근 권한을 꼭 승인해주세요.

1. 공식 Docker Desktop 다운로드 — Docker 공식 웹사이트에서 ‘Apple chip’ (Apple Silicon) 버전을 다운로드합니다. 약 1GB 정도의 파일입니다.
2. 설치 및 실행 — 다운로드한 .dmg 파일을 열고 Docker Desktop을 Applications 폴더로 드래그합니다. 이후 애플리케이션 폴더에서 Docker Desktop을 실행합니다.
3. 초기 설정 동의 — 처음 실행 시 서비스 약관 동의 및 필수 권한 설정 요청이 나타납니다. 모든 요청을 승인하고 ‘Install required components’를 진행합니다.
4. Docker Desktop 시작 확인 — 메뉴 바에 고래 아이콘이 나타나고 ‘Docker Desktop is running’ 메시지를 확인합니다. 초기 실행 시 웜업 시간이 30초에서 1분 정도 소요될 수 있습니다.
5. 버전 확인 — 터미널을 열고 docker --version 및 docker compose version 명령어를 입력하여 정상적으로 버전 정보가 출력되는지 확인합니다. 이 단계에서 오류가 발생한다면 다음 섹션을 참고해야 합니다.

Photo by Elias Gamez on Pexels

‘docker’ 명령어 안 먹힐 때: PATH 환경 변수 설정과 트러블슈팅

Docker Desktop 설치 후 가장 흔하게 겪는 문제가 바로 터미널에서 docker 명령어를 인식하지 못하는 경우입니다. 이는 대부분 시스템의 PATH 환경 변수에 Docker 실행 파일의 경로가 제대로 추가되지 않았기 때문에 발생합니다. 터미널은 PATH에 등록된 경로에서만 명령어를 찾기 때문입니다.

Docker Desktop은 일반적으로 설치 시 자동으로 필요한 심볼릭 링크를 생성하고 PATH 설정을 돕지만, 때로는 수동 개입이 필요할 수 있습니다. 특히 기존에 다른 개발 환경 설정을 많이 건드렸거나, 특정 셸(zsh, bash 등)의 설정 파일이 복잡한 경우 이런 현상이 발생하기도 합니다. 침착하게 PATH 설정을 확인하고 재설정하는 것이 중요합니다.

1. 현재 PATH 확인 — 터미널에서 echo $PATH를 입력하여 현재 PATH에 /usr/local/bin 경로가 포함되어 있는지 확인합니다. Docker Desktop은 이 경로에 docker 실행 파일로 연결되는 심볼릭 링크를 생성합니다.
2. 셸 설정 파일 확인 및 수정
   • zsh 사용자: ~/.zshrc 파일을 엽니다. (예: open ~/.zshrc)
   • bash 사용자: ~/.bash_profile 또는 ~/.bashrc 파일을 엽니다. (예: open ~/.bash_profile)

   파일 내에 export PATH="/usr/local/bin:$PATH"와 같은 라인이 있는지 확인합니다. 없다면 파일 마지막에 추가하고 저장합니다. 이미 있다면 중복되지 않게 주의합니다.

3. 설정 변경 사항 적용 — 변경된 셸 설정 파일을 터미널에 적용하기 위해 source ~/.zshrc 또는 source ~/.bash_profile 명령어를 실행합니다.
4. Docker Desktop 재시작 — 메뉴 바의 고래 아이콘을 클릭하고 ‘Quit Docker Desktop’을 선택한 후, 다시 애플리케이션 폴더에서 Docker Desktop을 실행합니다.
5. 명령어 재확인 — 새로운 터미널 창을 열고 docker --version 또는 docker run hello-world를 입력하여 정상적으로 작동하는지 확인합니다. 여전히 문제가 있다면, 시스템을 재부팅해 보는 것도 하나의 방법입니다.

Photo by Wolfgang Weiser on Pexels

Docker Desktop 기본 설정 및 권장 사항

Docker Desktop은 단순히 컨테이너를 실행하는 것 외에도 다양한 설정 옵션을 제공합니다. 특히 M1/M2 맥 환경에서는 리소스 할당이 중요하며, 최적의 성능을 위해 몇 가지 설정을 조정하는 것이 좋습니다. 기본적으로 Docker Desktop은 시스템 리소스의 일부를 사용하므로, 자신의 개발 환경에 맞춰 적절히 조절해야 합니다.

Docker Desktop 설정은 메뉴 바의 고래 아이콘 클릭 후 ‘Settings’ (또는 ‘Preferences’)를 통해 접근할 수 있습니다. 여기서는 CPU, 메모리, 스왑 공간, 디스크 이미지 위치 등을 설정할 수 있습니다. 예를 들어, 메모리를 4GB에서 8GB로 늘리거나, CPU 코어 수를 2개에서 4개로 조정하면 대규모 컨테이너를 다룰 때 훨씬 원활하게 작동합니다. 일반적인 개발 환경에서는 CPU 4코어, 메모리 8GB 정도를 권장하지만, 이는 개인의 맥 사양과 사용 목적에 따라 유연하게 조절해야 합니다.

Photo by Tima Miroshnichenko on Pexels

Docker 완벽 초기화 및 재설치 가이드

위에서 제시된 해결책들로도 문제가 해결되지 않거나, Docker 관련 오류가 반복적으로 발생한다면, Docker Desktop을 완전히 초기화하고 재설치하는 것이 가장 확실한 방법일 수 있습니다. 때로는 알 수 없는 설정 충돌이나 손상된 파일로 인해 문제가 발생하기도 합니다. 이 과정은 약 5분 정도 소요되며, 대부분의 난해한 문제를 해결하는 데 효과적입니다.

Docker Desktop의 초기화는 단순히 앱을 삭제하는 것 이상으로, 관련 설정 파일, 캐시, 데이터 볼륨까지 제거하는 과정을 포함합니다. 이렇게 하면 깨끗한 상태에서 다시 시작할 수 있으며, 기존에 남아있던 잔여 파일들이 새로운 설치를 방해할 가능성을 0%로 줄일 수 있습니다. 단, 이 과정에서 현재 사용 중인 모든 Docker 이미지와 컨테이너 데이터는 삭제되므로, 중요한 데이터는 미리 백업해야 합니다.

1. Docker Desktop 종료 — 메뉴 바의 고래 아이콘 클릭 후 ‘Quit Docker Desktop’을 선택합니다.
2. 앱 삭제 — Applications 폴더에서 Docker Desktop 앱을 휴지통으로 드래그하여 삭제합니다.
3. 데이터 및 설정 파일 제거 (터미널 명령) — 터미널을 열고 다음 명령어를 순서대로 실행하여 남아있는 Docker 관련 파일을 제거합니다. 이 과정에서 사용자 비밀번호를 요구할 수 있습니다.
   • rm -rf ~/.docker
   • rm -rf ~/Library/Application\ Support/Docker\ Desktop
   • rm -rf ~/Library/Preferences/com.docker.docker.plist
   • rm -rf ~/Library/Saved\ Application\ State/com.docker.docker.savedState
   • rm -rf ~/Library/Containers/com.docker.docker
   • sudo rm -rf /usr/local/bin/docker*
   • sudo rm -rf /Applications/Docker.app (만약 Applications 폴더에서 삭제 안된 경우)
4. 시스템 재시작 — 맥을 재시작하여 모든 관련 프로세스와 캐시를 비웁니다.
5. Docker Desktop 재설치 — 이 글의 첫 번째 섹션에 있는 ‘M1/M2 맥 Docker Desktop 설치 및 초기 설정’ 가이드를 다시 따라하여 Docker Desktop을 새로 설치합니다.