Docker run command

In this tutorial we will learn in depth about docker run command. I would suggest you read below article to learn about docker image and container before you start reading this tutorial:

Docker image and container

Let's have a look at the diagram to understand more about this command:

Docker run command is used to do following things:

  • Create a new container if it does not exist
  • Run a newly created or previously created container from the image provided

You need to have an image first in order to run this command. If you do not have an image it does following things:

  • Try to find docker image locally
  • If image is not found it tries to find image on Docker hub
  • If it finds the image it downloads it store in the image cache
  • Creates a container from the downloaded or local image
  • If image can not be found on local or on docker hub it gives you no error and does nothing

Let's take an example, open your terminal window and try running following command: 

docker run busybox

It will show you following output:

It does following when we ran above command:

  • It tries to find busybox image locally
  • It did not find this image locally and then talked to docker hub
  • It found the image on docker hub and then downloaded it and stored in cache
  • Once image is downloaded it created and ran the container

Docker run command can also override a default command that container runs when it is created. Let's have a look at following new diagram:

Let's understand above diagram practically. Open your terminal window again and let's run following command: 

# Display Hello There text when container runs
docker run busybox echo Hello There

# Display list of files when container runs
docker run busybox ls​

Note: You wont be able to run default command in all containers

The image we choose to run a container contains some commands of linux system and that is why we are able to run this command in this specific container.

If you remember my last tutorial on docker image and container you know that each container reserves specific resources discribed by image that is used to create this container.

So basically, your image can decide what resources that is required for this image containers.

Let's verify this by running same commands with different docker image called hello-world: 

# Throws an error because this image
# Does not have this command available
docker run hello-world echo Hello There

# Throws an error because this image
# Does not have this command available
docker run hello-world ls

Let's have a look at the output of the above command:

The reason why these commands does not work inside hello-world image is because

  • ls and echo commands are available in busybox image file system
  • while these commands are not available in hello-world image file system

Docker image contains following two things:

  • A snapshot of a given file system
  • A default startup command

Different docker images can contain different file systems depending upon how these images are build.

Let's have a look at what popular available options that we can use for this specific command:

Option Description
-d Run container in the background, print new container id​
-p 80:80 Makes container port to be available on specific host port i.e. -p HOST:CONTAINER
-i Keep STDIN open even if not attached​
-t Allocate a pseudo-tty​
-a=[] Attach to `STDIN`, `STDOUT` and/or `STDERR`​.
-it For interactive processes (like a shell), you must use -i -t together in order to allocate a tty
--name= assign a name to running container
--network= assign a network to running container i.e. host, bridge, none

Sample example of docker run command

Followings are some of the example of docker run command with options: 

# create and run a container in background
# expose port 8080 of container to host at port 80
docker run -d -p 80:8080 my_image

# create and run a container in background
# expose port 8080 of container to host at port 80
# and override default command with nginx -g 'daemon off;'
docker run -d -p 80:8080 my_image nginx -g 'daemon off;'
↑