Modified: 06 Jan 2023 17:17 UTC
Stability: Unknown

Creates a new container.

Usage: docker create [OPTIONS] IMAGE [COMMAND] [ARG...]

Create a new container

  -a, --attach=[]                  Attach to STDIN, STDOUT or STDERR
  --add-host=[]                    Add a custom host-to-IP mapping (host:ip)
  --blkio-weight=0                 Block IO weight (relative weight)
  --blkio-weight-device            Block IO weight (relative device weight) (default [])
  -c, --cpu-shares=0               CPU shares (relative weight)
  --cap-add=[]                     Add Linux capabilities
  --cap-drop=[]                    Drop Linux capabilities
  --cgroup-parent=""               Optional parent cgroup for the container
  --cidfile=""                     Write the container ID to the file
  --cpuset-cpus=""                 CPUs in which to allow execution (0-3, 0,1)
  --cpuset-mems=""                 Memory nodes (MEMs) in which to allow execution (0-3, 0,1)
  --cpu-count                      CPU count (Windows only)
  --cpu-percent                    CPU percent (Windows only)
  --cpu-period=0                   Limit the CPU CFS (Completely Fair Scheduler) period
  --cpu-quota=0                    Limit the CPU CFS (Completely Fair Scheduler) quota
  --credentialspec                 Credential spec for managed service account (Windows only)
  --device=[]                      Add a host device to the container
  --device-cgroup-rule=[]          Add a rule to the cgroup allowed devices list (default [])
  --device-read-bps=[]             Limit read rate (bytes per second) from a device
  --device-read-iops=[]            Limit read rate (IO per second) from a device
  --device-write-bps=[]            Limit write rate (bytes per second) to a device
  --device-write-iops=[]           Limit write rate (IO per second) to a device
  --disable-content-trust=true     Skip image verification
  --dns=[]                         Set custom DNS servers
  --dns-opt=[]                     Set DNS options
  --dns-search=[]                  Set custom DNS search domains
  -e, --env=[]                     Set environment variables
  --entrypoint=""                  Overwrite the default ENTRYPOINT of the image
  --env-file=[]                    Read in a file of environment variables
  --expose=[]                      Expose a port or a range of ports
  --group-add                      Add additional groups to join (default [])
  --health-cmd                     Command to run to check health
  --health-interval                Time between running the check
  --health-retries                 Consecutive failures needed to report unhealthy
  --health-timeout                 Maximum time to allow one check to run
  -h, --hostname=""                Container host name
  --help=false                     Print usage
  -i, --interactive=false          Keep STDIN open even if not attached
  --io-maxbandwidth                Maximum IO bandwidth limit for the system drive (Windows only)
  --io-maxiops                     Maximum IOps limit for the system drive (Windows only)
  --ip                             Container IPv4 address (e.g.
  --ip6                            Container IPv6 address (e.g. 2001:db8::33)
  --ipc=""                         IPC namespace to use
  --isolation                      Container isolation level
  --kernel-memory                  Kernel memory limit
  --link=[]                        Add link to another container
  --link-local-ip                  Container IPv4/IPv6 link-local addresses (default [])
  --log-driver=""                  Logging driver for container
  --log-opt=[]                     Log driver specific options
  -l, --label=[]                   Set metadata on the container (e.g., --label=com.example.key=value)
  --label-file=[]                  Read in a file of labels (EOL delimited)
  -m, --memory=""                  Memory limit
  --mac-address=""                 Container MAC address (e.g. 92:d0:c6:0a:29:33)
  --memory-reservation             Memory soft limit
  --memory-swap=""                 Total memory (memory + swap), '-1' to disable swap
  --memory-swappiness=""           Tune container memory swappiness (0 to 100)
  --name=""                        Assign a name to the container
  --network=default                Connect a container to a network
  --network-alias=[]               Add network-scoped alias for the container
  --no-healthcheck                 Disable any container-specified HEALTHCHECK
  --oom-kill-disable=false         Whether to disable OOM Killer for the container or not
  --oom-score-adj                  Tune host's OOM preferences (-1000 to 1000)
  -P, --publish-all=false          Publish all exposed ports to random ports
  -p, --publish=[]                 Publish a container's port(s) to the host
  --pid=""                         PID namespace to use
  --pids-limit                     Tune container pids limit (set -1 for unlimited)
  --privileged=false               Give extended privileges to this container
  --read-only=false                Mount the container's root filesystem as read only
  --restart="no"                   Restart policy (no, on-failure[:max-retry], always)
  --runtime                        Runtime to use for this container
  --security-opt=[]                Security Options
  --shm-size                       Size of /dev/shm, default value is 64MB
  --stop-signal=SIGTERM            Signal to stop a container, SIGTERM by default
  --storage-opt                    Storage driver options for the container (default [])
  --sysctl                         Sysctl options (default map[])
  -t, --tty=false                  Allocate a pseudo-TTY
  --tmpfs=[]                       Mount a tmpfs directory
  -u, --user=""                    Username or UID (format: <name|uid>[:<group|gid>])
  --ulimit=[]                      Ulimit options
  --userns                         User namespace to use
  --uts=""                         UTS namespace to use
  -v, --volume=[]                  Bind mount a volume
  --volume-driver                  Optional volume driver for the container
  --volumes-from=[]                Mount volumes from the specified container(s)
  -w, --workdir=""                 Working directory inside the container

The docker create command 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 start <container_id> 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 is ready to start when you need it.

Please see the run command section and the Docker run reference for more details.


$ docker create -t -i fedora bash
$ docker start -a -i 6d8af538ec5

As of v1.4.0 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


Triton's secure, multi-tenant, container-native environment imposes some differences from Docker Inc's implementation. Notably, arguments to control LXC or change container privilege are unsupported. Other arguments, such as those to manage CPU allocation, or networking, are more effective because of features unique to Triton. See the Resources and Networks documentation for more information on how to size containers and assign public or private IP addresses to them.

Windows-based images and the associated parameters are not supported on Triton.

Docker Swarm's affinity filters (also called "locality hints" in Triton, see the [cloudapi CreateMachine notes](

CreateMachine)) for controlling on which server a container is provisioned are

supported. See the placement feature documentation for details.

Please contact Joyent support or file a ticket if you discover any additional divergence.