How to Use Docker Run Command [Beginners Guide]

docker run command

The docker run command is used to launch and run containers. Learning how to use docker run command is a recommendation for any developers who want to get familiar with Docker.

When working with Docker, software developers mostly use the 'docker run' command to:

  • Create a container from a given docker image
  • Run a container with an optional name
  • Run a container in the foreground
  • Run a container in the detached mode
  • Run a container in interactive mode
  • Publish container ports to host machine
  • Share data between containers and host machine
  • Remove a container once it stopped

Docker run command

The syntax of the command:

docker run [options] image-name [command] [arg...]

In order to run a docker container, you can simply run the following command, assuming you have already installed docker:

docker run image-name


image-name could be a docker image on your local machine or be pulled from the online registry such as Docker Hub and

In the following example, you’ll run a container from a public image ‘hello-world’ which is located on Docker Hub.

$ sudo docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
0e03bdcc26d7: Pull complete 
Digest: sha256:7f0a9f93b4aa3022c3a4c147a449bf11e0941a1fd0bf4a8e6c9408b2600777c5
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

The first time you run the container, the Docker daemon pulls the image 'hello-world' from the Docker Hub. Then, it creates a new container from that image and streams the output to your terminal. From now on, the image was download to your local machine. You can list all of the docker images by running:

$ sudo docker image ls


REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
ubuntu              latest              4e2eef94cd6b        9 days ago          73.9MB
nginx               latest              4bb46517cac3        2 weeks ago         133MB
alpine              latest              a24bb4013296        3 months ago        5.57MB
truongnh1992/go     latest              57b4af3567ac        3 months ago        7.41MB
hello-world         latest              bf756fb1ae65        7 months ago        13.3kB

The next time you run that image, it is faster than the first one and you can use the IMAGE-ID instead of image name. For example:

$ sudo docker run bf756fb1ae65

Hello from Docker!
This message shows that your installation appears to be working correctly.

Note: From the Docker version 1.13, due to the new syntax of its release, we use ‘docker container run’ instead of ‘docker run’.

It's recommended to preface the docker run command with sudo or the other workaround without sudo.

Run a container with a defined name

When you run a container with the basic syntax ‘docker container run’, the Docker will randomly generate a name for each container as you can see in the below:

$ sudo docker container ls -a


CONTAINER ID        IMAGE               COMMAND             CREATED              STATUS                          PORTS               NAMES
941b67537bbb        ubuntu              "/bin/bash"         4 seconds ago        Exited (0) 3 seconds ago                            musing_elgamal
a7b197b56d2c        bf756fb1ae65        "/hello"            About a minute ago   Exited (0) About a minute ago                       determined_faraday
0b40e331161e        hello-world         "/hello"            4 minutes ago        Exited (0) 4 minutes ago                            nervous_sammet

If you want to explicitly assign a name for your container, let’s run the command with the following syntax:

$ docker container run --name container-name image-name

For example:

$ sudo docker container run --name hello-linoxide hello-world


$ sudo docker container ls -a
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                      PORTS               NAMES
eb2f0c9cc658        hello-world         "/hello"            21 seconds ago      Exited (0) 20 seconds ago                       hello-linoxide

Run a container in the foreground

When we working with docker containers, there are two modes of running them: attached mode and detached mode.

By default, Docker runs the container in foreground. It means container process attaches to the terminal session and displays the output. If the container is still running, it will not return the command prompt.

For example:

$ sudo docker container run nginx

/ /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/ Looking for shell scripts in /docker-entrypoint.d/
/ Launching /docker-entrypoint.d/ Getting the checksum of /etc/nginx/conf.d/default.conf Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/ Launching /docker-entrypoint.d/
/ Configuration complete; ready for start up

Run a container in the detached mode

If you want to run that container in background process (detached mode), let’s use the -d option:

$ sudo docker container run -d nginx

Run a container in interactive mode

Docker supports running a container in the interactive mode. Thanks to this feature, you can execute commands inside a container with a shell.

Using the -it option following with ‘/bin/bash’ or ‘/bin/sh’ to launch the interactive mode, for example:

$ sudo docker container run -it ubuntu /bin/bash
root@d99e70bff763:/# echo $0
$ sudo docker container run -it ubuntu /bin/sh
# echo $0

Port-forwarding a container

By default, in order to access the process running inside a container, you have to go into inside it. If you want to access it from the outside, let’s open a port. By publishing ports, you can map the container ports to the ports on your host machine using -p option as follows:

$ dock container run -p host-port:container-port image

For example, to map port 80 of container nginx to port 8080 on the host machine, run:

$ sudo docker container run -d -p 8080:80 nginx

Now, let's use 'curl' to retrieve the content from localhost:8080

$ curl localhost:8080

Mounting volumes of a container

Data in a container is ephemeral, it is no longer existed when the container is stopped. If you want to keep the data in the container persistently, you have to mount it to a shared storage volume.

Let’s use -v option as the follows for mounting volumes:

$ docker container run -v host-machine-location:container-storage image

For example, let’s mount the ‘share-data’ directory on your host machine into ‘/home’ in the container:

$ mkdir share-data/
$ echo "Hello linoxide readers" > share-data/test.txt
$ sudo docker container run -it -v $(pwd)/share-data:/home alpine


/ # ls /home/
/ # cat /home/test.txt 
Hello linoxide readers

Remove a container once it stopped

By default, when a container stops, its file system still remains on the host machine. They consume a large mount of storage. If you want to automatically remove the container after it exits, use --rm option:

$ docker container run --rm image

For example, running a docker container without --rm option:

$ sudo docker container run ubuntu
$ sudo docker container ls -a
CONTAINER ID        IMAGE               COMMAND                  CREATED              STATUS                      PORTS                  NAMES
ad348fb61463        ubuntu              "/bin/bash"              8 seconds ago        Exited (0) 6 seconds ago                           distracted_hoover

When using --rm option, one the container stopped, it will be automatically removed.

$ sudo docker container run --rm ubuntu
$ sudo docker container ls -a
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES


Docker is an opensource platform that enables software developers to build, deploy, and manage containerized applications. Docker is a really powerful tool for any developer especially DevOps engineers. Mastering the way to use ‘docker container run’ commands is the key to discover the power of Docker.

Thanks for reading and please leave your suggestion in the below comment section.

Truong Nguyen 11:00 am


Your email address will not be published. Required fields are marked *