Docker Cheatsheet — 80+ Commands with Pitfalls, Compose, and Build Techniques

Download an image (or a specific tag) from a registry to the local daemon.

⚠ Common pitfall: Without a tag docker pulls `:latest`, which is a moving target. Pin the version for reproducible builds.

docker pull nginx

docker pull node:20-alpine

docker pull ghcr.io/user/app:v1.2.3

Upload a local image to a registry. The image must already be tagged with the registry path.

⚠ Common pitfall: Push fails with "denied" if you have not run `docker login` first, or the tag does not include the registry prefix.

docker push myorg/app:v1.0

docker push registry.example.com/team/app:latest

Build an image from a Dockerfile in <path> and tag it as <name>.

⚠ Common pitfall: The build context is the WHOLE folder — a missing .dockerignore can ship gigabytes of node_modules / .git into the daemon.

docker build -t myapp .

docker build -t myapp:v1.0 -f Dockerfile.prod .

docker build --no-cache -t myapp .

List all local images with repository, tag, ID, age, and size.

docker images

docker images -a

docker images --filter "dangling=true"

Remove a local image. Multiple images can be removed in one call.

⚠ Common pitfall: `rmi` is for IMAGES; `rm` is for CONTAINERS. Confusing these two is the #1 docker rookie mistake. If a container still uses the image, add -f to force.

docker rmi nginx:1.25

docker rmi -f myapp:old

docker rmi $(docker images -q -f "dangling=true")

Add a new tag pointing to an existing image. Both old and new tags share the same image ID.

⚠ Common pitfall: Tagging does not copy data — pushing the new tag re-uses existing layers and is fast.

docker tag myapp:latest myorg/myapp:v1.0

docker tag abc123 registry.example.com/team/app:prod

Export an image (with all layers + metadata) to a tar archive for air-gapped transfer.

docker save -o myapp.tar myapp:v1.0

docker save myapp:v1.0 | gzip > myapp.tar.gz

Import an image from a tar archive created by `docker save`.

⚠ Common pitfall: `load` restores an image; `import` creates a new image from a raw filesystem tar. Different inputs, different commands.

docker load -i myapp.tar

gunzip -c myapp.tar.gz | docker load

Show the layer-by-layer construction of an image — every command, size, and timestamp.

docker history nginx

docker history --no-trunc myapp:v1.0

Scan an image for known CVE vulnerabilities (replaces the deprecated `docker scan`).

⚠ Common pitfall: `docker scan` (Snyk-based) is deprecated since Docker Desktop 4.27. Use `docker scout` for new projects.

docker scout cves myapp:latest

docker scout quickview myapp:latest

Remove all dangling images (images with no tag, usually leftovers from rebuilds).

⚠ Common pitfall: `-a` removes EVERY unused image, not just dangling ones — can blow away images you still want.

docker image prune

docker image prune -a

docker image prune -a --filter "until=168h"

Print low-level JSON metadata for an image: layers, env vars, entrypoint, exposed ports, labels.

docker inspect nginx

docker inspect --format "{{.Config.Env}}" myapp

Create a brand-new image from a raw filesystem tarball (e.g. from `docker export`). No layers, no history.

⚠ Common pitfall: `import` takes a filesystem tar and flattens it; `load` takes a `docker save` archive and keeps layers. They are not interchangeable.

docker import rootfs.tar myrootfs:base

docker export web | docker import - web-snapshot:v1

List images including their content-addressable digest (sha256), not just the human tag.

⚠ Common pitfall: A tag can be re-pushed to point at new content; the digest never changes. Pin `image@sha256:…` in prod for true immutability.

docker image ls --digests

docker pull nginx@sha256:abc123...

Inspect a multi-arch manifest list to see which platforms (amd64, arm64, …) a tag actually provides.

⚠ Common pitfall: This is an experimental CLI feature; on older Docker you must set `experimental: enabled` in ~/.docker/config.json first.

docker manifest inspect nginx:latest

docker buildx imagetools inspect nginx:latest

Pull every tag available in a repository at once.

⚠ Common pitfall: A busy repo can have hundreds of tags and tens of GB. Rarely what you want; pin a single tag instead.

docker pull -a alpine

Tag an image with the git commit SHA so every build is traceable back to source.

docker tag myapp:latest myapp:$(git rev-parse --short HEAD)

docker tag myapp registry.example.com/team/myapp:$(date +%Y%m%d)

Suggest a more secure / smaller base image and tag upgrades to cut CVE count.

docker scout recommendations myapp:latest

docker scout compare --to myapp:prod myapp:staging

Pull one specific field out of image metadata using a Go template, instead of reading the whole JSON.

docker image inspect --format "{{.Architecture}}" nginx

docker image inspect --format "{{.Size}}" myapp

Create AND start a new container from an image. The most-used docker command.

⚠ Common pitfall: Each `docker run` creates a NEW container. Repeated runs accumulate stopped containers — use `--rm` for one-shots or `docker start <name>` to reuse.

docker run nginx

docker run -d -p 8080:80 nginx

docker run --rm -it ubuntu bash

Run interactively with a TTY. -i keeps STDIN open, -t allocates a pseudo-TTY. Together you get a real shell.

⚠ Common pitfall: Just `-i` gives no prompt; just `-t` cannot receive input. Use `-it` together. Drop `-t` when piping (e.g. `echo x | docker run -i …`).

docker run -it ubuntu bash

docker run -it --rm alpine sh

docker run -it node:20 node

Run a container detached (in the background) and print only the container ID.

docker run -d nginx

docker run -d --name web -p 80:80 nginx

Auto-remove the container on exit. Perfect for one-shot commands so the host does not pile up dead containers.

⚠ Common pitfall: `--rm` runs at container EXIT — it does not remove the image. And data in non-mounted dirs is gone on exit.

docker run --rm alpine echo hello

docker run --rm -v $(pwd):/work -w /work node:20 npm test

Publish a container port to the host. Format: HOST:CONTAINER.

⚠ Common pitfall: The host port comes FIRST, the container port second. Swapping them gives a confusing "no app listening" error.

docker run -p 8080:80 nginx

docker run -p 127.0.0.1:5432:5432 postgres

docker run -P nginx

Mount a host path or named volume into the container at the given path.

⚠ Common pitfall: Bind-mounts on macOS/Windows are SLOW (file syncing through VM). Use named volumes for hot paths like node_modules.

docker run -v $(pwd):/app node:20

docker run -v mydata:/var/lib/mysql mysql

docker run -v $(pwd):/app:ro alpine

Give the container a human-readable name instead of the auto-generated funny-adjective-funny-noun.

⚠ Common pitfall: Names must be unique. Re-running with the same name fails until you `docker rm` the old one.

docker run --name web -d nginx

docker run --name pg -e POSTGRES_PASSWORD=secret -d postgres

Pass an environment variable into the container.

⚠ Common pitfall: Long secret strings on the CLI leak into shell history. Use `--env-file .env` or a secret manager.

docker run -e NODE_ENV=production node:20

docker run --env-file .env myapp

docker run -e DEBUG=1 -e LOG_LEVEL=info myapp

Restart policy: container restarts on crash and on daemon restart, but stays stopped if you `docker stop` it.

⚠ Common pitfall: `--restart=always` will resurrect a container even after `docker stop` once the daemon restarts. `unless-stopped` is almost always what you want.

docker run -d --restart unless-stopped --name web nginx

docker run -d --restart on-failure:5 myapp

List running containers. Add -a to include stopped ones.

docker ps

docker ps -a

docker ps --filter "status=exited"

docker ps --format "table {{.Names}}\t{{.Status}}"

Start one or more stopped containers (preserves all data + config from when you ran them).

docker start web

docker start -a web

docker start $(docker ps -aq -f "status=exited")

Gracefully stop a running container (SIGTERM, then SIGKILL after 10s).

⚠ Common pitfall: Apps that ignore SIGTERM (e.g. shell-wrapped node, sh -c "node app.js") get killed instead of stopped cleanly. Use `exec` form in Dockerfile CMD.

docker stop web

docker stop -t 30 web

docker stop $(docker ps -q)

Stop then start a container — sometimes the fastest fix for a wedged process.

docker restart web

docker restart -t 5 web

Remove one or more stopped containers. Use -f to force-remove running ones.

⚠ Common pitfall: Same as image: `rm` is for CONTAINERS, `rmi` is for IMAGES. Volumes mounted into the container are NOT removed; add -v for that.

docker rm web

docker rm -f web

docker rm -v old-db

docker rm $(docker ps -aq)

Run a one-off command inside a running container — typically a shell to poke around.

⚠ Common pitfall: The container must already be RUNNING. To run a command in a stopped container, use `docker start` first or `docker run` a fresh one.

docker exec -it web bash

docker exec -it web sh

docker exec web ls /etc

docker exec -u 0 -it web bash

Print the container's STDOUT + STDERR (whatever your app wrote, not files on disk).

⚠ Common pitfall: If your app writes to /var/log/app.log instead of stdout, `docker logs` is empty. Make 12-factor apps log to stdout.

docker logs web

docker logs -f web

docker logs --tail 100 web

docker logs --since 10m web

Attach your terminal to the main process of a running container. Ctrl-C will kill the container.

⚠ Common pitfall: `attach` is NOT a shell — it joins the existing process. Use `docker exec -it … bash` instead unless you really need the main TTY.

docker attach web

docker attach --detach-keys="ctrl-p,ctrl-q" web

Copy files between the host and a container. Either side can be the container.

docker cp web:/etc/nginx/nginx.conf ./nginx.conf

docker cp ./fix.patch web:/tmp/

docker cp web:/var/log/. ./logs/

Print all low-level config + state JSON for the container: IP, mounts, env, network, exit code.

docker inspect web

docker inspect --format "{{.State.Status}}" web

docker inspect --format "{{.NetworkSettings.IPAddress}}" web

Live stream of CPU, memory, network and disk IO for running containers.

docker stats

docker stats --no-stream

docker stats web db

Show the processes running INSIDE a container (similar to host `ps`).

docker top web

docker top web aux

Send SIGKILL (or any signal with -s) immediately to the container's main process.

⚠ Common pitfall: SIGKILL gives the app no chance to clean up — half-written files, unflushed DB writes. Prefer `docker stop` unless the process is wedged.

docker kill web

docker kill -s SIGHUP web

Rename an existing container.

docker rename web web-old

docker rename happy_elephant payment-service

Freeze all processes in the container using cgroup freezer (they are still in memory).

⚠ Common pitfall: Paused containers still hold their ports + memory. For testing only — not a real "low-resource standby" mode.

docker pause web

docker unpause web

Resume a paused container.

docker unpause web

Snapshot a running container's filesystem into a new image. Useful for debugging, NOT for prod builds.

⚠ Common pitfall: `commit` images are opaque — no Dockerfile, no reproducibility. Always prefer a Dockerfile for anything you ship.

docker commit web debug-snapshot:v1

docker commit -m "added trace" -a "lei" web debug:v2

Show every file added (A), changed (C), or deleted (D) in the container vs its base image.

docker diff web

Block until the container exits, then print its exit code.

docker wait batch-job

EXIT=$(docker wait batch-job) && echo "Job finished: $EXIT"

List the public-facing port mappings for the container.

docker port web

docker port web 80

Set the working directory inside the container for the command and any later `exec`.

docker run -w /app -v $(pwd):/app node:20 npm test

docker run -w /src --rm gcc:13 gcc main.c

Run the container process as a specific user/group instead of root.

⚠ Common pitfall: Files written to a bind-mount land on the host owned by this UID. Use `$(id -u):$(id -g)` so they match your host user.

docker run -u 1000:1000 -v $(pwd):/app node:20

docker run -u $(id -u):$(id -g) --rm -v $(pwd):/work alpine touch /work/x

Cap the container’s memory. The kernel OOM-kills the container if it exceeds the limit.

⚠ Common pitfall: Without `--memory-swap` set equal to `--memory`, the container can still use host swap. Set both to truly cap RAM.

docker run -m 512m myapp

docker run --memory 1g --memory-swap 1g myapp

Limit how many CPU cores the container may use (fractional values allowed).

docker run --cpus 1.5 myapp

docker run --cpus 0.5 --cpu-shares 512 myapp

Mount the container’s root filesystem read-only. A strong hardening default for stateless services.

⚠ Common pitfall: Apps that write temp files break. Add `--tmpfs /tmp` (and any other writable path) so they have somewhere to scribble.

docker run --read-only --tmpfs /tmp nginx

docker run --read-only -v logs:/var/log myapp

Drop all Linux capabilities, then add back only the ones the app truly needs with --cap-add.

⚠ Common pitfall: Containers run with a default cap set that includes more than most apps need. Drop-all-then-add is least-privilege done right.

docker run --cap-drop ALL --cap-add NET_BIND_SERVICE nginx

docker run --cap-drop ALL alpine id

Prevent the container process from gaining new privileges via setuid binaries.

docker run --security-opt no-new-privileges:true myapp

Attach a healthcheck so `docker ps` shows healthy/unhealthy and orchestrators can act on it.

⚠ Common pitfall: A healthcheck that just pings localhost can report "healthy" while the app is broken upstream. Probe a real endpoint.

docker run --health-cmd "curl -f http://localhost/ || exit 1" --health-interval 30s nginx

Expose host NVIDIA GPUs to the container (needs the NVIDIA Container Toolkit installed).

⚠ Common pitfall: `--gpus` needs the nvidia-container-toolkit on the host; without it you get "could not select device driver".

docker run --gpus all nvidia/cuda:12.4.1-base nvidia-smi

docker run --gpus "device=0,1" myapp

Add a custom /etc/hosts entry inside the container.

docker run --add-host db.local:10.0.0.5 myapp

docker run --add-host host.docker.internal:host-gateway myapp

Change resource limits (CPU, memory, restart policy) on a running container without recreating it.

⚠ Common pitfall: Most settings update live, but some (like `--restart`) only take effect on the next start. Port and volume mounts cannot be changed at all.

docker update --memory 1g web

docker update --restart unless-stopped web

docker update --cpus 2 web

Run a command inside a running container with extra environment variables for that command only.

docker exec -e DEBUG=1 -it web node debug.js

docker exec -e PGPASSWORD=secret db psql -U app

Prefix each log line with an RFC3339 timestamp from the daemon.

docker logs -t web

docker logs -t --since 2026-01-01T00:00:00 web

Run a tiny init (tini) as PID 1 to reap zombie processes and forward signals correctly.

⚠ Common pitfall: If your app spawns children and does not reap them, zombies pile up. `--init` fixes this without changing your image.

docker run --init myapp

docker run --init -d --name worker myapp

List all docker networks. You always get bridge, host, and none by default.

docker network ls

docker network ls --filter "driver=bridge"

Create a user-defined bridge network. Containers on the same user network can resolve each other by name.

⚠ Common pitfall: Default `bridge` network does NOT have DNS-based service discovery — containers cannot ping each other by name. Always create a user network.

docker network create app-net

docker network create --driver bridge app-net

docker network create --subnet 172.20.0.0/16 app-net

Show network details: subnet, gateway, attached containers, options.

docker network inspect bridge

docker network inspect app-net

Attach a running container to an additional network (containers can be on multiple networks).

docker network connect app-net web

docker network connect --alias api app-net web

Detach a container from a network without stopping it.

docker network disconnect app-net web

docker network disconnect -f app-net web

Remove one or more empty user-defined networks.

⚠ Common pitfall: Networks with attached containers cannot be removed — disconnect them first or remove the containers.

docker network rm app-net

docker network prune

Start a container directly on a specific network.

docker run -d --network app-net --name web nginx

docker run --network host nginx

Create a network with no external connectivity; containers can talk to each other but not the internet.

⚠ Common pitfall: Great for a DB tier that should never reach out. But the DB also cannot pull updates or call webhooks from here.

docker network create --internal backend

docker run --network backend --name db postgres

Share the host’s network stack directly; the container has no isolated network namespace.

⚠ Common pitfall: On macOS/Windows `--network host` does NOT reach host ports the way Linux does — Docker runs in a VM. Mostly a Linux-only trick.

docker run --network host nginx

docker run --network host -d prom/prometheus

Override the DNS server the container uses for name resolution.

docker run --dns 1.1.1.1 alpine nslookup example.com

docker run --dns 8.8.8.8 --dns-search corp.local myapp

Create an overlay/bridge network that standalone containers can also attach to (not just swarm services).

docker network create --driver overlay --attachable mesh

docker network connect mesh standalone-tool

Give the container no network at all — only a loopback interface. Maximum isolation for untrusted code.

docker run --network none --rm untrusted-job

docker run --network none alpine ip addr

List all docker-managed volumes.

docker volume ls

docker volume ls --filter "dangling=true"

Create a named volume. Persists data outside the container lifecycle.

docker volume create pgdata

docker volume create --driver local --opt type=tmpfs fastdata

Show volume metadata: driver, mountpoint on host, labels.

docker volume inspect pgdata

Delete one or more volumes. Fails if a container still uses them.

⚠ Common pitfall: Deleting a volume is IRREVERSIBLE — your DB data is gone. Always back up before pruning shared volumes.

docker volume rm pgdata

docker volume rm $(docker volume ls -q -f "dangling=true")

Remove every volume not currently in use by any container.

⚠ Common pitfall: A stopped container counts as "in use". A volume only used by a deleted container counts as "unused" and will be pruned.

docker volume prune

docker volume prune -a -f

The explicit, verbose alternative to -v. Each option is a key=value pair, harder to typo silently.

⚠ Common pitfall: With `-v`, a typo in the source path silently creates a NEW empty volume. `--mount` errors out instead — safer for prod.

docker run --mount type=volume,source=pgdata,target=/var/lib/postgresql/data postgres

docker run --mount type=bind,source=$(pwd),target=/app,readonly node:20

Mount an in-memory tmpfs into the container; data is fast and vanishes on stop. Good for secrets/scratch.

docker run --mount type=tmpfs,target=/tmp,tmpfs-size=64m myapp

docker run --tmpfs /run:rw,size=16m nginx

Create a volume backed by an NFS share via the local driver options.

docker volume create --driver local --opt type=nfs --opt o=addr=10.0.0.5,rw --opt device=:/exports/data nfsdata

Back up a named volume by running a throwaway container that tars its contents to the host.

⚠ Common pitfall: There is no `docker volume backup` command. The tar-through-a-container pattern is the standard idiom.

docker run --rm -v pgdata:/data -v $(pwd):/backup alpine tar czf /backup/pgdata.tar.gz -C /data .

docker run --rm -v pgdata:/data -v $(pwd):/backup alpine tar xzf /backup/pgdata.tar.gz -C /data

Show disk usage for images, containers, volumes, and build cache (the `du` of docker).

docker system df

docker system df -v

Remove stopped containers, dangling images, unused networks, and build cache in one shot.

⚠ Common pitfall: `-a --volumes` ALSO removes unused images + volumes. People run this and lose database data. Read the prompt before confirming.

docker system prune

docker system prune -a

docker system prune -a --volumes

Print daemon-wide info: total containers/images, storage driver, kernel, OS, registry mirrors.

docker info

docker info --format "{{.ServerVersion}}"

Show client + server version, API version, Go version, git commit.

docker version

docker version --format "{{.Server.Version}}"

Live stream of daemon events: container start/stop, image pull, network create. Great for debugging.

docker events

docker events --filter "type=container"

docker events --since 1h --until 5m

Authenticate to a registry. Credentials get cached in ~/.docker/config.json.

⚠ Common pitfall: On shared machines, config.json may store creds in plaintext. Use `docker-credential-helpers` (osxkeychain / pass) for real protection.

docker login

docker login ghcr.io

echo $TOKEN | docker login -u user --password-stdin ghcr.io

Remove cached registry credentials.

docker logout

docker logout ghcr.io

List docker contexts (local socket, remote SSH host, Desktop). Switch which daemon the CLI talks to.

⚠ Common pitfall: Running commands against the wrong context (e.g. prod instead of local) is a classic foot-gun. Check `docker context show` first.

docker context ls

docker context use my-remote

docker context create remote --docker "host=ssh://user@host"

Reclaim disk used specifically by the BuildKit build cache, leaving images and containers untouched.

⚠ Common pitfall: `docker system df` often shows build cache as the single biggest consumer. Prune it here without nuking images.

docker builder prune

docker builder prune -af --filter "until=72h"

Stream container stats as a custom one-line format instead of the full live table.

docker stats --no-stream --format "{{.Name}}: {{.MemUsage}}"

docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemPerc}}"

Use Go templates to extract exactly the fields you want from any object’s inspect JSON.

⚠ Common pitfall: Inside `--format` use `{{json .Field}}` to dump a sub-object as JSON, and `{{index .Map "key"}}` to read a map by key.

docker inspect --format "{{json .Mounts}}" web

docker inspect --format "{{index .Config.Labels \"version\"}}" web

Subscribe to a filtered live event stream — e.g. only container die events — for alerting or audit.

docker events --filter "event=die"

docker events --filter "image=nginx" --filter "event=start"

Quickly check the storage driver, cgroup version, or default runtime without scrolling all of `docker info`.

docker info --format "{{.Driver}}"

docker info --format "{{.CgroupVersion}}"

Create + start all services defined in compose.yaml. Add -d for background.

⚠ Common pitfall: `docker-compose` (with dash) is V1 and deprecated. Use `docker compose` (space) which is the V2 plugin built into modern Docker.

docker compose up

docker compose up -d

docker compose up --build

docker compose up web db

Stop AND remove all containers, networks, default network. Add -v to also remove named volumes.

⚠ Common pitfall: `down -v` wipes DATA volumes. People do this in dev then run the same command in staging and lose user data. Treat -v as destructive.

docker compose down

docker compose down -v

docker compose down --rmi all

List containers managed by this compose project (with health + ports).

docker compose ps

docker compose ps --status running

Tail aggregated logs from all services. -f follows, --tail limits per-service.

docker compose logs

docker compose logs -f web

docker compose logs --tail=50 -f

Build (or rebuild) all services that have a build: block in compose.yaml.

⚠ Common pitfall: `docker compose up` does NOT rebuild on Dockerfile changes by default. Pair with `--build` or run `build` first.

docker compose build

docker compose build --no-cache web

docker compose build --pull

Restart all (or named) services without recreating containers.

docker compose restart

docker compose restart web

Run a command in an already-running compose service (vs `run` which starts a new container).

docker compose exec web bash

docker compose exec db psql -U postgres

docker compose exec -T db pg_dump mydb > backup.sql

Start a NEW one-off container for a service to run a command. Networks attached, volumes mounted, but no port publishing by default.

⚠ Common pitfall: `compose run` does NOT publish ports defined in compose.yaml — pass --service-ports if you need them.

docker compose run --rm web npm test

docker compose run --rm --service-ports web bash

Pull the latest images for all services with an image: block.

docker compose pull

docker compose pull web db

Parse + validate compose.yaml and print the merged, resolved config. Great for debugging env var interpolation.

docker compose config

docker compose config --services

docker compose -f compose.yaml -f compose.prod.yaml config

Stop services without removing containers. `start` brings them back later.

docker compose stop

docker compose stop web

Start services detached and block until they all report healthy (or fail). Ideal for CI.

⚠ Common pitfall: `--wait` only works if your services define a healthcheck. Without one, compose considers "started" = "ready", which it often is not.

docker compose up -d --wait

docker compose up -d --wait --wait-timeout 60

Start only services tagged with a given profile. Lets one compose file hold dev-only / debug-only services.

docker compose --profile debug up

docker compose --profile prod up -d

Control when compose pulls images. `missing` pulls only images you do not have locally.

docker compose pull --policy missing

docker compose up --pull never

Watch source files and auto-sync/rebuild services per the `develop.watch` block in compose.yaml.

⚠ Common pitfall: `watch` needs a `develop:` section in your service; it is not on by default. It is the compose-native hot-reload, no bind mount needed.

docker compose watch

docker compose up --watch

Set the compose project name explicitly, isolating container/network/volume names from other stacks.

⚠ Common pitfall: Default project name = the folder name. Two clones in same-named folders collide. Set `-p` (or COMPOSE_PROJECT_NAME) per stack.

docker compose -p staging up -d

COMPOSE_PROJECT_NAME=ci docker compose up

Copy files between a compose service container and the host (the compose-aware `docker cp`).

docker compose cp db:/var/lib/postgresql/data/pg_hba.conf ./

docker compose cp ./seed.sql db:/tmp/

Show the running processes inside each service’s containers, grouped by service.

docker compose top

docker compose top web

Enable BuildKit — the modern build engine with parallel layers, cache mounts, secrets, much faster builds.

⚠ Common pitfall: BuildKit is default since Docker Engine 23.0. On older daemons you must set DOCKER_BUILDKIT=1 each time or in daemon.json.

DOCKER_BUILDKIT=1 docker build -t myapp .

docker buildx build -t myapp .

In a multi-stage Dockerfile, build only up to the named stage. Useful for dev images that stop at the `builder` stage.

docker build --target builder -t myapp:dev .

docker build --target prod -t myapp:prod .

Build for a specific target platform. Supports cross-arch (linux/arm64 from amd64 host) via emulation.

⚠ Common pitfall: Building cross-arch via QEMU emulation is 5-20x slower than native. Use `docker buildx` + remote ARM builder for production multi-arch.

docker build --platform linux/amd64 -t myapp .

docker buildx build --platform linux/amd64,linux/arm64 -t myorg/myapp --push .

Pass a build-time variable matching an ARG in the Dockerfile.

⚠ Common pitfall: ARG values end up in `docker history` — do NOT pass secrets this way. Use BuildKit `--secret` instead.

docker build --build-arg NODE_VERSION=20 -t myapp .

docker build --build-arg GIT_SHA=$(git rev-parse HEAD) -t myapp .

Pass a secret into the build that does NOT end up in the final image or `docker history`.

docker buildx build --secret id=npmrc,src=$HOME/.npmrc -t myapp .

RUN --mount=type=secret,id=npmrc cp /run/secrets/npmrc ./

Reuse build cache from a remote image (great for CI where the local cache is empty).

docker buildx build --cache-from type=registry,ref=myorg/myapp:cache --cache-to type=registry,ref=myorg/myapp:cache,mode=max -t myorg/myapp:v1 --push .

Tell docker which paths to EXCLUDE from the build context. Same syntax as .gitignore.

⚠ Common pitfall: Without `.dockerignore`, docker uploads node_modules, .git, dist, .env to the daemon — slow builds and accidental secret leaks in layers.

echo "node_modules\n.git\ndist\n.env*" > .dockerignore

Use multiple FROM blocks to build in one stage (with toolchain) and copy only artifacts into a tiny runtime image.

⚠ Common pitfall: Without multi-stage, your prod image includes gcc, npm, source code, tests — easily 1GB+. With multi-stage, the same app fits in 50MB.

FROM node:20 AS builder\nWORKDIR /app\nCOPY . .\nRUN npm ci && npm run build\n\nFROM nginx:alpine\nCOPY --from=builder /app/dist /usr/share/nginx/html

Extended build command (BuildKit). Multi-platform, cache backends, output to registry/tar/oci, all in one.

docker buildx create --use --name multi

docker buildx build --platform linux/amd64,linux/arm64 -t myorg/app --push .

docker buildx ls

BuildKit cache mount: persist package-manager caches across builds without baking them into a layer.

⚠ Common pitfall: A cache mount survives between builds but never ships in the image — perfect for ~/.npm, /root/.cache/pip, go mod cache.

RUN --mount=type=cache,target=/root/.npm npm ci

RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt

Build a whole group of targets from a docker-bake.hcl / compose file in one parallel, declarative run.

docker buildx bake

docker buildx bake --push web api

docker buildx bake -f docker-bake.hcl --set "*.platform=linux/amd64,linux/arm64"

Export build artifacts straight to the host filesystem instead of producing a container image.

⚠ Common pitfall: With `--output type=local,dest=./out` the final stage’s filesystem lands on disk — handy for building static binaries or sites.

docker buildx build --output type=local,dest=./dist .

docker buildx build -o type=tar,dest=out.tar .

Print full, non-collapsed build logs (every RUN line) instead of the tidy TTY view. Essential for CI debugging.

docker build --progress=plain --no-cache -t myapp .

BUILDKIT_PROGRESS=plain docker build -t myapp .

Bake a healthcheck into the image so every container from it reports health automatically.

⚠ Common pitfall: A Dockerfile `HEALTHCHECK` is inherited by all containers; a `docker run --health-cmd` only applies to that one run and overrides it.

HEALTHCHECK --interval=30s --timeout=3s CMD curl -f http://localhost/ || exit 1

HEALTHCHECK NONE  # disable an inherited check

ENTRYPOINT sets the fixed executable; CMD sets default args. Together they make a configurable container command.

⚠ Common pitfall: Use the exec form `["nginx","-g","daemon off;"]`, not shell form. Shell form wraps in /bin/sh -c and swallows SIGTERM.

ENTRYPOINT ["python", "app.py"]\nCMD ["--port", "8080"]

docker run myapp --port 9090  # overrides CMD, keeps ENTRYPOINT

Set ownership and permissions of copied files in one step, avoiding an extra RUN chown layer.

COPY --chown=node:node . /app

COPY --chmod=755 entrypoint.sh /usr/local/bin/

Copy files from another image (not just an earlier build stage) into the current stage.

COPY --from=golang:1.22 /usr/local/go/bin/go /usr/local/bin/go

COPY --from=builder /app/dist /usr/share/nginx/html

Daemon is not running, or your user is not in the docker group. On Linux: `sudo systemctl start docker` then `sudo usermod -aG docker $USER` and re-login.

⚠ Common pitfall: On macOS/Windows the daemon is Docker Desktop — open the app. WSL2 needs Docker Desktop's WSL integration enabled per distro.

sudo systemctl start docker

sudo systemctl status docker

docker context ls

Your user is not in the `docker` group. Add yourself and re-login (group membership is loaded at login).

⚠ Common pitfall: `sudo docker` works but every command needing sudo defeats the purpose. Group membership only takes effect on a fresh login (or `newgrp docker`).

sudo usermod -aG docker $USER

newgrp docker

docker ps

Switch to a slim base (alpine / distroless), use multi-stage, run `npm ci --omit=dev`, and put your COPY of large dirs LAST so cache works.

⚠ Common pitfall: Each RUN creates a layer — `RUN apt update && apt install -y x && rm -rf /var/lib/apt/lists/*` in ONE line is much smaller than three separate RUNs.

FROM node:20-alpine

FROM gcr.io/distroless/nodejs20

docker history --no-trunc myapp:latest

137 = 128 + SIGKILL(9). The kernel OOM killer reaped your container. Either bump --memory or fix the leak.

⚠ Common pitfall: On Docker Desktop the VM has its own memory cap (default 2GB on older versions, 8GB on newer). Bump it in Settings > Resources.

docker run -m 1g myapp

docker inspect --format "{{.State.OOMKilled}}" web

docker stats --no-stream web

125 = docker itself errored; 126 = command found but not executable; 127 = command not found in the container.

⚠ Common pitfall: Code 127 hits hard with alpine — many distros have `bash` but alpine ships only `sh`. Use `sh` in exec/run or install bash.

docker run --rm alpine sh -c "echo hi"

docker run --rm alpine bash  # exit 127

docker run --rm alpine apk add --no-cache bash

Docker fills /var/lib/docker. Run `docker system prune` first, then `docker system df` to see what is left.

⚠ Common pitfall: On Docker Desktop the disk is a sparse VM file — pruning frees logical space but the .raw file does not shrink automatically. Reset disk image as last resort.

docker system df

docker system prune -a --volumes

sudo du -sh /var/lib/docker

Another process (often a previous container) holds the host port. Find it: `lsof -i :<port>` or `docker ps -a` then stop/remove.

docker ps -a --filter "publish=8080"

lsof -i :8080

docker rm -f $(docker ps -aq -f "publish=8080")

The tag does not exist in the registry. Check the spelling, verify with `docker buildx imagetools inspect <image>` or browse the registry UI.

⚠ Common pitfall: For private registries this can also mean you are not authenticated — `docker login` first. ARM users hitting amd64-only images get this too.

docker buildx imagetools inspect ghcr.io/user/app:v1

docker login ghcr.io

docker pull --platform linux/amd64 myimg

All three speak the same CLI. Desktop is the official GUI bundle (paid for big orgs). Podman is daemonless and rootless by default. nerdctl ships with containerd.

⚠ Common pitfall: Podman aliases `docker` to `podman` — handy until something assumes a docker socket at /var/run/docker.sock. Either start `podman system service` or keep real docker.

alias docker=podman

podman system service --time=0 unix:///tmp/podman.sock &

nerdctl run hello-world

You are running an image built for a different CPU architecture (e.g. arm64 image on amd64 host).

⚠ Common pitfall: Common on Apple Silicon pulling amd64-only images, or CI on amd64 running an arm64 build. Add `--platform` or build multi-arch.

docker run --platform linux/amd64 myimg

docker buildx build --platform linux/amd64,linux/arm64 -t myorg/app --push .

The path in COPY is outside the build context, or excluded by .dockerignore.

⚠ Common pitfall: COPY paths are relative to the build context root (the last arg of `docker build`), not to the Dockerfile’s folder. You cannot COPY ../something.

docker build -f docker/Dockerfile .   # context is "."

cat .dockerignore   # check nothing excludes the file

The container’s writable layer is ephemeral. Without a volume, anything written there is lost on rm/recreate.

⚠ Common pitfall: `docker stop`+`docker start` keeps the writable layer; `docker rm`+`docker run` does NOT. For data that must survive, use a volume.

docker run -v pgdata:/var/lib/postgresql/data postgres

docker inspect --format "{{.Mounts}}" db

Inside a container, `localhost` is the container itself, not the host machine or another container.

⚠ Common pitfall: To reach the host from a container use `host.docker.internal` (Desktop) or `--add-host host.docker.internal:host-gateway` (Linux). To reach another container, use its service/container name on a shared network.

docker run --add-host host.docker.internal:host-gateway myapp

curl http://host.docker.internal:5432

BuildKit cannot find the Dockerfile — wrong -f path, or no Dockerfile in the context.

⚠ Common pitfall: The default filename is `Dockerfile` (capital D). On case-sensitive filesystems `dockerfile` will not be found without `-f`.

docker build -f path/to/Dockerfile .

ls -la Dockerfile

Pulling from a registry with a self-signed or untrusted cert. The daemon refuses the TLS handshake.

⚠ Common pitfall: For a private registry, add it under `insecure-registries` in daemon.json (dev only), or install its CA into the host trust store (prod).

/etc/docker/daemon.json: {"insecure-registries":["registry.local:5000"]}

sudo cp registry-ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates

A huge build context (gigabytes) is being uploaded to the daemon before the build even starts.

⚠ Common pitfall: Almost always a missing or weak .dockerignore. Check the "transferring context" size in build output, then exclude node_modules/.git/dist.

printf "node_modules\n.git\ndist\n*.log\n" > .dockerignore

du -sh . --exclude=node_modules

The container is still inside its `start-period` window, so an early failing check is not counted yet.

⚠ Common pitfall: If it never leaves "starting", your `--health-cmd` is failing every time. Run the command manually with `docker exec` to see why.

docker inspect --format "{{json .State.Health}}" web

docker exec web sh -c "curl -f http://localhost/ || echo FAIL"