docker container create

DescriptionCreate a new container
Usagedocker container create [OPTIONS] IMAGE [COMMAND] [ARG...]
docker create


The docker container create (or shorthand: docker create) command creates a new container from the specified image, without starting it.

When creating a container, the Docker daemon creates a writeable container layer over the specified image and prepares it for running the specified command. The container ID is then printed to STDOUT. This is similar to docker run -d except the container is never started. You can then use the docker container start (or shorthand: docker start) command to start the container at any point.

This is useful when you want to set up a container configuration ahead of time so that it's ready to start when you need it. The initial status of the new container is created.

The docker create command shares most of its options with the docker run command (which performs a docker create before starting it). Refer to the docker run CLI reference for details on the available flags and options.


--add-hostAdd a custom host-to-IP mapping (host:ip)
--annotationAPI 1.43+ Add an annotation to the container (passed through to the OCI runtime)
-a, --attachAttach to STDIN, STDOUT or STDERR
--blkio-weightBlock IO (relative weight), between 10 and 1000, or 0 to disable (default 0)
--blkio-weight-deviceBlock IO weight (relative device weight)
--cap-addAdd Linux capabilities
--cap-dropDrop Linux capabilities
--cgroup-parentOptional parent cgroup for the container
--cgroupnsAPI 1.41+ 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)
--cidfileWrite the container ID to the file
--cpu-countCPU count (Windows only)
--cpu-percentCPU percent (Windows only)
--cpu-periodLimit CPU CFS (Completely Fair Scheduler) period
--cpu-quotaLimit CPU CFS (Completely Fair Scheduler) quota
--cpu-rt-periodAPI 1.25+ Limit CPU real-time period in microseconds
--cpu-rt-runtimeAPI 1.25+ Limit CPU real-time runtime in microseconds
-c, --cpu-sharesCPU shares (relative weight)
--cpusAPI 1.25+ Number of CPUs
--cpuset-cpusCPUs in which to allow execution (0-3, 0,1)
--cpuset-memsMEMs in which to allow execution (0-3, 0,1)
--deviceAdd a host device to the container
--device-cgroup-ruleAdd a rule to the cgroup allowed devices list
--device-read-bpsLimit read rate (bytes per second) from a device
--device-read-iopsLimit read rate (IO per second) from a device
--device-write-bpsLimit write rate (bytes per second) to a device
--device-write-iopsLimit write rate (IO per second) to a device
--disable-content-trusttrueSkip image verification
--dnsSet custom DNS servers
--dns-optionSet DNS options
--dns-searchSet custom DNS search domains
--domainnameContainer NIS domain name
--entrypointOverwrite the default ENTRYPOINT of the image
-e, --envSet environment variables
--env-fileRead in a file of environment variables
--exposeExpose a port or a range of ports
--gpusAPI 1.40+ GPU devices to add to the container ('all' to pass all GPUs)
--group-addAdd additional groups to join
--health-cmdCommand to run to check health
--health-intervalTime between running the check (ms|s|m|h) (default 0s)
--health-retriesConsecutive failures needed to report unhealthy
--health-start-intervalAPI 1.44+ Time between running the check during the start period (ms|s|m|h) (default 0s)
--health-start-periodAPI 1.29+ Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s)
--health-timeoutMaximum time to allow one check to run (ms|s|m|h) (default 0s)
--helpPrint usage
-h, --hostnameContainer host name
--initAPI 1.25+ Run an init inside the container that forwards signals and reaps processes
-i, --interactiveKeep STDIN open even if not attached
--io-maxbandwidthMaximum IO bandwidth limit for the system drive (Windows only)
--io-maxiopsMaximum IOps limit for the system drive (Windows only)
--ipIPv4 address (e.g.,
--ip6IPv6 address (e.g., 2001:db8::33)
--ipcIPC mode to use
--isolationContainer isolation technology
--kernel-memoryKernel memory limit
-l, --labelSet meta data on a container
--label-fileRead in a line delimited file of labels
--linkAdd link to another container
--link-local-ipContainer IPv4/IPv6 link-local addresses
--log-driverLogging driver for the container
--log-optLog driver options
--mac-addressContainer MAC address (e.g., 92:d0:c6:0a:29:33)
-m, --memoryMemory limit
--memory-reservationMemory soft limit
--memory-swapSwap limit equal to memory plus swap: '-1' to enable unlimited swap
--memory-swappiness-1Tune container memory swappiness (0 to 100)
--mountAttach a filesystem mount to the container
--nameAssign a name to the container
--networkConnect a container to a network
--network-aliasAdd network-scoped alias for the container
--no-healthcheckDisable any container-specified HEALTHCHECK
--oom-kill-disableDisable OOM Killer
--oom-score-adjTune host's OOM preferences (-1000 to 1000)
--pidPID namespace to use
--pids-limitTune container pids limit (set -1 for unlimited)
--platformAPI 1.32+ Set platform if server is multi-platform capable
--privilegedGive extended privileges to this container
-p, --publishPublish a container's port(s) to the host
-P, --publish-allPublish all exposed ports to random ports
--pullmissingPull image before creating (always, |missing, never)
-q, --quietSuppress the pull output
--read-onlyMount the container's root filesystem as read only
--restartnoRestart policy to apply when a container exits
--rmAutomatically remove the container and its associated anonymous volumes when it exits
--runtimeRuntime to use for this container
--security-optSecurity Options
--shm-sizeSize of /dev/shm
--stop-signalSignal to stop the container
--stop-timeoutAPI 1.25+ Timeout (in seconds) to stop a container
--storage-optStorage driver options for the container
--sysctlSysctl options
--tmpfsMount a tmpfs directory
-t, --ttyAllocate a pseudo-TTY
--ulimitUlimit options
-u, --userUsername or UID (format: <name|uid>[:<group|gid>])
--usernsUser namespace to use
--utsUTS namespace to use
-v, --volumeBind mount a volume
--volume-driverOptional volume driver for the container
--volumes-fromMount volumes from the specified container(s)
-w, --workdirWorking directory inside the container


Create and start a container

The following example creates an interactive container with a pseudo-TTY attached, then starts the container and attaches to it:

$ docker container create -i -t --name mycontainer alpine

$ docker container start --attach -i mycontainer
/ # echo hello world
hello world

The above is the equivalent of a docker run:

$ docker run -it --name mycontainer2 alpine
/ # echo hello world
hello world

Initialize volumes

Container volumes are initialized during the docker create phase (i.e., docker run too). For example, this allows you to create the data volume container, and then use it from another container:

$ docker create -v /data --name data ubuntu


$ docker run --rm --volumes-from data ubuntu ls -la /data

total 8
drwxr-xr-x  2 root root 4096 Dec  5 04:10 .
drwxr-xr-x 48 root root 4096 Dec  5 04:11 ..

Similarly, create a host directory bind mounted volume container, which can then be used from the subsequent container:

$ docker create -v /home/docker:/docker --name docker ubuntu


$ docker run --rm --volumes-from docker ubuntu ls -la /docker

total 20
drwxr-sr-x  5 1000 staff  180 Dec  5 04:00 .
drwxr-xr-x 48 root root  4096 Dec  5 04:13 ..
-rw-rw-r--  1 1000 staff 3833 Dec  5 04:01 .ash_history
-rw-r--r--  1 1000 staff  446 Nov 28 11:51 .ashrc
-rw-r--r--  1 1000 staff   25 Dec  5 04:00 .gitconfig
drwxr-sr-x  3 1000 staff   60 Dec  1 03:28 .local
-rw-r--r--  1 1000 staff  920 Nov 28 11:51 .profile
drwx--S---  2 1000 staff  460 Dec  5 00:51 .ssh
drwxr-xr-x 32 1000 staff 1140 Dec  5 04:01 docker