
Docker runs applications inside containers; lightweight, isolated environments that bundle software with its dependencies and configuration. Unlike virtual machines, containers do not require a full guest operating system and instead share the host's kernel. This makes containers faster to start and more resource-efficient. The docker container run
command is the primary method for starting containers from images, applying runtime options, and creating isolated processes.
This article explains how to use docker container run
to launch containers with custom settings. You'll learn how to name containers, run them in detached mode, publish ports, mount volumes, and enable automatic cleanup with --rm
. It also includes reference tables that describe important Docker run flags for managing resources, networks, storage, and container health.
The Short Answer Version
# Run a container interactively from an image
$ docker container run -it ubuntu
# Run a container in the background
$ docker container run -d nginx
# Run and name the container
$ docker container run --name myapp alpine
# Run and publish container port 80 to host port 8080
$ docker container run -p 8080:80 nginx
# Mount a volume into the container
$ docker container run -v $(pwd):/data alpine
# Run and remove container after it exits
$ docker container run --rm busybox echo "done"
Each command demonstrates a core usage of docker container run
, including naming, networking, volumes, interactive mode, and cleanup.
Docker Run General Options
Option | Description | Example |
---|---|---|
-d , --detach |
Run the container in the background (detached mode). | -d |
--name |
Assign a custom name to the container. | --name my-nginx |
--rm |
Automatically remove the container after it exits. | --rm |
-e , --env |
Set an environment variable in the container. | -e NODE_ENV=production |
--env-file |
Load environment variables from a file. | --env-file ./env.list |
--entrypoint |
Override the default entrypoint of the image. | --entrypoint /bin/sh |
-t , --tty |
Allocate a pseudo-TTY for interactive input (typically used with -i ). |
-it |
-i , --interactive |
Keep STDIN open even if not attached (used for interactive mode). | -it |
--workdir , -w |
Set the working directory inside the container. | --workdir /usr/src/app |
Docker Run Networking Options
Option | Description | Example |
---|---|---|
-p , --publish |
Map a container port to a host port to expose a service. | -p 8080:80 |
-P , --publish-all |
Automatically expose all container ports to random host ports. | -P |
--network |
Attach the container to a user-defined Docker network. | --network backend-net |
--add-host |
Add a custom DNS entry to the container’s /etc/hosts file. |
--add-host db.local:10.0.0.5 |
--dns |
Specify custom DNS servers for name resolution inside the container. | --dns 1.1.1.1 |
Docker Run Storage Options
Option | Description | Example |
---|---|---|
-v , --volume |
Mount a host path or named volume to a container path. | -v /data:/app/data |
--mount |
Mount storage using a structured syntax for bind, volume, or tmpfs types. | --mount type=bind,src=/data,dst=/app |
--tmpfs |
Create a temporary in-memory filesystem inside the container. | --tmpfs /app/cache |
--read-only |
Set the entire container filesystem to read-only for added security. | --read-only |
Docker Run Resource Management Options
Option | Description | Example |
---|---|---|
--cpus |
Limit the container to use only the specified number of CPU cores. | --cpus 2 |
--memory , -m |
Set a hard limit for memory usage (e.g., 512m , 2g ). |
-m 512m |
--memory-swap |
Set a combined memory + swap limit. Must be used with --memory . Use -1 to allow unlimited swap. |
--memory-swap 1g |
--oom-kill-disable |
Prevent the container from being killed when it exceeds the memory limit (not recommended). | --oom-kill-disable |
--pids-limit |
Restrict the maximum number of processes inside the container. | --pids-limit 100 |
Docker Run Security Options
Option | Description | Example |
---|---|---|
--user |
Run the container as a specific user (UID and optional GID). | --user 1000:1000 |
--cap-add / --cap-drop |
Add or remove Linux kernel capabilities for the container. | --cap-drop NET_RAW |
--security-opt |
Set container security profiles (e.g., seccomp, AppArmor, SELinux). | --security-opt seccomp=./profile.json |
--privileged |
Grant full host access to the container. Use only when absolutely necessary (e.g., for hardware access). | --privileged |
Docker Run Container Health Options
Option | Description | Example |
---|---|---|
--health-cmd |
Command that runs inside the container to determine if it's healthy. | --health-cmd "curl -f http://127.0.0.1/" |
--health-interval |
Time to wait between health checks (e.g., 30s , 1m ). |
--health-interval 30s |
--health-retries |
Number of consecutive failures required to mark the container unhealthy. | --health-retries 3 |
--no-healthcheck |
Disable any health check defined in the image. | --no-healthcheck |
Docker Run Additional Options
Option | Description | Example |
---|---|---|
--restart |
Configures the container’s restart policy. Common values: no , on-failure , always , unless-stopped . |
--restart always |
--log-driver |
Specifies the logging backend (e.g., json-file , syslog , none ). |
--log-driver json-file |
--pull |
Controls when Docker pulls the image (always , missing , or never ). |
--pull always |
Run Container Under Specific Name
Use the --name
flag with docker container run
to assign a custom name to your container. This helps with logging, management, and automation. Without this flag, Docker generates a random name like frosty_morse
.
Container names must begin with an alphanumeric character and may only contain letters, numbers, underscores (_
), periods (.
), and hyphens (-
).
Command Syntax
docker container run --name <container-name> [IMAGE]
--name <container-name>
: Assigns a specific name to the container.[IMAGE]
: The Docker image to use (e.g.,nginx
,ubuntu
,busybox
).
Command Demonstration
Create a BusyBox container named
busybox_test
.console$ docker container run --name busybox_test busybox
Create an Nginx container named
web-server
.console$ docker container run --name web-server nginx
Create an Ubuntu container named
linux
.console$ docker container run --name linux ubuntu
Create a named container
my-nginx
and run it in the background.console$ docker container run --name my-nginx -d nginx
Verify that the container is running.
console$ docker container ls
Display logs for the
my-nginx
container.console$ docker container logs my-nginx
Rename
my-nginx
tomy-nginx-2
.console$ docker container rename my-nginx my-nginx-2
List containers to confirm the name change.
console$ docker container ls
Output:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES dbbe80f32d93 nginx "/docker-entrypoint.…" 20 seconds ago Up 20 seconds 80/tcp my-nginx-2
Run Container in Background (Detached Mode)
By default, Docker runs containers in the foreground and displays their output in your terminal. To run containers in the background, use the -d
(detached) flag. This is especially useful for services that should run persistently, such as web servers and background workers.
Command Syntax
docker container run -d [IMAGE]
-d
: Runs the container in detached mode.[IMAGE]
: The image to use for the container (e.g.,nginx
,busybox
).
Command Demonstration
Run an Nginx container in background mode.
console$ docker container run --name nginx-bg -d nginx
View logs in real-time.
console$ docker container logs -f nginx-bg
Open a shell session inside the container.
console$ docker container exec -it nginx-bg bash
Run a command inside the container.
console# date
Output:
Fri Jun 27 11:22:47 UTC 2025
Exit the shell.
console# exit
Run Container and Publish Container Ports
Use the -p
or --publish
flag with docker container run
to make a container’s internal ports accessible from the host. Port publishing enables external clients to reach containerized applications like web servers or APIs.
Port publishing is only required for incoming connections. Containers can make outgoing connections without any publishing.
Command Syntax
docker container run -p [IP:]<host_port>:<container_port> [IMAGE]
-p
: Publishes a container port to the host system.[IP:]
: (Optional) Bind the port to a specific interface like127.0.0.1
.<host_port>
: The port exposed on the host machine.<container_port>
: The internal port in the container.[IMAGE]
: The Docker image to run.
Command Demonstration
Map container port
80
to host port8080
.console$ docker container run -p 8080:80 nginx
Map host port
8080
to container port1234
for UDP traffic.console$ docker container run -p 8080:1234/udp busybox
Limit access to localhost only.
console$ docker container run -p 127.0.0.1:8080:80 nginx
Map container port
80
to the same host port.console$ docker container run -p 80:80 nginx
Expose multiple ports (HTTP and HTTPS).
console$ docker container run -p 80:80 -p 443:443 nginx
Command Application
The following examples demonstrate how port publishing behaves in practice, including local and remote accessibility.
Run an Nginx container and expose port 8080 to the public.
console$ docker container run -d -p 8080:80 nginx
Access the container from an external system (replace with your instance IP).
console$ curl http://<SERVER-IP>:8080
Run a container restricted to localhost access only.
console$ docker container run -d -p 127.0.0.1:8081:80 nginx
Verify localhost access works.
console$ curl http://127.0.0.1:8081
Verify remote access is blocked (expect timeout or error).
console$ curl http://<SERVER-IP>:8081
Run Container With Mounted Host Volume
By default, Docker containers run in isolation from the host filesystem. To share files between the host and the container, such as application configs, website content, or database data, use the -v
flag to mount a host directory into the container.
Command Syntax
docker container run -v <host_path>:<container_path>[:options] [IMAGE]
-v
: Mounts a directory from the host system.<host_path>
: Absolute path to a directory on the host.<container_path>
: Target directory inside the container.[:options]
: Optional settings such asro
(read-only).[IMAGE]
: Docker image to run, such asnginx
orbusybox
.
Command Demonstration
Mount a host directory into a BusyBox container with read-write access.
console$ docker container run -v /home/linuxuser/data:/data busybox
Mount the same directory as read-only.
console$ docker container run -v /home/linuxuser/data:/data:ro busybox
Command Application
Use this example to build a real-world containerized web server by serving static files from the host system using Nginx. This demonstrates how volume mounting enables persistent content sharing between host and container.
Create a directory on the host for your static website.
console$ mkdir /home/linuxuser/webdata
Navigate into the directory.
console$ cd /home/linuxuser/webdata
Create an HTML page.
console$ cat <<EOF > index.html <!DOCTYPE html> <html> <head><title>Vultr Greeting</title></head> <body><h1>Greetings from Vultr</h1></body> </html> EOF
Run an Nginx container that mounts the website directory and serves it.
console$ docker container run -d -p 8082:80 -v /home/linuxuser/webdata:/usr/share/nginx/html:ro nginx
-d
: Detached mode.-p 8082:80
: Maps host port 8082 to container port 80.-v ...:ro
: Mounts the host directory as read-only inside the container.
Confirm the container is serving the HTML page.
console$ curl http://127.0.0.1:8082
Output:
<!DOCTYPE html> <html> <head><title>Vultr Greeting</title></head> <body><h1>Greetings from Vultr</h1></body> </html>
Mounted directories persist even after the container is removed. Changes made to files in /usr/share/nginx/html
are reflected in /home/linuxuser/webdata
on the host.
Run Docker Container and Automatically Remove It After Exit
By default, stopped containers remain on the system in an exited
state. Use the --rm
flag with docker container run
to automatically remove the container after it finishes. This is ideal for short-lived containers like scripts, tests, or one-time tasks.
Command Syntax
docker container run --rm [IMAGE] [COMMAND]
--rm
: Removes the container immediately after it exits.[IMAGE]
: The Docker image to run.[COMMAND]
: The command to execute inside the container.
Command Demonstration
Run a container that prints
Hello, world
and self-deletes.console$ docker container run --rm busybox echo "Hello, world"
Run a container that sleeps for 5 seconds, then exits and removes itself.
console$ docker container run --rm busybox sleep 5
Run an Ubuntu container that prints the current date and removes itself.
console$ docker container run --rm ubuntu bash -c "echo Done && date"
Command Application
This demonstration shows how the --rm
flag prevents accumulation of exited containers.
Run a temporary BusyBox container with
--rm
.console$ docker container run --name busybox --rm busybox echo "Temporary container"
Confirm it no longer exists.
console$ docker container ls -a
The container does not appear in the list. Docker deleted it after execution.
Run the same container without
--rm
:console$ docker container run --name busybox busybox echo "Persistent container"
List all containers again.
console$ docker container ls -a
Output:
CONTAINER ID IMAGE COMMAND CREATED STATUS NAMES 9f5d3cc7bb3e busybox "echo 'Persistent co…" 5 seconds ago Exited (0) 5 seconds ago busybox
This container remains on the system in
Exited
state and must be manually removed usingdocker container rm
.
Conclusion
In this article, you learned how to run containers using the docker container run
command. You named containers, launched them in detached mode, mapped ports, mounted host directories, and configured automatic cleanup with --rm
. You also explored key flags for managing container networking, resource limits, security options, and health checks.
These capabilities form the foundation for building portable and reproducible container workflows. For more options and advanced configurations, refer to the official Docker documentation.
No comments yet.