Table of Contents
Why `docker run` Matters
The docker run command is the main way you start containers from images. Every time you want to turn an image into a running container, you use docker run with different options to control how that container behaves.
Understanding this command is essential because it combines many core ideas at once. It chooses the image, sets the container name, controls networking and ports, passes configuration, and decides what process runs inside the container.
The Basic Structure of `docker run`
At its simplest, the structure of docker run looks like this:
docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
You always have at least an image name. Everything before the image name is an option that affects how Docker runs the container. Everything after the image name can override what the container does inside.
Key structure:
$$\text{docker run } \underbrace{[OPTIONS]}_{\text{how it runs}} \ \underbrace{IMAGE}_{\text{what to run}} \ \underbrace{[COMMAND] [ARG...]}_{\text{what to do inside}}$$
You will frequently see simple examples such as:
docker run hello-world
Here, there are no options and no extra command, only the image name. Docker uses the default behavior defined inside that image.
What Happens When You Use `docker run`
When you execute docker run, Docker performs several steps internally, even if you do not see them.
First, Docker checks whether the image is available locally. If it is not, Docker will automatically try to download it from a registry such as Docker Hub, using the image name and tag.
Second, Docker creates a new container based on that image. This is like creating an instance from a template. The container gets its own isolated filesystem, process space, and networking according to the Docker settings.
Third, Docker starts the main process inside the container. This process comes from the image configuration or from any command you provided after the image name. When this process ends, the container stops.
Finally, Docker keeps a record of the container, including its status. Even after it stops, the container still exists until you remove it explicitly or use an option that removes it automatically.
Image Names and Default Tags
When you write an image name in docker run, you can include a tag to specify a version, for example:
docker run ubuntu:22.04
If you omit the tag, Docker assumes the tag latest by default:
docker run ubuntu
is the same as:
docker run ubuntu:latest
If no tag is specified in docker run IMAGE, Docker uses :latest as the default tag.
This automatic behavior is convenient but can hide which exact version you are using. In real projects, it is common to specify explicit tags to keep behavior predictable.
Commonly Used Options in `docker run`
While docker run supports many options, a few appear very frequently in everyday use.
One important option is --name, which gives the container a human readable name:
docker run --name my-container nginx
If you do not provide a name, Docker generates one for you. Names make it easier to refer to containers in later commands.
Another commonly used option is -d, which runs the container in the background as a detached process. Combined with an image, it looks like this:
docker run -d nginx
There is a strong connection between the options you use here and the ways you start and manage containers later, which will be explored in other chapters. In this chapter, focus on how docker run ties these pieces together.
Commands and Arguments After the Image
The part after the image name in docker run lets you override what the image would normally do. For example, consider:
docker run ubuntu echo "Hello from Docker"
Here, ubuntu is the image, and echo "Hello from Docker" is the command executed inside the container. The container will run that command, print the message, then exit. The container will stay in the stopped state until removed.
You can also pass arguments, for example:
docker run ubuntu ls -l /
In this case, ls is the command, and -l / are its arguments. The image supplies the environment where the command runs, but the actual action comes from what you specify after the image name.
If you do not provide any command, Docker uses the default command defined in the image. That default is what makes docker run nginx or docker run hello-world behave in a particular way without extra parameters.
Exit Codes and Container Status
When the main process inside a container finishes, it exits with an exit code. This is the same idea as exit codes in regular command line programs. By convention, an exit code of 0 means success and a nonzero code indicates some problem.
You can see the exit code of a finished container using other Docker commands. This matters because when you run something like:
docker run ubuntu ls /nonexistent
the command fails inside the container, the container stops, and the exit code reflects that failure. Scripts and automation that call docker run often rely on these exit codes to decide whether something worked or not.
The container stops when the main process started by docker run ends. The container status and exit code come directly from that process.
This also explains why some containers exit immediately. If the default command inside the image completes quickly, the container will not keep running.
Automatic Cleanup with `--rm`
By default, Docker keeps a record of containers even after they stop. This can be useful for checking logs or inspecting what happened, but it can also clutter your system during experiments.
The --rm option tells Docker to remove the container automatically when it exits:
docker run --rm ubuntu echo "temporary task"
With this option, once the command finishes and the container stops, Docker deletes it. This is handy for one time commands where you do not need to inspect the container later.
Combining Multiple Options in `docker run`
Most real world docker run commands combine several options together. The general pattern is that all options come before the image name, and any command or arguments come after the image name.
For example:
docker run --rm --name temp-container ubuntu echo "Hi"
Here, --rm and --name temp-container are options, ubuntu is the image, and echo "Hi" is the command. Docker interprets each part according to its position in the structure described earlier.
As you learn about networking, volumes, and other features in later chapters, you will see more options added to docker run. The structure stays the same. Options before the image, image in the middle, command and arguments after the image.
Understanding this pattern now will make those additional capabilities easier to understand and use correctly.