Docker Run Command Examples - Part 1

Read Time: 15 Minutes | Reading Level: Medium

Part 1: Topics Covered

  1. Introduction to Docker Run Command
  2. Tutorial Prerequisite
  3. Downloading a few images (Alpine Linux Versions)
  4. The docker run command Syntax
  5. The first run command using,
    • repository name
    • repository-name:tag
    • Image Id
  6. Run an Image that is not available locally
  7. The Docker Run with a [COMMAND]
  8. The Docker run command Options
    1. The --rm (remove) option
    2. The --interactive -i mode option
    3. The --tty -t mode option for Pseudo Terminal
    4. The --detach -d mode
    5. The --name option


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.


- 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:

  1. The run command Syntax
  2. 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,

  3. The first run command
  4. 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
    Docker Run Repository Example

    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
    Docker run Image colon tag example

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

    $ docker run alpine:3.16.2
    Docker run repo colon tag version

    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
    Run Docker Image using Image Id

    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.

  5. The Docker Run with a [COMMAND]
  6. 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

    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.

    $ 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
       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..

  7. The Docker run command Options
  8. 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.

    1. The --rm (remove) option
    2. 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:

      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.

      $ 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

    3. The --interactive -i mode option
    4. ⛏️ 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
      Mon Nov 21 14:47:56 UTC 2022

      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.

    5. The --tty -t mode option for Pseudo Terminal
    6. 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
      docker run with interactive and pseudo tty terminal example

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

      docker run --rm -it alpine sh

    7. The --detach -d mode
    8. 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.

      $ docker run -d alpine ping localhost

      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 seq=4 ttl=64 time=0.206 ms
      64 bytes from 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)

    9. The --name option
    10. 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
      % 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

      Have Questions? Post them here!

Topics Coverage:

🎉 We are celebrating the 10th years of Code2care! Thank you for all your support!

We strongly support Gender Equality & Diversity.

Follow Us: GitHub | Facebook | Twitter | Instagram