The difference between RUN and CMD with Docker

When you write your first Dockerfile, the RUN and CMD instructions are often a source of confusion.

They may seem similar… but they play completely different roles.

Note that if you don't know Docker, this article won't be very useful to you, but you can always go listen to our introduction to Docker in a dedicated podcast episode!

The RUN command

RUN is used when building the Docker image.

For example:

RUN apt-get update && apt-get install -y curl

This command is executed:

• during docker build
• to modify the image

RUN is used to prepare the image.

Each RUN instruction creates a new layer in the Docker image.

Typically, you use RUN to:

• install dependencies
• copy or generate files
• configure the environment

The CMD command

CMD is used when launching the container.

For example:

CMD ["node", "server.js"]

This command is executed:

• when you run docker run
• at container startup

CMD is used to say: "this is what this container does when it starts".

The key difference

The main difference can be summed up in one sentence: RUN executes during the build while CMD executes at runtime.

In other words:

• RUN modifies the image
• CMD defines the container's behavior

A concrete example

Let's take a simple Dockerfile:

FROM node:18
WORKDIR /app
COPY package.json .
RUN npm install
COPY . .

CMD ["node", "index.js"]

What happens:

1. RUN npm install installs the dependencies into the image
2. CMD ["node", "index.js"] launches the application at startup

Without CMD, the container wouldn't do anything.

To go further

CMD can be overridden

For example:

docker run mon-image echo "Hello"

Here:

• CMD is ignored
• the echo "Hello" command is executed

CMD is a default value.

The layer system

Each RUN adds a layer to your image.

For example:

RUN apt-get update
RUN apt-get install -y curl

Creates two layers.

The different layers are used by Docker to optimize the memory used by images, because similar layers are shared between different containers!

Article summary

RUN and CMD are complementary.

• use RUN to build your environment (executed during the build)
• use CMD to launch your application (executed at runtime)

If you confuse them, your container will probably not do what you expect.