Docker Run Command Examples

Read Time: 15 Minutes | Reading Level: Medium

Part 1: Topics Covered

Introduction to Docker Run Command
Tutorial Prerequisite
Downloading a few images (Alpine Linux Versions)
The docker run command Syntax
The first run command using,
- repository name
- repository-name:tag
- Image Id
Run an Image that is not available locally
The Docker Run with a [COMMAND]
The Docker run command Options

The --rm (remove) option
The --interactive -i mode option
The --tty -t mode option for Pseudo Terminal
The --detach -d mode
The --name option

Introduction

The docker run command is undoubtedly the most widely used and essential command for day-to-day usage. It is the command with an extensive list of options or flags.

It is imperative for one to master the run command and to have an idea of the permutation and combination of options to use in different scenarios for running a docker image and spawning a container.

When you execute a docker run command, Docker runs a container as an isolated process on the host with its own file system, networking and a separate process tree which is separate from the host system.

Prerequisite

- You should have Docker Desktop installed on your computer.

- You should have a basic understanding of Docker and commands such as pull, images, run, ps, etc.

- Have few images downloaded locally.

Downloading few images

As to learning the run command, we will surely need a few images to test them, let's get a few pulled from Docker Hub,

docker pull alpine:latest

docker pull alpine:edge

docker pull alpine:3.16.2

Docker run command with examples:

The run command Syntax

Before we start looking at some examples, let's take a look at what the structure of the run command looks like,

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

What is mentioned in the square brackets are optional parameters. So as you may have guessed by now, docker run image are the three words that are always needed to do a docker run, which makes it our first example,

The first run command

Let's do a docker ps to see what all images we have first,

$ docker ps

REPOSITORY          TAG       IMAGE ID       CREATED        SIZE
alpine              3.16.2    16d65c69c39d   10 days ago    5.29MB
alpine              edge      2aef41d31e68   10 days ago    7.46MB
alpine              latest    a6215f271958   3 months ago   5.29MB

To run a Docker image we can either pass in,

repository name
repository-name:tag
Image Id

Example 1: Run using the image/repository name

$ docker run alpine

Note: We have 3 images of Alpine Linux, if you do not pass the tag, by default the :lastest tag will be picked up to create the container, so it's always better to pass the tag explicitly when you have multiple repositories with the same name.

Advance Tip: To know the image ID of the container make use of the docker inspect command.

$ docker inspect e80e8a3abe79 | grep Image

"Image": "sha256:a6215f271958c760a2975a6765016044115dbae4b90f414eba3a448a6a26b4f6",
"Image": "alpine",

If you see the first 12 characters of the sha256 of the container Image, it matches with alpine:latest

Example 2: Run using the repository:tag

$ docker run alpine:edge

Some tags have names, while some may just have a version number eg. 3.16.2

$ docker run alpine:3.16.2

Example 3: Run using IMAGE ID

The third way to run a Docker image is using the image id which you can get by running the docker images command,

$ docker run 2aef41d31e68

Example 4: Run an Image that is not available locally

When you run an image and it is not available locally, the Docker daemon will get it pulled and downloaded and then will run to create a container,

$ docker run node

Unable to find image 'node:latest' locally
latest: Pulling from library/node
077c13527d40: Pull complete 
a3e29af4daf3: Pull complete 
3d7b1480fa4d: Pull complete 
426e8acfed2a: Downloading  53.83MB/54.68MB
7301bf329e1e: Downloading  65.59MB/189.8MB
9eb76eece07e: Download complete 
67add1bbe8f9: Downloading  2.796MB/45.81MB
b0882f3e8638: Waiting 
70617c9ca86d: Waiting 

...
...
Digest: sha256:bff0e689cb433913ab411af7a58253d54c7fd8c3134ffeb25287cdf24d9a5972
Status: Downloaded newer image for node:latest

If you pass in an invalid Image name, name:tag or image ID you will get an error.

% docker run alpine:aaa
Unable to find image 'alpine:aaa' locally
docker: Error response from daemon: manifest for alpine:aaa not found: 
manifest unknown: manifest unknown.
See 'docker run --help'.

% docker run alpine123 
Unable to find image 'alpine123:latest' locally
docker: Error response from daemon: pull access denied for alpine123, 
repository does not exist or may require 'docker login': denied: 
requested access to the resource is denied.

The Docker Run with a [COMMAND]

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

In all the above examples, one must have noticed that as docker run gets executed it is returned back to the prompt with no output, this is because when you do not provide any command or options along with docker run the container has nothing to do and it exits. You can check that using the docker ps -a

% docker ps -a
CONTAINER ID   IMAGE           COMMAND                  CREATED             STATUS                         PORTS     NAMES
7caceda3ca9c   node            "docker-entrypoint.s…"   6 minutes ago       Exited (0) 6 minutes ago                 exciting_maxwell
599a9d7227c3   2aef41d31e68    "/bin/sh"                36 minutes ago      Exited (0) 36 minutes ago                blissful_neumann
eb9f468ac664   alpine:3.16.2   "/bin/sh"                About an hour ago   Exited (0) About an hour ago             vigilant_hoover
13c5add0f3a0   alpine:edge     "/bin/sh"                About an hour ago   Exited (0) About an hour ago             stoic_mendeleev
5d6b520f22a6   alpine          "/bin/sh"                About an hour ago   Exited (0) About an hour ago             flamboyant_ishizaka
e80e8a3abe79   alpine          "/bin/sh"                2 hours ago         Exited (0) 2 hours ago                   musing_mestorf

As you can see, in all the examples we saw, the containers are in Exited (0) status.

When we use an image like Ubuntu or Alpine Linux you can pass in the COMMAND along with the docker run command,

$ docker run alpine whoami
root

Here you can pass in any shell command as shown in the example with whoami, you can also pass in arguments with the command, such as an echo with a string as shown below.

Examples:

$ docker run alpine echo "Hello Docker"
Hello Docker

Yes! You can even run multiple commands separated by a semi-colon. Below are some examples where I ran date, whoami, pwd and cal all one after the other.

% docker run alpine date;whoami;pwd;cal
Mon Nov 21 13:21:24 UTC 2022

code2care

/Users/code2care

   November 2022      
Su Mo Tu We Th Fr Sa  
       1  2  3  4  5  
 6  7  8  9 10 11 12  
13 14 15 16 17 18 19  
20 21 22 23 24 25 26  
27 28 29 30

Docker run command with multiple commands and arguments example

$ docker run alpine echo "sleeping for 10 sec..";sleep 10

sleeping for 10 sec..

The Docker run command Options

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

If you have followed the tutorial from the start, we have covered all aspects of the docker run command, except the OPTIONS.

Options are the most important part of the run command and as we said earlier knowing them is crucial.

The --rm (remove) option

Till now all the commands we ran a docker run command, had create a new container if you do not belive me, just run the docker ps with -a option and you will see a pile of exited containers

$ docker ps -a

CONTAINER ID   IMAGE           COMMAND                   CREATED          STATUS                      PORTS     NAMES
25018a772a18   alpine          "whoami"                  5 hours ago      Exited (0) 5 hours ago                youthful_shockley
0b4f9499b972   alpine          "who"                     5 hours ago      Exited (0) 5 hours ago                priceless_lovelace
4aba0ae290b1   alpine          "ls -l"                   5 hours ago      Exited (0) 5 hours ago                nervous_perlman
c9ba64a28174   alpine          "ls"                      5 hours ago      Exited (0) 5 hours ago                youthful_goldstine
7482b98d18c0   alpine          "echo 'Hello Docker'"     5 hours ago      Exited (0) 5 hours ago                tender_elion
cc8a4063880a   alpine          "echo 'hello world'"      5 hours ago      Exited (0) 5 hours ago                happy_dirac
a2b69e4a0a68   alpine          "echo 'hello world\n'…"   5 hours ago      Exited (0) 5 hours ago                keen_noyce
a9efe8e09a73   alpine          "echo 'hello world\n'…"   5 hours ago      Exited (0) 5 hours ago                mystifying_faraday
7caceda3ca9c   node            "docker-entrypoint.s…"    5 hours ago      Exited (0) 5 hours ago                exciting_maxwell
599a9d7227c3   2aef41d31e68    "/bin/sh"                 6 hours ago      Exited (0) 6 hours ago                blissful_neumann
eb9f468ac664   alpine:3.16.2   "/bin/sh"                 6 hours ago      Exited (0) 6 hours ago                vigilant_hoover
13c5add0f3a0   alpine:edge     "/bin/sh"                 6 hours ago      Exited (0) 6 hours ago                stoic_mendeleev
5d6b520f22a6   alpine          "/bin/sh"                 6 hours ago      Exited (0) 6 hours ago                flamboyant_ishizaka
e80e8a3abe79   alpine          "/bin/sh"                 7 hours ago      Exited (0) 7 hours ago                musing_mestorf
66a95f09c690   a               "/bin/sh"                 8 hours ago      Exited (127) 7 hours ago              thirsty_yonath

You can remove them all by using the docker rm command if you want to remove specific once. Or simply use docker container prune to purge all stopped containers at once.

$ docker container prune

WARNING! This will remove all stopped containers.

Are you sure you want to continue? [y/N] y

Deleted Containers:
f323004688ee492debcdf4c09984fb0d1aa16093df22fa2979d73beee079eaee
a7824a1c4d8622da2e277988aa33673155e4d479f523140332325a64fb3b22a5
...
...
e80e8a3abe79957c4fb41c27dd4056d3b7a8a65227d35b7613a3b7e5b480eba8
66a95f09c69086898d1442691c7099b45a1da5e92a7b57166e28716bc5ac940d

Question: But what if I want to remove the container as soon as it finishes the command/script/task that it ran?

Answer: Make use of the --rm option along with your docker run command.

Example:

$ docker run --rm alpine:edge echo "Hello There"

Hello There

The above command contains all the parts that make up the docker run command

docker run --> Command to build a container out of an image.
--rm --> Option to remove the container after it exits.
alpine:edge --> The image to run.
echo --> The command to run when the containers start.
"Hello There" --> Argument to the command.

Now if you do a docker ps -a you will not see the exited container.

docker run command with rm remove option

The --interactive -i mode option

⛏️ There are two forms of options, a long-form e.g. --interactive, and short-form -i, you can use either of them.

The interactive mode option when used to run a docker image will keep the interactive STDIN (Standard Input /dev/stdin) open.

$ docker run -i alpine

whoami
root

pwd
/

date
Mon Nov 21 14:47:56 UTC 2022

exit

  %

When you type exit, the container will be removed as we have used --rm option, and the prompt will return to your host operating system Terminal shell.

The --tty -t mode option for Pseudo Terminal

You would notice that when we used the interactive mode (-i) option you do not get the Terminal prompt add the -t option to allocate a pseudo-TTY Terminal to the container.

$ docker run --rm -it alpine
#

You can attach a specific terminal by passing it as a command.

Example:

docker run --rm -it alpine sh

The --detach -d mode

If you want to run a command or a script but want the container to run in the background, make use of the detached mode. The containers that you start in the detach mode will exit when the root process used to run the container exits.

Example:

$ docker run -d alpine ping localhost
8ccd8b3553e946cd499f07235441b293822fa820b61d56fbd276f8f6c8571978

The detach option will print out the sha256 of the container. Note you need to run a command or a script/application that keeps running or else the container will quit and go into exit mode. One easy way to run a ping on the localhost.

You can reattach to the container by using the docker attach command.

$ docker attach 8ccd8
64 bytes from 127.0.0.1: seq=4 ttl=64 time=0.206 ms
64 bytes from 127.0.0.1: seq=5 ttl=64 time=0.290 ms
....
....

You do not need to pass the complete sha256 value, the first few characters should do (provided they are unique wrt. other containers that are running)

The --name option

We have seen quite a few options till now, this one is something that you may always want to pass to provide a name for your image, if you do not provide a --name when you run a docker image, docker daemon will randomly pick one name for you.

$ docker run -d --name localhost-pinger alpine ping localhost
eb90f419b6b627c3dac40513b8dc8aa13595bbec86df08fe445d4028be0c9b88

% docker ps -a

CONTAINER ID   IMAGE     COMMAND            CREATED          STATUS                      PORTS     NAMES
eb90f419b6b6   alpine    "ping localhost"   13 seconds ago   Up 12 seconds                         localhost-pinger
ad45334e50e2   alpine    "ping localhost"   9 minutes ago    Exited (0) 8 minutes ago              sweet_jones
5dd1ca1c6c79   alpine    "echo hello"       10 minutes ago   Exited (0) 10 minutes ago             bold_cohen

Facing issues? Have Questions? Post them here! I am happy to answer!

Author Info:

Rakesh (He/Him) has over 14+ years of experience in Web and Application development. He is the author of insightful How-To articles for Code2care.

Follow him on: X

You can also reach out to him via e-mail: rakesh@code2care.org

More Posts related to Docker,

More Posts:

Docker Run Command Examples - Part 1

Part 1: Topics Covered

Introduction

Prerequisite

Downloading few images

Docker run command with examples:

The run command Syntax

The first run command

Example 1: Run using the image/repository name

Example 2: Run using the repository:tag

Example 3: Run using IMAGE ID

Example 4: Run an Image that is not available locally

The Docker Run with a [COMMAND]

The Docker run command Options

The --rm (remove) option

The --interactive -i mode option

The --tty -t mode option for Pseudo Terminal

The --detach -d mode

The --name option