Docker Run Command with Examples

When you start working with Docker, docker run is the command you will use most often. It creates a container from an image and starts it in a single step. You can run a web server, execute a one-off script, open an interactive shell, or spin up a database, all with different combinations of docker run flags.

This guide walks through the most common options with practical examples using the official Nginx image.

docker run Syntax #

The docker run command takes the following form:

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

The image name is the only required argument. If the image is not present on the local system, Docker pulls it from the configured registry.

When no command is specified, Docker executes the default command defined in the image’s CMD or ENTRYPOINT instruction.

docker run is an alias for docker container run. Both forms work identically.

A full list of options is available in the Docker documentation .

Running in the Foreground #

By default, docker run starts the container process in the foreground with standard input, output, and error attached to your terminal:

docker run nginx

The Nginx process output appears on your terminal. Since there are no incoming connections, the terminal stays empty. This mode is useful when you want to see logs in real time or debug a container that exits unexpectedly. Press CTRL+C to stop the container.

Running in Detached Mode #

To keep the container running after you close the terminal, start it in detached mode with -d. This is similar to running a Linux process in the background :

docker run -d nginx

050e72d8567a3ec1e66370350b0069ab5219614f9701f63fcf02e8c8689f04fa

Docker prints the container ID and returns you to the shell. The container continues running in the background until its main process exits.

You can list running containers with docker container ls and reattach to a detached container with docker attach .

Removing the Container After Exit #

By default, a stopped container’s filesystem remains on the host. The --rm flag tells Docker to automatically remove the container when it exits:

docker run --rm nginx

This is useful for short-lived tasks such as running tests, database backups, or one-off scripts where you do not need the container after it finishes.

Setting the Container Name #

Docker assigns a random name to each container unless you specify one with --name:

docker run -d --name my_nginx nginx

Container names must be unique. If a container with the same name already exists, Docker returns an error:

docker: Error response from daemon: Conflict. The container name "/my_nginx" is already in use...

Remove the old container with docker rm my_nginx or choose a different name. Named containers are easier to reference in commands and Docker networks than random IDs.

Publishing Container Ports #

By default, a container’s ports are not accessible from the host. The -p flag maps a container port to a host port:

-p host_ip:host_port:container_port/protocol

• If no host_ip is specified, it defaults to 0.0.0.0 (all interfaces).
• If no protocol is specified, it defaults to TCP.
• Use multiple -p flags to publish multiple ports.

To map container port 80 (Nginx) to host port 8080:

docker run -d --name web_server -p 8080:80 nginx

Verify the port is published with curl :

curl -I http://localhost:8080

HTTP/1.1 200 OK
Server: nginx
Content-Type: text/html
Connection: keep-alive

The 200 OK response confirms that Docker published host port 8080 and forwarded the request to Nginx inside the container.

Passing Environment Variables #

The -e flag sets environment variables inside the container. This is the standard way to pass configuration such as database credentials, API keys, or feature flags:

docker run -d --name my_db -e MYSQL_ROOT_PASSWORD=secret -e MYSQL_DATABASE=appdb mysql:8

Each variable needs its own -e flag. You can also read variables from a file with --env-file:

docker run -d --name my_db --env-file ./db.env mysql:8

Where db.env contains one variable per line:

MYSQL_ROOT_PASSWORD=secret
MYSQL_DATABASE=appdb

Mounting Volumes #

Docker volumes let you persist data beyond the container’s lifecycle and share files between the host and container. The -v flag maps a host path or named volume to a path inside the container:

-v host_src:container_dest:options

• host_src can be an absolute path on the host or a named volume.
• container_dest is the path inside the container.
• Options can be rw (read-write, the default) or ro (read-only).

To serve a custom HTML file with Nginx, create a directory and add an index.html:

mkdir public_html
echo "Testing Docker Volumes" > public_html/index.html

Mount it into the container’s web root:

docker run -d --name web_server -p 8080:80 -v $(pwd)/public_html:/usr/share/nginx/html nginx

The $(pwd) expands to the current working directory , which gives Docker the absolute host path to mount.

Verify the mount works:

curl http://localhost:8080

Testing Docker Volumes

Any changes you make to files in public_html/ on the host are immediately visible inside the container.

Setting the Working Directory #

The -w flag sets the working directory inside the container. All commands run relative to this path:

docker run --rm -w /app -v $(pwd):/app node:22 npm install

This mounts the current directory into /app, sets /app as the working directory, and runs npm install there. It is a common pattern for running build tools without installing them on the host.

Restart Policies #

The --restart flag controls whether Docker automatically restarts a container when it stops or when the Docker daemon starts:

• --restart no - Do not restart (default).
• --restart on-failure - Restart only if the container exits with a non-zero exit code.
• --restart on-failure:5 - Same as above, but retry at most 5 times.
• --restart unless-stopped - Always restart unless the container was explicitly stopped.
• --restart always - Always restart, even after a daemon reboot.

For a web server that should survive host reboots:

docker run -d --name web_server --restart unless-stopped -p 80:80 nginx

Running Interactively #

To get a shell inside a container, use -i (keep stdin open) and -t (allocate a pseudo-TTY) together:

docker run -it nginx sh

The command prompt changes to the container’s shell:

/#

You can now run commands inside the container. The sh argument overrides the image’s default command. When you type exit, the container stops.

If you want a Bash shell specifically, use an image that includes Bash:

docker run -it --rm ubuntu bash

Quick Reference #

For a printable quick reference, see the Docker cheatsheet .

Conclusion #

The examples above cover the docker run options you will reach for most often. For building your own images, see the Dockerfile guide .

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 800+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page