What Is the Difference between RUN and CMD in a Dockerfile?

RUNCopy and CMDCopy look alike because both take a command, but they fire at completely different moments in a container's life. RUNCopy executes while you build the image and commits its result into a new layer. CMDCopy runs nothing at build time; it only records the default command that executes when someone starts a container from the finished image.

That single distinction (build time versus runtime) explains almost every confusing behavior people hit, including why a CMDCopy can vanish without a trace when you pass arguments to docker runCopy, and why RUNCopy instructions keep bloating your image even after you think you've cleaned up. Once that split clicks, the rest of it (layers, the two syntax forms, and how CMDCopy bends around ENTRYPOINTCopy) follows from there.

Build time vs runtime

A Dockerfile describes two separate phases, and RUNCopy and CMDCopy live in different ones.

The build phase turns a Dockerfile into an image. Every RUNCopy instruction executes during this phase, inside a temporary container, and whatever it changes on disk gets saved into the image. By the time the build finishes, all RUNCopy commands have already happened. They will never run again.

The runtime phase starts when you call docker runCopy. This is when CMDCopy matters. The command in CMDCopy is not executed during the build at all; Docker just stores it as metadata in the image. When a container launches, Docker reads that metadata and runs it as the container's main process.

A minimal Dockerfile shows both phases:

123456
FROM python:3.14-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "main.py"]

When you run docker buildCopy, the RUN pip installCopy line executes and the installed packages are written into the image. The CMD ["python", "main.py"]Copy line does nothing yet. Then when you run docker run my-imageCopy, Docker skips straight to executing python main.pyCopy, because the build work is already baked in.

A useful rule of thumb: if a command needs to leave something behind in the image (an installed package, a compiled binary, a created directory), it belongs in RUNCopy. If a command defines what the running container should do, it belongs in CMDCopy.

How RUN affects layering

Each RUNCopy instruction creates a new read-only layer in the image, capturing the filesystem changes that command produced. This is why you can have many RUNCopy instructions stacked on top of each other, and why build caching works: if nothing above a layer has changed, Docker reuses the cached layer instead of re-executing it.

Layers are additive, and that has a consequence people get burned by. If you install something in one RUNCopy and delete it in a later RUNCopy, the deleted files still occupy space in the earlier layer:

123
# This does NOT shrink the image
RUN apt-get update && apt-get install -y build-essential
RUN apt-get purge -y build-essential

The build-essentialCopy packages are gone from the final filesystem view, but they're permanently stored in the layer the first RUNCopy created. To actually keep them out of the image, do the install and cleanup in a single RUNCopy so the deletion happens before the layer is committed:

12345
RUN apt-get update \
    && apt-get install -y --no-install-recommends build-essential \
    && make -C /app \
    && apt-get purge -y build-essential \
    && rm -rf /var/lib/apt/lists/*

CMDCopy does not create a filesystem layer in this sense. It writes a small piece of image configuration. You can have multiple CMDCopy lines in a Dockerfile, but only the last one survives; the earlier ones are silently discarded.

Shell form vs exec form

Both RUNCopy and CMDCopy accept two syntaxes, and the choice changes how the command is executed.

Shell form is a plain string. Docker wraps it in /bin/sh -cCopy, so you get shell features like variable expansion, pipes, and &&Copy:

12
RUN apt-get update && apt-get install -y curl
CMD python main.py

Exec form is a JSON array. Docker runs the executable directly, without a shell:

12
RUN ["/bin/bash", "-c", "apt-get update && apt-get install -y curl"]
CMD ["python", "main.py"]

For RUNCopy, shell form is usually what you want, because build steps lean heavily on shell operators to chain commands together. Note the exec form bypasses the shell entirely, so RUN ["echo", "$HOME"]Copy prints the literal string $HOMECopy rather than expanding the variable.

For CMDCopy, exec form is the better default, and the reason is signal handling. In exec form, your process runs as process ID 1 (PID 1) and receives signals like SIGTERMCopy directly, so docker stopCopy shuts it down cleanly. In shell form, /bin/shCopy becomes PID 1, and many shells don't forward signals to their child process. The result is a container that ignores docker stopCopy and gets force-killed after the timeout. One subtle catch: the exec form is parsed as JSON, so it requires double quotes. Single quotes will break the parse.

How CMD interacts with ENTRYPOINT

CMDCopy changes behavior the moment you add an ENTRYPOINTCopy. On its own, CMDCopy is the full command Docker runs. But when an ENTRYPOINTCopy is present, CMDCopy stops being the command and becomes the default arguments appended to the ENTRYPOINTCopy.

123
FROM alpine
ENTRYPOINT ["ping"]
CMD ["localhost"]

Running docker run my-imageCopy executes ping localhostCopy. The ENTRYPOINTCopy supplies the fixed executable, and CMDCopy supplies the default argument. Override the argument and the ENTRYPOINTCopy stays put:

12
docker run my-image example.com
# runs: ping example.com

Watch the form here, though. When you combine an exec form ENTRYPOINTCopy with CMDCopy, use exec form for the CMDCopy too. If you write CMDCopy in shell form, Docker expands it to /bin/sh -c "your command"Copy, and the ENTRYPOINTCopy receives /bin/shCopy, -cCopy, and your command as three separate trailing arguments instead of the clean parameters you intended. This is one of the most common reasons an ENTRYPOINTCopy-plus-CMDCopy combination behaves strangely, and it's spelled out in the official Dockerfile reference.

Overriding CMD with docker run

Anything you pass after the image name when you start a container with docker runCopy replaces CMDCopy entirely. This is the override behavior that surprises people when their default command seems to disappear.

Given the earlier Python image with CMD ["python", "main.py"]Copy:

1234567891011
# Uses the CMD from the Dockerfile
docker run my-image
# runs: python main.py

# Replaces the CMD completely
docker run my-image python debug.py
# runs: python debug.py

# Also replaces it: you get a shell, not your app
docker run -it my-image bash
# runs: bash

That last example is the gotcha. Running your image with bashCopy tacked on doesn't run your app and then drop you into a shell. It throws away the CMDCopy and runs only bashCopy. This is exactly why dropping into a container to debug it works, and also why people occasionally wonder why their service never started.

RUNCopy has no runtime equivalent to override. Once the image is built, RUNCopy instructions are frozen into layers and there's nothing at runtime to replace.

Common pitfalls

The most common mistake is expecting RUNCopy to do something at startup. People write RUN python main.pyCopy, watch it execute during the build, and then can't figure out why the app never starts in the container. RUNCopy only ever fires at build time, so anything that should happen when the container launches belongs in CMDCopy or ENTRYPOINTCopy.

Stacking multiple CMDCopy instructions causes a quieter version of the same confusion. Only the last CMDCopy in the file takes effect, and Docker won't warn you that the earlier ones were thrown away. If your container keeps running the wrong command, check whether a later CMDCopy is shadowing the one you meant to use.

The signal-handling pitfall is the one that bites in production. A CMDCopy in shell form makes /bin/shCopy your PID 1, and the shell often won't pass SIGTERMCopy down to your application, so graceful shutdown breaks. The usual symptom is docker stopCopy hanging for ten seconds and then force-killing the container. Switch the CMDCopy to exec form and the signal reaches your process directly. For more on the stop and start lifecycle, see how to restart a Docker container.

Final thoughts

The short version: RUNCopy builds the image and CMDCopy runs the container, with CMDCopy quietly turning into default arguments once an ENTRYPOINTCopy enters the picture. Get those two phases straight and most Dockerfile confusion resolves itself.

Once your containers are running, the next question is what's actually happening inside them. A misbehaving container that ignores shutdown signals or restarts in a loop is hard to spot without visibility into its resource usage and logs.

Dash0's infrastructure monitoring tracks container resource usage alongside real-time logs and distributed traces, built on OpenTelemetry so you own your data and avoid lock-in. Start a free trial to see your containers, pods, and clusters in one view. No credit card required.