Docker 기본 명령어

핵심 요약

Docker 명령을 처음 익힐 때는 모든 옵션을 암기하기보다 다음 흐름을 이해하는 것이 중요합니다.

1. Docker Engine과 클라이언트 상태를 확인합니다.
2. 이미지를 내려받거나 만듭니다.
3. 이미지의 생성 구성으로 컨테이너를 만듭니다.
4. 컨테이너의 상태, 로그와 내부 프로세스를 확인합니다.
5. 필요할 때 컨테이너를 중지·시작하거나 재생성합니다.
6. 삭제하기 전에는 대상과 데이터 보존 범위를 확인합니다.

처음에는 다음 명령부터 익히면 됩니다.

docker version
docker info
docker image ls
docker container ls
docker container ls -a
docker container logs 컨테이너명
docker container inspect 컨테이너명
docker container stop 컨테이너명
docker container start 컨테이너명

Docker 명령은 이미지, 컨테이너, 네트워크와 볼륨처럼 관리 대상을 명시하는 형식으로 사용하면 의미를 파악하기 쉽습니다.

docker 관리대상 하위명령 옵션 대상

예:

docker container ls --all

짧은 별칭도 사용할 수 있습니다.

docker ps -a

두 명령은 같은 목적으로 사용하지만, 이 문서에서는 처음 학습할 때 구조를 이해하기 쉽도록 전체 형식을 먼저 제시합니다.

Docker CLI의 기본 구조

docker 명령과 Docker Engine

터미널에서 입력하는 docker는 Docker CLI 명령입니다. Docker CLI는 Docker 데몬에 요청을 보내 이미지, 컨테이너, 네트워크와 볼륨을 관리합니다.

따라서 docker 명령 파일이 설치되어 있어도 Docker 데몬이 실행 중이 아니거나 현재 사용자에게 Docker 소켓 접근 권한이 없으면 명령이 실패할 수 있습니다.

Docker Engine 설치와 권한 설정은 Docker Engine 설치 문서를 참고합니다.

명령의 기본 형식

docker 관리대상 하위명령 옵션 대상

다음 명령을 예로 살펴보겠습니다.

docker container logs --tail 50 nginx-web

전체 형식과 짧은 별칭

Docker는 일부 명령에 짧은 별칭을 제공합니다.

팀 문서와 자동화에서는 한 문서 안에서 선택한 형식을 일관되게 사용하는 것이 좋습니다.

설치와 연결 상태 확인

docker version: 클라이언트와 서버 버전 확인

docker version

Docker CLI가 데몬에 정상적으로 연결되면 일반적으로 Client와 Server 정보가 함께 표시됩니다.

Client만 표시되고 Server 연결 오류가 나타나면 다음 항목을 확인합니다.

• Docker 서비스 실행 상태
• 현재 사용자의 Docker 소켓 접근 권한
• 현재 선택한 Docker Context
• 원격 Docker 호스트 설정 여부

간단한 버전 문자열만 확인하려면 다음 명령을 사용할 수 있습니다.

docker --version

docker info: Docker 시스템 정보 확인

docker info

컨테이너와 이미지 수, 스토리지 드라이버, 로깅 드라이버, 운영체제와 Docker Root Dir 등 Docker 시스템 전반의 정보를 확인할 수 있습니다.

출력이 길면 다음과 같이 확인할 수 있습니다.

docker info | less

docker context ls: Docker Context 확인

docker context ls

현재 docker 명령이 어느 Docker 데몬을 대상으로 하는지 확인합니다. 별표(*)가 표시된 Context가 현재 선택된 대상입니다.

로컬 서버를 관리한다고 생각했는데 예상과 다른 컨테이너가 보이면 삭제 명령을 실행하기 전에 Context를 먼저 확인합니다.

이미지 관리

이미지는 컨테이너를 만들기 위한 읽기 전용 템플릿입니다. 이미지를 내려받는 것과 그 이미지로 컨테이너를 만드는 것은 서로 다른 작업입니다.

docker image ls: 이미지 목록 확인

docker image ls

짧은 형식:

docker images

일반적으로 저장소 이름, 태그, 이미지 ID, 생성 시점과 크기를 확인할 수 있습니다.

특정 저장소의 이미지만 확인하려면 이름을 지정합니다.

docker image ls nginx

docker image pull: 이미지 내려받기

docker image pull nginx:alpine

태그를 생략하면 일반적으로 latest 태그를 사용합니다.

docker image pull nginx

운영 문서에서는 latest에 의존하기보다 검증한 태그를 명시하는 편이 좋습니다. 같은 태그가 나중에 다른 이미지 내용을 가리킬 수 있기 때문입니다.

docker image inspect: 이미지 상세 정보 확인

docker image inspect nginx:alpine

JSON 형식으로 이미지 구성, 환경 변수, 기본 명령, 노출 포트와 레이어 정보를 확인합니다.

특정 항목만 출력하려면 --format을 사용할 수 있습니다.

docker image inspect nginx:alpine --format '{{json .Config.ExposedPorts}}'

이 출력은 실행 환경과 이미지 버전에 따라 달라집니다.

docker image history: 이미지 레이어 확인

docker image history nginx:alpine

이미지를 구성하는 레이어와 각 단계의 크기를 확인할 때 사용합니다.

docker image rm: 이미지 삭제

삭제 전에 해당 이미지를 사용하는 컨테이너가 있는지 확인합니다.

docker container ls -a --filter ancestor=nginx:alpine

대상을 확인한 뒤 이미지를 삭제합니다.

docker image rm nginx:alpine

이미지를 사용하는 컨테이너가 남아 있으면 삭제가 거부될 수 있습니다. 이때 원인을 확인하지 않고 강제 삭제 옵션부터 사용하지 않습니다.

컨테이너 만들기와 실행

docker container run: 컨테이너 생성과 실행

docker container run --name nginx-web -d nginx:alpine

이 명령은 다음 작업을 수행합니다.

1. 로컬에 이미지가 없으면 이미지를 내려받습니다.
2. 이미지와 지정한 옵션으로 새 컨테이너를 만듭니다.
3. 컨테이너의 기본 프로세스를 시작합니다.

주요 옵션:

포트 게시

Nginx 컨테이너의 포트 80을 호스트 포트 8080으로 게시하는 예입니다.

docker container run --name nginx-web -d -p 8080:80 nginx:alpine

포트 게시 순서는 다음과 같습니다.

호스트 IP:호스트 포트:컨테이너 포트

호스트 IP를 생략한 -p 8080:80은 기본적으로 모든 네트워크 인터페이스에 게시될 수 있습니다. 방화벽만 믿지 말고 공개 범위를 확인합니다.

로컬 호스트에서만 접근하게 제한하는 예:

docker container run --name nginx-web -d -p 127.0.0.1:8080:80 nginx:alpine

Docker가 게시한 포트는 UFW 또는 firewalld 규칙보다 먼저 처리될 수 있습니다. 공개 서버에서는 Docker의 방화벽 동작과 DOCKER-USER 체인을 함께 확인합니다.

환경 변수 전달

docker container run --name example-app -d -e APP_ENV=development example-image:tag

명령 기록과 프로세스 정보에 비밀정보가 노출될 수 있으므로 실제 암호, API 키와 토큰을 명령줄에 직접 입력하지 않습니다.

일회성 컨테이너

docker container run --rm alpine:latest echo "hello"

프로세스가 끝나면 컨테이너가 자동으로 삭제됩니다. 실행 결과를 조사해야 하거나 생성된 파일을 보존해야 하는 작업에는 --rm 사용 여부를 신중히 결정합니다.

컨테이너 상태 확인

docker container ls: 실행 중인 컨테이너 목록

docker container ls

짧은 형식:

docker ps

컨테이너 ID, 이미지, 실행 명령, 생성 시점, 상태, 포트와 이름을 확인합니다.

docker container ls -a: 모든 컨테이너 목록

중지된 컨테이너까지 확인합니다.

docker container ls -a

삭제나 정리 명령을 실행하기 전에는 이 목록을 먼저 확인합니다.

목록 필터링

실행 상태가 종료된 컨테이너만 확인하는 예:

docker container ls -a --filter status=exited

이름에 nginx-web이 포함된 컨테이너 확인:

docker container ls -a --filter name=nginx-web

필터는 지원하는 명령마다 사용할 수 있는 키가 다릅니다. 현재 명령의 --help와 Docker CLI 문서를 확인합니다.

출력 형식 지정

docker container ls --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'

--format은 Go 템플릿 문법을 사용합니다. 셸에 따라 따옴표와 이스케이프 방식이 달라질 수 있습니다.

컨테이너 시작·중지·재시작

docker container stop: 정상 종료 요청

docker container stop nginx-web

컨테이너의 주 프로세스에 정상 종료 신호를 보내고 일정 시간 기다린 뒤 종료합니다.

docker container start: 중지된 기존 컨테이너 시작

docker container start nginx-web

docker start는 중지된 기존 컨테이너를 같은 생성 구성으로 다시 시작합니다. 포트 게시, 바인드 마운트, 이미지와 환경 변수 같은 생성 옵션은 바뀌지 않습니다.

docker container restart: 기존 프로세스 재시작

docker container restart nginx-web

docker restart는 기존 컨테이너의 프로세스를 같은 생성 구성으로 재시작합니다. 설정 파일을 바인드 마운트한 경우 컨테이너 내부 애플리케이션이 바뀐 파일을 다시 읽을 수 있지만, 컨테이너 생성 옵션 자체는 변경되지 않습니다.

생성 옵션 변경에는 컨테이너 재생성이 필요

다음 항목을 바꾸려면 일반적으로 기존 컨테이너를 제거하고 새 구성으로 다시 만들어야 합니다.

• 포트 게시
• 바인드 마운트와 볼륨 연결
• 컨테이너 이미지
• 환경 변수
• 재시작 정책을 제외한 여러 생성 옵션

기존 컨테이너의 생성 구성을 먼저 확인합니다.

docker container inspect nginx-web

영속 데이터의 위치와 복구 방법을 확인하지 않은 상태에서 컨테이너를 제거하지 않습니다.

docker container kill: 즉시 종료

docker container kill nginx-web

정상 종료를 기다리지 않고 신호를 보내므로 데이터 기록 중인 애플리케이션에 영향을 줄 수 있습니다. 일반적인 중지는 docker container stop을 먼저 사용합니다.

로그와 내부 상태 확인

docker container logs: 로그 확인

docker container logs nginx-web

마지막 50줄만 확인:

docker container logs --tail 50 nginx-web

실시간으로 이어서 확인:

docker container logs --follow nginx-web

종료:

Ctrl + C

docker logs에 표시되는 내용은 컨테이너가 표준 출력과 표준 오류로 보낸 로그입니다. 애플리케이션이 컨테이너 내부 파일에만 로그를 기록하면 이 명령에 나타나지 않을 수 있습니다.

docker container inspect: 상세 구성 확인

docker container inspect nginx-web

다음 항목을 조사할 때 유용합니다.

• 현재 상태와 종료 코드
• 이미지
• 환경 변수
• 포트 게시
• 마운트
• 네트워크와 IP 주소
• 재시작 정책

특정 항목만 확인하는 예:

docker container inspect nginx-web --format '{{.State.Status}}'

docker container top: 실행 중인 프로세스 확인

docker container top nginx-web

컨테이너 안에서 실행 중인 프로세스 목록을 확인합니다.

docker container stats: 자원 사용량 확인

docker container stats

CPU, 메모리, 네트워크와 블록 입출력 사용량을 실시간으로 확인합니다.

한 번만 출력하고 종료:

docker container stats --no-stream

docker container port: 게시 포트 확인

docker container port nginx-web

컨테이너 포트가 어느 호스트 주소와 포트로 게시되었는지 확인합니다.

실행 중인 컨테이너 안에서 명령 실행

docker container exec

실행 중인 컨테이너 안에서 명령을 실행합니다.

docker container exec nginx-web nginx -t

대화형 셸 실행:

docker container exec -it nginx-web sh

이미지에 Bash가 설치되어 있다면 다음 명령을 사용할 수 있습니다.

docker container exec -it 컨테이너명 bash

경량 이미지에는 bash가 없고 sh만 있을 수 있습니다.

컨테이너 셸 종료:

exit

컨테이너 내부에서 직접 수정한 파일은 컨테이너 재생성 시 사라질 수 있습니다. 지속해야 하는 설정은 Dockerfile, Compose 파일, 볼륨 또는 바인드 마운트로 관리합니다.

컨테이너 삭제

삭제 전 확인

docker container ls -a --filter name=nginx-web
docker container inspect nginx-web

컨테이너에 쓰인 데이터가 볼륨, 바인드 마운트 또는 컨테이너의 쓰기 가능 레이어 중 어디에 저장되는지 확인합니다.

중지된 컨테이너 삭제

docker container rm nginx-web

실행 중인 컨테이너는 먼저 중지합니다.

docker container stop nginx-web
docker container rm nginx-web

강제 삭제 옵션 -f는 실행 중인 컨테이너를 종료하고 삭제하므로 일반적인 정리 절차의 기본값으로 사용하지 않습니다.

볼륨과 바인드 마운트

Docker가 관리하는 저장 공간인 볼륨과 호스트의 실제 파일 또는 폴더를 연결하는 바인드 마운트는 서로 다른 개념입니다.

볼륨 목록 확인

docker volume ls

볼륨 생성

docker volume create app-data

볼륨 상세 정보 확인

docker volume inspect app-data

볼륨을 연결해 컨테이너 실행

docker container run --name nginx-web -d \
  --mount type=volume,source=app-data,target=/usr/share/nginx/html \
  nginx:alpine

바인드 마운트 연결

docker container run --name nginx-web -d \
  --mount type=bind,source=/srv/nginx/html,target=/usr/share/nginx/html,readonly \
  -p 8080:80 \
  nginx:alpine

readonly를 사용하면 컨테이너가 연결된 호스트 파일을 변경하지 못하게 제한할 수 있습니다.

Docker는 복잡한 마운트 구성에서 --mount 문법 사용을 권장합니다. -v는 원본 호스트 경로가 없을 때 폴더를 자동 생성할 수 있지만, --mount type=bind는 원본 경로가 없으면 오류를 내므로 경로 오타를 발견하는 데 도움이 됩니다.

볼륨 삭제

볼륨을 사용하는 컨테이너와 데이터 백업 여부를 먼저 확인합니다.

docker volume inspect app-data
docker container ls -a --filter volume=app-data

확인한 볼륨만 삭제합니다.

docker volume rm app-data

볼륨 삭제는 영속 데이터를 잃게 할 수 있습니다. 데이터베이스 볼륨은 검증된 백업과 Restore 절차 없이 삭제하지 않습니다.

네트워크 관리

네트워크 목록 확인

docker network ls

네트워크 생성

docker network create app-network

네트워크 상세 정보 확인

docker network inspect app-network

컨테이너를 네트워크에 연결

컨테이너 생성 시 연결:

docker container run --name nginx-web -d --network app-network nginx:alpine

실행 중인 기존 컨테이너 연결:

docker network connect app-network nginx-web

연결 해제:

docker network disconnect app-network nginx-web

네트워크 삭제

docker network inspect app-network
docker network rm app-network

연결된 컨테이너가 있으면 일반적으로 삭제가 거부됩니다.

Docker Compose 기본 명령

Docker Compose에서 Compose 파일에 선언된 구성 단위는 서비스, 서비스 정의로 생성된 실행 인스턴스는 컨테이너, 같은 프로젝트 이름으로 관리되는 전체 묶음은 Compose 프로젝트입니다.

다음 명령은 compose.yaml이 있는 프로젝트 폴더에서 실행합니다.

구성 확인

docker compose config

변수 치환을 포함한 최종 Compose 구성을 확인합니다. 출력에 비밀정보가 포함될 수 있으므로 공유하기 전에 내용을 점검합니다.

서비스 생성과 시작

docker compose up -d

이미지나 Compose 서비스 구성이 바뀌면 필요한 컨테이너를 생성하거나 재생성합니다.

이미지도 다시 빌드해야 하는 경우:

docker compose up -d --build

상태 확인

docker compose ps

로그 확인

docker compose logs --tail 100

특정 서비스 로그를 이어서 확인:

docker compose logs --follow 서비스명

서비스 안에서 명령 실행

docker compose exec 서비스명 sh

Compose 프로젝트 중지와 제거

docker compose stop

컨테이너를 중지하지만 제거하지 않습니다.

docker compose start

중지된 기존 컨테이너를 같은 구성으로 시작합니다.

docker compose down

Compose 프로젝트의 컨테이너와 기본 네트워크를 제거합니다. 기본적으로 이름 있는 볼륨은 제거하지 않지만, 옵션과 Compose 파일 구성을 확인해야 합니다.

docker compose down --volumes는 Compose 프로젝트의 볼륨을 삭제할 수 있으므로 영속 데이터가 있는 환경에서는 백업과 복구 절차를 확인하지 않고 실행하지 않습니다.

Docker Compose 실습은 Docker Nginx Compose 문서를 참고합니다.

디스크 사용량과 정리 명령

docker system df: Docker 디스크 사용량 확인

docker system df

이미지, 컨테이너, 로컬 볼륨과 Build Cache의 사용량과 회수 가능 공간을 확인합니다.

상세 정보:

docker system df -v

docker container prune: 중지된 컨테이너 전체 정리

docker context show
docker container ls -a

삭제 범위와 데이터 보존 상태를 확인한 경우에만 실행합니다.

docker container prune

docker image prune

docker image prune

기본적으로 사용하지 않는 dangling 이미지를 정리합니다. -a를 추가하면 어떤 컨테이너에서도 사용하지 않는 이미지까지 범위가 넓어지므로 다시 내려받아야 할 이미지도 삭제될 수 있습니다.

docker volume prune

docker volume ls
docker volume prune

볼륨에는 데이터베이스와 업로드 파일 같은 영속 데이터가 있을 수 있습니다. 이름만으로 불필요하다고 판단하지 말고 연결된 컨테이너, Backup과 Restore 가능 여부를 확인합니다.

docker system prune

docker system prune

Docker 공식 문서 기준으로 중지된 컨테이너, 사용하지 않는 네트워크, dangling 이미지와 사용하지 않는 Build Cache를 정리합니다. -a는 사용하지 않는 이미지 전체로 범위를 넓히고, --volumes는 사용하지 않는 익명 볼륨까지 포함할 수 있습니다.

운영 호스트에서는 편의를 위한 첫 해결 명령으로 사용하지 않습니다. docker system df -v와 개별 목록 명령으로 대상을 확인한 뒤 필요한 객체만 명시적으로 정리하는 편이 안전합니다.

도움말과 명령 탐색

최상위 도움말

docker --help

관리 대상 도움말

docker container --help
docker image --help
docker network --help
docker volume --help
docker compose --help

하위 명령 도움말

docker container run --help
docker container logs --help
docker image ls --help

Docker CLI가 업데이트되면 지원 옵션이 달라질 수 있으므로 현재 설치된 버전의 --help와 Docker 공식 CLI 문서를 함께 확인합니다.

기본 실습

다음 실습은 Docker Engine이 설치되고 현재 사용자가 docker 명령을 실행할 수 있다는 전제의 예시입니다. 이 문서 작성 과정에서는 별도 환경에서 직접 실행하지 않았습니다.

1단계: Docker 상태 확인

docker version
docker info

2단계: 기존 대상 확인

같은 이름의 컨테이너가 있는지 확인합니다.

docker container ls -a --filter name=nginx-web

결과가 있다면 기존 컨테이너의 용도와 구성을 확인하고, 이 실습을 그대로 실행하지 않습니다.

3단계: Nginx 이미지 내려받기

docker image pull nginx:alpine

확인:

docker image ls nginx

4단계: Nginx 컨테이너 실행

docker container run --name nginx-web -d -p 127.0.0.1:8080:80 nginx:alpine

이 구성은 호스트의 로컬 주소에만 포트를 게시합니다.

5단계: 상태와 포트 확인

docker container ls --filter name=nginx-web
docker container port nginx-web

6단계: HTTP 응답 확인

Docker 호스트에서 실행합니다.

curl -I http://127.0.0.1:8080

예상 결과에는 HTTP 상태 줄과 Nginx 응답 헤더가 포함됩니다. 실제 출력은 이미지 버전과 환경에 따라 달라질 수 있습니다.

7단계: 로그 확인

docker container logs --tail 50 nginx-web

8단계: 컨테이너 내부 설정 검사

docker container exec nginx-web nginx -t

9단계: 중지와 재시작 확인

docker container stop nginx-web
docker container ls -a --filter name=nginx-web
docker container start nginx-web
docker container ls --filter name=nginx-web

10단계: 실습 컨테이너 제거

이 실습에서 직접 만든 nginx-web이 맞는지 다시 확인합니다.

docker container inspect nginx-web

확인한 컨테이너를 중지하고 제거합니다.

docker container stop nginx-web
docker container rm nginx-web

이미지는 다른 실습에서 다시 사용할 수 있으므로 자동으로 삭제하지 않습니다.

자주 사용하는 기본 명령 요약

핵심 정리

Docker 명령을 실행할 때는 현재 Docker Context와 대상을 먼저 확인합니다.

docker context show
docker container ls -a
docker image ls
docker volume ls
docker network ls

컨테이너에 문제가 생기면 바로 삭제하거나 재생성하기 전에 상태, 로그와 구성을 확인합니다.

docker container inspect 컨테이너명
docker container logs --tail 100 컨테이너명
docker container stats --no-stream 컨테이너명

docker start와 docker restart는 기존 컨테이너의 생성 구성을 바꾸지 않습니다. 포트 게시, 마운트, 이미지와 환경 변수 같은 생성 옵션을 바꾸려면 컨테이너 재생성이 필요합니다.

삭제 명령은 Docker 호스트의 데이터에 직접 영향을 줍니다. 특히 볼륨과 prune 명령은 대상 범위, Backup과 Restore 가능 여부를 확인한 뒤 사용합니다.

주의 사항과 한계

• Docker CLI의 명령과 옵션은 Docker Engine, Docker Desktop과 Compose CLI 버전에 따라 달라질 수 있습니다.
• 컨테이너 이름, 이미지 태그, 포트와 경로는 예시이며 실제 환경의 기존 객체와 충돌하지 않는지 먼저 확인합니다.
• docker container rm, docker image rm, docker volume rm, docker network rm과 각종 prune 명령은 삭제 작업입니다.
• 컨테이너를 삭제해도 볼륨이나 바인드 마운트의 데이터가 자동으로 삭제되는지는 실행 옵션과 구성에 따라 다릅니다. 데이터 위치를 먼저 확인합니다.
• 볼륨과 바인드 마운트는 같은 뜻이 아닙니다. 원본 유형과 마운트 구성을 확인한 뒤 구분해 설명합니다.
• 게시한 포트는 방화벽 정책에 영향을 줄 수 있습니다. 외부 공개 범위와 DOCKER-USER 체인을 함께 확인합니다.
• 이 문서는 Docker CLI 입문 범위를 다루며 Dockerfile 작성, 이미지 보안, Registry 운영, Compose Specification과 운영 환경 배포 전체를 대신하지 않습니다.

작성 및 검증 정보

• 작성자: apple2ne1
• 검토자: apple2ne1
• 직접 수행 여부: 이번 문서 작성 과정에서는 별도 Docker 환경에서 명령을 직접 실행하지 않음
• 마지막 문서 검토일: 2026-08-14
• 검증 방법: Docker 공식 CLI Reference, 필터·출력 형식 문서, 포트 게시와 파일 공유 문서 및 Vault의 기존 Docker Engine 29.6.2 검증 기록과 대조

참고 자료 및 출처

• Docker CLI Reference — Docker CLI 구조와 최상위 관리 명령 확인 — 2026-08-14
• Docker Container CLI Reference — 컨테이너 생성, 상태 확인, 로그, 시작·중지와 삭제 명령 확인 — 2026-08-14
• Docker Image CLI Reference — 이미지 목록, 내려받기, 검사와 삭제 명령 확인 — 2026-08-14
• Docker System CLI Reference — Docker 디스크 사용량과 시스템 관리 명령 확인 — 2026-08-14
• Docker CLI Filter — --filter 형식과 지원 범위 확인 — 2026-08-14
• Docker CLI Formatting — --format의 Go 템플릿 사용 방식과 셸 차이 확인 — 2026-08-14
• Docker Port Publishing — 포트 게시 순서와 기본 공개 범위 확인 — 2026-08-14
• Docker File Sharing — 볼륨과 바인드 마운트, -v와 --mount 차이 확인 — 2026-08-14
• Docker System Prune — docker system prune, -a와 --volumes의 삭제 범위 확인 — 2026-08-14

관련 문서

• Docker MOC
• Docker Engine 설치
• Docker Nginx 컨테이너
• Docker Nginx Compose
• Linux 기본 명령어