.nh
.TH "DOCKER" "1" "Sep 2024" "Docker Community" "Docker User Manuals"

.SH NAME
.PP
docker-container-run - Create and run a new container from an image


.SH SYNOPSIS
.PP
\fBdocker container run [OPTIONS] IMAGE [COMMAND] [ARG...]\fP


.SH DESCRIPTION
.PP
Alias for \fBdocker run\fR\&.


.SH OPTIONS
.PP
\fB--add-host\fP=
	Add a custom host-to-IP mapping (host:ip)

.PP
\fB--annotation\fP=map[]
	Add an annotation to the container (passed through to the OCI runtime)

.PP
\fB-a\fP, \fB--attach\fP=
	Attach to STDIN, STDOUT or STDERR

.PP
\fB--blkio-weight\fP=0
	Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0)

.PP
\fB--blkio-weight-device\fP=[]
	Block IO weight (relative device weight)

.PP
\fB--cap-add\fP=
	Add Linux capabilities

.PP
\fB--cap-drop\fP=
	Drop Linux capabilities

.PP
\fB--cgroup-parent\fP=""
	Optional parent cgroup for the container

.PP
\fB--cgroupns\fP=""
	Cgroup namespace to use (host|private)
\&'host':    Run the container in the Docker host's cgroup namespace
\&'private': Run the container in its own private cgroup namespace
\&'':        Use the cgroup namespace as configured by the
           default-cgroupns-mode option on the daemon (default)

.PP
\fB--cidfile\fP=""
	Write the container ID to the file

.PP
\fB--cpu-count\fP=0
	CPU count (Windows only)

.PP
\fB--cpu-percent\fP=0
	CPU percent (Windows only)

.PP
\fB--cpu-period\fP=0
	Limit CPU CFS (Completely Fair Scheduler) period

.PP
\fB--cpu-quota\fP=0
	Limit CPU CFS (Completely Fair Scheduler) quota

.PP
\fB--cpu-rt-period\fP=0
	Limit CPU real-time period in microseconds

.PP
\fB--cpu-rt-runtime\fP=0
	Limit CPU real-time runtime in microseconds

.PP
\fB-c\fP, \fB--cpu-shares\fP=0
	CPU shares (relative weight)

.PP
\fB--cpus\fP=
	Number of CPUs

.PP
\fB--cpuset-cpus\fP=""
	CPUs in which to allow execution (0-3, 0,1)

.PP
\fB--cpuset-mems\fP=""
	MEMs in which to allow execution (0-3, 0,1)

.PP
\fB-d\fP, \fB--detach\fP[=false]
	Run container in background and print container ID

.PP
\fB--detach-keys\fP=""
	Override the key sequence for detaching a container

.PP
\fB--device\fP=
	Add a host device to the container

.PP
\fB--device-cgroup-rule\fP=
	Add a rule to the cgroup allowed devices list

.PP
\fB--device-read-bps\fP=[]
	Limit read rate (bytes per second) from a device

.PP
\fB--device-read-iops\fP=[]
	Limit read rate (IO per second) from a device

.PP
\fB--device-write-bps\fP=[]
	Limit write rate (bytes per second) to a device

.PP
\fB--device-write-iops\fP=[]
	Limit write rate (IO per second) to a device

.PP
\fB--disable-content-trust\fP[=true]
	Skip image verification

.PP
\fB--dns\fP=
	Set custom DNS servers

.PP
\fB--dns-option\fP=
	Set DNS options

.PP
\fB--dns-search\fP=
	Set custom DNS search domains

.PP
\fB--domainname\fP=""
	Container NIS domain name

.PP
\fB--entrypoint\fP=""
	Overwrite the default ENTRYPOINT of the image

.PP
\fB-e\fP, \fB--env\fP=
	Set environment variables

.PP
\fB--env-file\fP=
	Read in a file of environment variables

.PP
\fB--expose\fP=
	Expose a port or a range of ports

.PP
\fB--gpus\fP=
	GPU devices to add to the container ('all' to pass all GPUs)

.PP
\fB--group-add\fP=
	Add additional groups to join

.PP
\fB--health-cmd\fP=""
	Command to run to check health

.PP
\fB--health-interval\fP=0s
	Time between running the check (ms|s|m|h) (default 0s)

.PP
\fB--health-retries\fP=0
	Consecutive failures needed to report unhealthy

.PP
\fB--health-start-interval\fP=0s
	Time between running the check during the start period (ms|s|m|h) (default 0s)

.PP
\fB--health-start-period\fP=0s
	Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s)

.PP
\fB--health-timeout\fP=0s
	Maximum time to allow one check to run (ms|s|m|h) (default 0s)

.PP
\fB--help\fP[=false]
	Print usage

.PP
\fB-h\fP, \fB--hostname\fP=""
	Container host name

.PP
\fB--init\fP[=false]
	Run an init inside the container that forwards signals and reaps processes

.PP
\fB-i\fP, \fB--interactive\fP[=false]
	Keep STDIN open even if not attached

.PP
\fB--io-maxbandwidth\fP=0
	Maximum IO bandwidth limit for the system drive (Windows only)

.PP
\fB--io-maxiops\fP=0
	Maximum IOps limit for the system drive (Windows only)

.PP
\fB--ip\fP=""
	IPv4 address (e.g., 172.30.100.104)

.PP
\fB--ip6\fP=""
	IPv6 address (e.g., 2001:db8::33)

.PP
\fB--ipc\fP=""
	IPC mode to use

.PP
\fB--isolation\fP=""
	Container isolation technology

.PP
\fB--kernel-memory\fP=0
	Kernel memory limit

.PP
\fB-l\fP, \fB--label\fP=
	Set meta data on a container

.PP
\fB--label-file\fP=
	Read in a line delimited file of labels

.PP
\fB--link\fP=
	Add link to another container

.PP
\fB--link-local-ip\fP=
	Container IPv4/IPv6 link-local addresses

.PP
\fB--log-driver\fP=""
	Logging driver for the container

.PP
\fB--log-opt\fP=
	Log driver options

.PP
\fB--mac-address\fP=""
	Container MAC address (e.g., 92:d0:c6:0a:29:33)

.PP
\fB-m\fP, \fB--memory\fP=0
	Memory limit

.PP
\fB--memory-reservation\fP=0
	Memory soft limit

.PP
\fB--memory-swap\fP=0
	Swap limit equal to memory plus swap: '-1' to enable unlimited swap

.PP
\fB--memory-swappiness\fP=-1
	Tune container memory swappiness (0 to 100)

.PP
\fB--mount\fP=
	Attach a filesystem mount to the container

.PP
\fB--name\fP=""
	Assign a name to the container

.PP
\fB--network\fP=
	Connect a container to a network

.PP
\fB--network-alias\fP=
	Add network-scoped alias for the container

.PP
\fB--no-healthcheck\fP[=false]
	Disable any container-specified HEALTHCHECK

.PP
\fB--oom-kill-disable\fP[=false]
	Disable OOM Killer

.PP
\fB--oom-score-adj\fP=0
	Tune host's OOM preferences (-1000 to 1000)

.PP
\fB--pid\fP=""
	PID namespace to use

.PP
\fB--pids-limit\fP=0
	Tune container pids limit (set -1 for unlimited)

.PP
\fB--platform\fP=""
	Set platform if server is multi-platform capable

.PP
\fB--privileged\fP[=false]
	Give extended privileges to this container

.PP
\fB-p\fP, \fB--publish\fP=
	Publish a container's port(s) to the host

.PP
\fB-P\fP, \fB--publish-all\fP[=false]
	Publish all exposed ports to random ports

.PP
\fB--pull\fP="missing"
	Pull image before running ("always", "missing", "never")

.PP
\fB-q\fP, \fB--quiet\fP[=false]
	Suppress the pull output

.PP
\fB--read-only\fP[=false]
	Mount the container's root filesystem as read only

.PP
\fB--restart\fP="no"
	Restart policy to apply when a container exits

.PP
\fB--rm\fP[=false]
	Automatically remove the container and its associated anonymous volumes when it exits

.PP
\fB--runtime\fP=""
	Runtime to use for this container

.PP
\fB--security-opt\fP=
	Security Options

.PP
\fB--shm-size\fP=0
	Size of /dev/shm

.PP
\fB--sig-proxy\fP[=true]
	Proxy received signals to the process

.PP
\fB--stop-signal\fP=""
	Signal to stop the container

.PP
\fB--stop-timeout\fP=0
	Timeout (in seconds) to stop a container

.PP
\fB--storage-opt\fP=
	Storage driver options for the container

.PP
\fB--sysctl\fP=map[]
	Sysctl options

.PP
\fB--tmpfs\fP=
	Mount a tmpfs directory

.PP
\fB-t\fP, \fB--tty\fP[=false]
	Allocate a pseudo-TTY

.PP
\fB--ulimit\fP=[]
	Ulimit options

.PP
\fB-u\fP, \fB--user\fP=""
	Username or UID (format: [:])

.PP
\fB--userns\fP=""
	User namespace to use

.PP
\fB--uts\fP=""
	UTS namespace to use

.PP
\fB-v\fP, \fB--volume\fP=
	Bind mount a volume

.PP
\fB--volume-driver\fP=""
	Optional volume driver for the container

.PP
\fB--volumes-from\fP=
	Mount volumes from the specified container(s)

.PP
\fB-w\fP, \fB--workdir\fP=""
	Working directory inside the container


.SH SEE ALSO
.PP
\fBdocker-container(1)\fP