Dockerfile CMD reference

Exec form vs shell form

The two forms follow the same rules as for ENTRYPOINT:

• Exec form CMD ["node", "server.js"] is a JSON array. Use double quotes; with single quotes the line is not valid JSON and Docker falls back to the shell form. No shell runs, so $VAR is not expanded, and the program is PID 1 and receives SIGTERM from docker stop.
• Shell form CMD node server.js runs as /bin/sh -c "node server.js". Variables are expanded, but the shell is PID 1 and may not forward signals, so the container can take the full stop timeout to shut down.

To expand variables in exec form, invoke the shell explicitly and exec the program:

CMD ["sh", "-c", "exec gunicorn --bind 0.0.0.0:\"$PORT\" app:app"]

Both forms can be overridden at run time in exactly the same way.

Overriding CMD at run time

Arguments after the image name replace the entire CMD. They are not appended to it or merged with it:

FROM python:3.12-slim
WORKDIR /app
COPY . .
CMD ["python", "app.py"]

docker run --rm myapp
# runs: python app.py

docker run --rm myapp python manage.py migrate
# runs: python manage.py migrate

docker run --rm -it myapp bash
# runs: bash (interactive shell instead of the app)

Other places that override CMD:

CMD is also inherited: if your Dockerfile has none, the base image's CMD is used. That is why FROM python:3.12-slim with no CMD starts a Python REPL.

CMD with ENTRYPOINT

When an image also has an ENTRYPOINT, CMD stops being the command and becomes the default arguments to it. Run-time arguments then replace only those defaults, not the executable:

ENTRYPOINT ["nginx"]
CMD ["-g", "daemon off;"]

docker run myimage runs nginx -g "daemon off;"; docker run myimage -t runs nginx -t.

The resulting command for each combination of forms:

• A shell-form ENTRYPOINT ignores CMD completely.
• A shell-form CMD under an exec-form ENTRYPOINT passes /bin/sh -c … as literal arguments. Use the exec form for both.
• Setting ENTRYPOINT in your Dockerfile resets the CMD inherited from the base image. Write CMD after it if you want defaults.

Signal handling, --entrypoint, and entrypoint scripts that end in exec "$@" are covered in the ENTRYPOINT reference.

CMD vs RUN vs HEALTHCHECK CMD

• RUN executes during docker build and commits the result as an image layer (installing packages, compiling code).
• CMD executes nothing at build time. It only sets metadata for the container's default process.
• HEALTHCHECK CMD uses CMD as a keyword to introduce a probe command, for example HEALTHCHECK CMD curl -f http://localhost/ || exit 1. The probe runs periodically inside the running container alongside the main process; it does not replace the image's CMD.

Examples

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
USER node
CMD ["node", "server.js"]

FROM alpine:3.20
ENTRYPOINT ["ping", "-c", "3"]
CMD ["localhost"]

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y --no-install-recommends curl jq \
 && rm -rf /var/lib/apt/lists/*
CMD ["bash"]

Notes

• Only the last CMD takes effect. To start several processes, make the single command a script or a process manager.
• CMD does not add a filesystem layer; it only changes image metadata.
• Build-time ENV and ARG substitution does not apply to CMD; variables are only expanded at run time, and only by a shell.
• Inspect the effective value with docker image inspect --format '{{json .Config.Cmd}}' myimage.