Docker를 설치하고 docker ps를 실행했는데 permission denied가 나오고, sudo docker ps는 된다면 먼저 사용자 권한을 확인해 보세요. 기본 Linux Docker Engine에서는 일반 사용자가 Docker 소켓에 접근하려면 sudo를 사용하거나 docker 그룹에 등록되어 있어야 합니다.
반면 Cannot connect to the Docker daemon이라면 서비스가 꺼져 있거나 접속 대상이 다를 수 있어요. 아래 명령은 systemd를 사용하는 Linux에서 관리자 권한으로 동작하는 Docker Engine 기준입니다. Docker Desktop·Rootless 환경은 서비스와 소켓 경로가 다릅니다.
이 글의 목차
오류 메시지부터 구분합니다
docker ps는 Docker를 시작하는 명령이 아닙니다. 명령줄 도구인 Docker CLI가 백그라운드 서비스인 Docker 데몬에 접속해 실행 중인 컨테이너 목록을 요청합니다. 설치, 서비스 실행, 사용자 접근 권한을 나눠 보면 원인을 찾기 편해요.
| 화면에 보이는 결과 | 먼저 확인할 항목 |
|---|---|
docker: command not found | CLI 설치 여부와 실행 파일 검색 경로(PATH) |
permission denied와 docker.sock | 소켓 접근 권한과 현재 세션의 그룹 |
Cannot connect to the Docker daemon | 데몬 실행 상태와 접속 주소 |
| 표 머리글만 나오고 오류 없음 | 실행 중인 컨테이너가 없는 정상 조회인지 확인 |
CLI가 인식되는지는 다음 명령으로 확인합니다. docker --version이 출력되어도 데몬이 실행 중이라는 뜻은 아닙니다.
command -v docker
docker --version명령 자체를 찾지 못한다면 Docker Engine 설치 문서에서 배포판과 설치한 패키지를 먼저 확인합니다. 그룹 등록은 실행 파일이 없는 문제를 해결하지 않습니다.
permission denied는 소켓 접근 권한을 확인합니다
기본 로컬 Engine은 /var/run/docker.sock이라는 Unix 소켓으로 요청을 받습니다. 일반적으로 소유자는 root, 그룹은 docker이며, 소유자와 해당 그룹에 읽기·쓰기 권한이 주어집니다. 실제 설정은 아래 명령으로 확인합니다.
ls -l /var/run/docker.sock
id -nG
docker ps
sudo docker ps소켓이 root:docker 소유이고 권한이 srw-rw----인데 현재 그룹 목록에 docker가 없다면 접근이 거부될 수 있습니다. sudo docker ps만 성공하는 결과는 권한 문제를 뒷받침하는 단서예요. 다만 sudo에서는 사용자 설정이 달라질 수 있으므로 두 명령이 같은 소켓을 조회하는지도 확인해야 합니다.
소켓 파일이 없다는 결과가 나오면 그룹부터 바꾸지 말고 아래의 서비스 상태와 접속 대상 확인으로 이동합니다. 오류 문구와 소켓 경로는 설치 방식과 버전에 따라 조금씩 달라질 수 있습니다.
일반 사용자를 docker 그룹에 등록합니다
docker 그룹은 Docker를 통해 호스트의 관리자 수준 작업을 할 수 있는 권한을 줍니다. Docker 보안 문서의 접근 권한 설명을 참고해 신뢰하는 운영 계정만 등록합니다. 일반 사용자 계정으로 Docker CLI를 실행해도, 이 방식의 Docker 데몬은 계속 관리자 권한으로 동작합니다. 관리자 권한 없이 데몬까지 실행하려면 Rootless 모드를 별도로 검토합니다.
1. 등록할 계정과 그룹을 확인합니다
Docker를 사용할 일반 사용자로 로그인한 터미널에서 실행합니다. whoami 결과가 등록 대상 계정인지 먼저 확인하세요.
whoami
getent group dockergetent group docker에 결과가 있으면 그룹 생성은 건너뜁니다. 아무 결과도 없고, 로컬 계정을 사용하는 환경이라면 다음 명령으로 그룹을 만듭니다.
sudo groupadd docker2. 기존 그룹을 유지하며 추가합니다
sudo usermod -aG docker "$USER"-G docker는 보조 그룹을 지정하고, -a는 기존 보조 그룹을 유지하면서 추가합니다. -a를 빼면 명령에 지정하지 않은 기존 보조 그룹에서 빠질 수 있으므로 그대로 사용합니다. 옵션의 의미는 usermod 매뉴얼에서도 확인할 수 있습니다.
위 명령은 $USER가 Docker를 사용할 일반 사용자일 때 적용합니다. sudo -i나 su -로 들어간 root 셸에서는 대상이 root가 될 수 있어요. 관리자가 대신 등록한다면 아래의 maru를 실제 일반 사용자 이름으로 바꿉니다. 이미 root 셸이라면 sudo를 생략합니다.
sudo usermod -aG docker maru3. 로그아웃 후 다시 로그인합니다
그룹 등록은 계정 정보에 저장되지만 이미 실행 중인 셸의 그룹 권한은 바로 갱신되지 않습니다. SSH 접속은 끊은 뒤 다시 연결하고, 데스크톱은 사용자 세션에서 로그아웃한 뒤 다시 로그인합니다. 기존 터미널이나 IDE 안에서 터미널 탭만 새로 열면 이전 그룹을 물려받을 수 있어요.
현재 터미널에서 먼저 확인하려면 아래 명령으로 docker 그룹을 적용한 하위 셸을 시작할 수도 있습니다. 그 셸에서 만든 파일은 소유 그룹이 docker가 될 수 있으므로 작업 범위를 확인합니다.
newgrp docker
id -nG
docker psid -nG에 docker가 포함되고 docker ps가 오류 없이 끝나면 해당 셸에서 접근할 수 있는 상태입니다. newgrp로 들어간 하위 셸은 exit로 나갑니다. 다른 터미널과 이미 실행 중인 프로그램의 권한은 이 명령으로 바뀌지 않습니다. 등록·재로그인 절차는 Docker의 Linux 설치 후 설정 문서를 기준으로 합니다.
Cannot connect는 Docker 서비스와 접속 대상을 확인합니다
Docker Engine 패키지를 설치했어도 서비스가 자동으로 시작되지 않는 환경이 있습니다. 이 글의 일반 Linux Engine에서는 다음 명령으로 상태를 확인합니다.
sudo systemctl status docker --no-pageractive (running)이면 서비스가 동작 중입니다. 중지 상태이고 이 호스트의 Docker를 사용할 예정이라면 서비스를 시작한 뒤 다시 조회합니다.
sudo systemctl start docker
sudo systemctl is-active docker
sudo docker psstart는 지금 서비스를 시작하는 명령입니다. 부팅 시 자동 시작도 필요하면 sudo systemctl enable docker를 별도로 실행합니다. enable만으로 현재 중지된 서비스가 시작되지는 않습니다.
시작이 실패하면 재시작을 반복하기보다 오류 로그를 확인합니다. 설정 충돌이나 저장 공간 부족처럼 로그가 가리키는 항목을 먼저 조사하세요.
sudo journalctl -u docker.service -b -n 100 --no-pagerUnit docker.service could not be found라면 현재 환경에 서비스가 설치되어 있는지 확인합니다. CLI만 설치했거나 Docker Desktop·Rootless를 사용하는 경우에는 위 시스템 서비스가 대상이 아닐 수 있습니다. Rootless의 서비스 상태는 해당 사용자로 systemctl --user status docker에서 확인합니다. 서비스 등록과 로그 조회는 systemd와 journalctl 사용법에서도 다룹니다.
서비스가 실행 중인데 연결이 실패하면 CLI가 어느 데몬을 보는지 확인합니다. 컨텍스트는 접속 주소 등을 묶어 둔 설정이며, 환경 변수가 다른 대상을 지정할 수도 있습니다.
docker context ls
printenv DOCKER_HOST DOCKER_CONTEXT기본 로컬 Engine을 사용하려던 환경인지 확인한 뒤에만 아래 설정을 적용합니다. 의도적으로 원격 서버·Docker Desktop·Rootless에 연결하는 환경에는 적용하지 않습니다.
unset DOCKER_HOST DOCKER_CONTEXT
docker context use default
docker psunset은 현재 셸의 변수만 해제합니다. 재로그인 후 되살아나면 셸 초기화 파일이나 IDE의 환경 설정에서 해당 변수를 살펴봅니다. Docker의 데몬 연결 문제 해결 문서와 컨텍스트 문서에 접속 대상 확인 방법이 설명되어 있습니다.
그룹을 추가했는데도 권한 오류가 남을 때
먼저 현재 셸에 적용된 그룹과 계정에 저장된 그룹을 비교합니다. id 명령은 사용자 이름을 생략하면 현재 프로세스의 정보를 조회합니다. 아래 명령은 Docker를 사용할 일반 사용자 셸에서 실행합니다.
id -nG
id -nG "$USER"
ls -l /var/run/docker.sock사용자 이름을 지정한 결과에는 docker가 있는데 첫 번째 결과에는 없다면 현재 세션이 이전 권한을 유지하는 상황입니다. 완전히 로그아웃한 뒤 다시 로그인하거나 newgrp docker로 확인합니다. 두 결과 모두 docker가 없다면 다른 계정에 등록했는지 살펴봅니다.
두 결과에 모두 docker가 있어도 실패한다면 오류에 나온 소켓 경로와 실제 소유 그룹을 다시 비교합니다. 소켓의 그룹이나 권한이 기본값과 다르면 Docker 서비스·소켓의 설정과 설치 방식을 확인해야 합니다. docker.sock에 chmod 666이나 chmod 777을 적용해 모든 로컬 사용자에게 접근을 열지 않습니다.
오류 경로가 ~/.docker/config.json이라면 데몬 소켓이 아니라 사용자 설정 파일의 권한 문제입니다. 이 경우에는 ls -ld "$HOME/.docker" "$HOME/.docker/config.json"으로 소유권을 먼저 확인합니다. 과거 sudo 사용으로 소유권이 바뀐 것이 맞다면 Docker 설치 후 설정 문서의 사용자 설정 권한 안내에 따라 해당 디렉터리를 조정합니다.
목록이 비어 있으면 조회는 성공한 상태입니다
docker ps가 오류 없이 표 머리글만 보여준다면 현재 접속한 데몬에 실행 중인 컨테이너가 없다는 뜻입니다. 중지된 컨테이너까지 보려면 -a를 붙입니다.
docker ps
docker ps -ahello-world처럼 실행 후 종료하는 컨테이너는 기본 목록에서 사라지고 전체 목록에는 남을 수 있습니다. docker ps 공식 문서에서도 기본 조회 대상을 실행 중인 컨테이너로 구분합니다. 조회가 된 뒤 컨테이너가 Restarting으로 반복 표시된다면 컨테이너 재시작 원인과 로그 확인으로 이어서 조사하면 됩니다.
그룹을 등록했다면 재로그인한 일반 사용자 세션에서 id -nG와 docker ps를 다시 확인해 보세요. 권한 오류가 사라졌는지와 실행할 컨테이너가 있는지는 별개의 확인 항목입니다.
