Docker Commands Reference

Docker Commands Reference is a concise, focused guide to the core Docker CLI commands engineers use daily, from building containers to debugging production issues. This reference captures the exact syntax, subtle flag interactions, and common pitfalls that arise when managing Dockerized applications in development, staging, and production environments.

Build Images

Build from Dockerfile with custom context and cache

docker build \
  --tag myapp:v1.2.3 \
  --file Dockerfile.prod \
  --cache-from myapp:latest \
  --target production \
  --progress plain \
  --no-cache \
  --build-arg NODE_ENV=production \
  --build-arg BUILD_DATE=2024-05-15 \
  -f ./app/Dockerfile \
  -t myapp:latest \
  .

• --cache-from pulls layers from existing images, reducing build time.
• --target selects a stage in a multi-stage Dockerfile (e.g., FROM base AS build, FROM alpine AS production).
• --progress plain shows detailed output for debugging slow builds.
• --no-cache forces re-evaluation of all build steps.
• Build arguments (--build-arg) are passed to ARG directives in the Dockerfile.

Build with buildkit backend

DOCKER_BUILDKIT=1 docker build \
  --output type=local,dest=./dist \
  --output type=oci,dest=myapp.tar \
  --load \
  --squash \
  --cache-to type=local,dest=build-cache \
  --cache-from type=local,src=build-cache \
  -t myapp:latest .

• --output supports multiple formats: local, oci, tar, s3, registry.
• --load pushes built image to the local Docker daemon.
• --squash combines all layers into a single layer, reducing image size.
• --cache-to and --cache-from use type=local with dest= for on-disk cache, type=registry for remote cache.

Common build pitfalls

• COPY . . in Dockerfile copies the entire build context, but COPY . /app may miss files not in the root.
• docker build uses the current directory as context by default; use --context or -c to specify a different path.
• ARG values are not available at runtime unless declared with ENV or ARG in the Dockerfile.
• --target does not include layers from earlier stages unless --load is used.

Run Containers

Run a container with port mapping, volume, and environment variables

docker run \
  --name webserver \
  --detach \
  --publish 80:80 \
  --publish 443:443 \
  --volume /data/logs:/var/log/app \
  --volume /data/config:/app/config:ro \
  --env NODE_ENV=production \
  --env DATABASE_URL=postgres://db:5432/app \
  --env-file .env.prod \
  --workdir /app \
  --restart unless-stopped \
  --ulimit nofile=65536:65536 \
  --health-cmd "curl -f http://localhost:3000/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  --health-start-period 10s \
  myapp:latest

• --volume src:dst mounts host directory to container; :ro makes it read-only.
• --env-file .env.prod reads key=value pairs from a file.
• --restart unless-stopped restarts container on Docker restart, unless explicitly stopped.
• --ulimit sets system limits (e.g., open file descriptors).
• Health checks are defined via --health-cmd, --health-interval, etc.

Run a container with network and custom configuration

docker run \
  --network app-network \
  --network-alias api \
  --link db:db \
  --ip 172.18.0.10 \
  --label app=web \
  --label version=v1.2.3 \
  --label env=prod \
  --entrypoint "/bin/start.sh" \
  --cmd "serve index.html" \
  myapp:latest

• --network app-network connects container to an existing network.
• --network-alias api assigns api as an alias in DNS.
• --link db:db creates a link to a container named db, making db available via DNS.
• --ip sets a static IP address in the network.
• --label adds metadata for filtering and orchestration.
• --entrypoint and --cmd override the image’s default ENTRYPOINT and CMD.

Common run pitfalls

• --publish is short for --publish-all when no port specified; --publish 80:80 maps host port 80 to container port 80.
• --volume with :ro does not sync changes from container to host; use :rw or :z (SELinux context).
• --detach starts container in background; docker run -d is equivalent.
• --env-file values override --env values if keys conflict.
• Health checks fail silently if --health-cmd exits non-zero but no error message is logged.

Manage Containers

List and inspect running containers

docker ps \
  --all \
  --filter "status=running" \
  --filter "label=app=web" \
  --filter "name=webserver" \
  --format "table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.Ports}}" \
  --no-trunc

• --all includes stopped containers; --filter supports status, name, label, exited, since, before, ancestor, volume.
• --format uses Go template syntax: {{.ID}}, {{.Names}}, {{.Status}}, {{.Ports}}.
• --no-trunc prevents truncation of long output (e.g., container names, images).

Stop, start, restart, and remove containers

docker stop webserver --time=30
docker start webserver
docker restart webserver --time=15
docker rm webserver --force --volumes
docker rm -f -v $(docker ps -q --filter "status=exited")

• --time=30 waits 30 seconds for graceful shutdown before killing the container.
• docker rm -f -v removes containers and their volumes, even if stopped.
• docker ps -q outputs only container IDs, useful in pipelines.

Attach to running container

docker exec -it webserver bash
docker exec -d webserver /bin/healthcheck.sh
docker exec --user app webserver ls /var/app

• --user app runs command as user app inside the container.
• --detach runs command in background; docker exec -d returns immediately.
• -i keeps stdin open; -t allocates a pseudo-TTY.

Image Management

Pull, push, and tag images

docker pull myapp:latest
docker pull registry.example.com/myapp:v1.2.3
docker tag myapp:latest myapp:prod
docker tag myapp:latest registry.example.com/myapp:2024-05-15
docker push registry.example.com/myapp:latest

• docker tag creates an alias for an image; docker push uploads to a registry.
• registry.example.com/myapp is a fully qualified image name.

Prune unused resources

docker image prune --all --filter "dangling=true" --filter "label=env=dev"
docker image prune --all --filter "until=24h" --force
docker container prune --filter "status=exited" --filter "label=cleanup=weekly"
docker system prune --volumes --filter "label=cleanup=monthly"

• --all removes all unused images, not just dangling.
• --filter supports dangling, label, until, since, before, created, reference.
• --volumes removes unused volumes.

Debugging and Troubleshooting

View logs from a container

docker logs --tail=100 --follow --since=1h --timestamps webserver
docker logs --details --no-color webserver

• --tail=100 shows last 100 lines.
• --follow is equivalent to tail -f.
• --since=1h shows logs from the last hour.
• --details includes metadata like container ID, exit code, and image name.

Inspect container and image details

docker inspect webserver
docker inspect myapp:latest
docker inspect --format '{{.State.Running}}' webserver
docker inspect --format '{{json .Mounts}}' webserver

• --format uses Go template syntax to extract specific fields.
• Output is a JSON object with nested structures.
• docker inspect includes detailed information about networks, volumes, ports, health checks, and environment.

Copy files between host and container

docker cp ./config.json webserver:/app/config.json
docker cp webserver:/var/log/app/error.log ./logs/
docker cp -r webserver:/app/data ./data/

• docker cp is equivalent to scp but without SSH.
• -r enables recursive copying of directories.

Common debugging failures

• docker exec fails if the container is not running.
• docker logs shows no output when the container exits immediately; use docker logs -f to follow.
• docker inspect reveals State.ExitCode and State.Error when a container fails.
• docker run with --rm automatically removes the container after it exits.
• --volume with :z (SELinux) or :Z (label) ensures correct file permissions in container.

Advanced: Build and Run Workflows

Build and run in one command

docker build -t myapp:latest . && \
  docker run -d --name webserver --publish 80:80 myapp:latest

• && chains commands in shell; ; runs them in parallel.
• docker-compose up --build builds and runs services defined in docker-compose.yml.

Use Docker Compose with CLI

docker-compose up --build --detach --force-recreate --no-recreate
docker-compose down --volumes --remove-orphans
docker-compose exec webserver bash
docker-compose logs -f --tail=50

• --force-recreate recreates containers even if config unchanged.
• --no-recreate skips recreation if config unchanged.
• --remove-orphans removes containers not defined in docker-compose.yml.

Multi-stage builds and optimized run

FROM node:18 as builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM node:18-alpine as production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
EXPOSE 3000
CMD ["node", "dist/index.js"]

# Build with --target production
docker build --target production -t myapp:latest .

• --target production uses only the production stage.
• COPY --from=builder copies files from a previous stage.
• node:18-alpine uses Alpine Linux, reducing image size.

Summary

This reference captures the essential Docker commands engineers use daily. It is not a tutorial, nor a conceptual overview. It is a precise, executable guide to building, running, and maintaining containers. Every command, flag, and configuration key is chosen for its impact on real systems. The reader knows exactly what to type, what to expect, and what to do when it breaks.

This page was rewritten on 10 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.