Search or ask Docker

Create a container

POST /containers/create — Docker Engine API 1.57.

View Markdown
POST/containers/create

Connection and access

API connection and authentication guidance

/v1.57

No HTTP authentication requirement is declared for this operation. Transport access controls can still apply.

Parameters

name query

Assign the specified name to the container. Must match /?[a-zA-Z0-9][a-zA-Z0-9_.-]+.

Type: string

All schema constraints and annotations
{
  "pattern": "^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$",
  "type": "string"
}

platform query

Platform in the format os[/arch[/variant]] used for image lookup.

When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a 404 status.

If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the Warnings field in the response, for example;

WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested

Type: string

All schema constraints and annotations
{
  "default": "",
  "type": "string"
}

Request and responses

Request

Container to create

application/json

All constraints apply

Schema: ContainerConfig

Type: object

HostConfig

Schema: HostConfig

NetworkingConfig

Schema: NetworkingConfig

All schema constraints and annotations
{
  "properties": {
    "HostConfig": {
      "$ref": "#/components/schemas/HostConfig"
    },
    "NetworkingConfig": {
      "$ref": "#/components/schemas/NetworkingConfig"
    }
  },
  "type": "object"
}
All schema constraints and annotations
{
  "allOf": [
    {
      "$ref": "#/components/schemas/ContainerConfig"
    },
    {
      "properties": {
        "HostConfig": {
          "$ref": "#/components/schemas/HostConfig"
        },
        "NetworkingConfig": {
          "$ref": "#/components/schemas/NetworkingConfig"
        }
      },
      "type": "object"
    }
  ],
  "example": {
    "AttachStderr": true,
    "AttachStdin": false,
    "AttachStdout": true,
    "Cmd": [
      "date"
    ],
    "Domainname": "",
    "Entrypoint": "",
    "Env": [
      "FOO=bar",
      "BAZ=quux"
    ],
    "ExposedPorts": {
      "22/tcp": {}
    },
    "HostConfig": {
      "AutoRemove": true,
      "Binds": [
        "/tmp:/tmp"
      ],
      "BlkioDeviceReadBps": [
        {}
      ],
      "BlkioDeviceReadIOps": [
        {}
      ],
      "BlkioDeviceWriteBps": [
        {}
      ],
      "BlkioDeviceWriteIOps": [
        {}
      ],
      "BlkioWeight": 300,
      "BlkioWeightDevice": [
        {}
      ],
      "CapAdd": [
        "NET_ADMIN"
      ],
      "CapDrop": [
        "MKNOD"
      ],
      "CgroupParent": "",
      "CpuPercent": 80,
      "CpuPeriod": 100000,
      "CpuQuota": 50000,
      "CpuRealtimePeriod": 1000000,
      "CpuRealtimeRuntime": 10000,
      "CpuShares": 512,
      "CpusetCpus": "0,1",
      "CpusetMems": "0,1",
      "DeviceRequests": [
        {
          "Capabilities": [
            [
              "gpu",
              "nvidia",
              "compute"
            ]
          ],
          "Count": -1,
          "DeviceIDs\"": [
            "0",
            "1",
            "GPU-fef8089b-4820-abfc-e83e-94318197576e"
          ],
          "Driver": "nvidia",
          "Options": {
            "property1": "string",
            "property2": "string"
          }
        }
      ],
      "Devices": [],
      "Dns": [
        "8.8.8.8"
      ],
      "DnsOptions": [
        ""
      ],
      "DnsSearch": [
        ""
      ],
      "GroupAdd": [
        "newgroup"
      ],
      "Links": [
        "redis3:redis"
      ],
      "LogConfig": {
        "Config": {},
        "Type": "json-file"
      },
      "MaximumIOBps": 0,
      "MaximumIOps": 0,
      "Memory": 0,
      "MemoryReservation": 0,
      "MemorySwap": 0,
      "MemorySwappiness": 60,
      "NanoCpus": 500000,
      "NetworkMode": "bridge",
      "OomKillDisable": false,
      "OomScoreAdj": 500,
      "PidMode": "",
      "PidsLimit": 0,
      "PortBindings": {
        "22/tcp": [
          {
            "HostPort": "11022"
          }
        ]
      },
      "Privileged": false,
      "PublishAllPorts": false,
      "ReadonlyRootfs": false,
      "RestartPolicy": {
        "MaximumRetryCount": 0,
        "Name": ""
      },
      "SecurityOpt": [],
      "ShmSize": 67108864,
      "StorageOpt": {},
      "Ulimits": [
        {}
      ],
      "VolumeDriver": "",
      "VolumesFrom": [
        "parent",
        "other:ro"
      ]
    },
    "Hostname": "",
    "Image": "ubuntu",
    "Labels": {
      "com.example.license": "GPL",
      "com.example.vendor": "Acme",
      "com.example.version": "1.0"
    },
    "NetworkDisabled": false,
    "NetworkingConfig": {
      "EndpointsConfig": {
        "database_nw": {},
        "isolated_nw": {
          "Aliases": [
            "server_x",
            "server_y"
          ],
          "IPAMConfig": {
            "IPv4Address": "172.20.30.33",
            "IPv6Address": "2001:db8:abcd::3033",
            "LinkLocalIPs": [
              "169.254.34.68",
              "fe80::3468"
            ]
          },
          "Links": [
            "container_1",
            "container_2"
          ]
        }
      }
    },
    "OpenStdin": false,
    "StdinOnce": false,
    "StopSignal": "SIGTERM",
    "StopTimeout": 10,
    "Tty": false,
    "User": "",
    "Volumes": {
      "/volumes/data": {}
    },
    "WorkingDir": ""
  }
}

Request

Container to create

application/octet-stream

All constraints apply

Schema: ContainerConfig

Type: object

HostConfig

Schema: HostConfig

NetworkingConfig

Schema: NetworkingConfig

All schema constraints and annotations
{
  "properties": {
    "HostConfig": {
      "$ref": "#/components/schemas/HostConfig"
    },
    "NetworkingConfig": {
      "$ref": "#/components/schemas/NetworkingConfig"
    }
  },
  "type": "object"
}
All schema constraints and annotations
{
  "allOf": [
    {
      "$ref": "#/components/schemas/ContainerConfig"
    },
    {
      "properties": {
        "HostConfig": {
          "$ref": "#/components/schemas/HostConfig"
        },
        "NetworkingConfig": {
          "$ref": "#/components/schemas/NetworkingConfig"
        }
      },
      "type": "object"
    }
  ],
  "example": {
    "AttachStderr": true,
    "AttachStdin": false,
    "AttachStdout": true,
    "Cmd": [
      "date"
    ],
    "Domainname": "",
    "Entrypoint": "",
    "Env": [
      "FOO=bar",
      "BAZ=quux"
    ],
    "ExposedPorts": {
      "22/tcp": {}
    },
    "HostConfig": {
      "AutoRemove": true,
      "Binds": [
        "/tmp:/tmp"
      ],
      "BlkioDeviceReadBps": [
        {}
      ],
      "BlkioDeviceReadIOps": [
        {}
      ],
      "BlkioDeviceWriteBps": [
        {}
      ],
      "BlkioDeviceWriteIOps": [
        {}
      ],
      "BlkioWeight": 300,
      "BlkioWeightDevice": [
        {}
      ],
      "CapAdd": [
        "NET_ADMIN"
      ],
      "CapDrop": [
        "MKNOD"
      ],
      "CgroupParent": "",
      "CpuPercent": 80,
      "CpuPeriod": 100000,
      "CpuQuota": 50000,
      "CpuRealtimePeriod": 1000000,
      "CpuRealtimeRuntime": 10000,
      "CpuShares": 512,
      "CpusetCpus": "0,1",
      "CpusetMems": "0,1",
      "DeviceRequests": [
        {
          "Capabilities": [
            [
              "gpu",
              "nvidia",
              "compute"
            ]
          ],
          "Count": -1,
          "DeviceIDs\"": [
            "0",
            "1",
            "GPU-fef8089b-4820-abfc-e83e-94318197576e"
          ],
          "Driver": "nvidia",
          "Options": {
            "property1": "string",
            "property2": "string"
          }
        }
      ],
      "Devices": [],
      "Dns": [
        "8.8.8.8"
      ],
      "DnsOptions": [
        ""
      ],
      "DnsSearch": [
        ""
      ],
      "GroupAdd": [
        "newgroup"
      ],
      "Links": [
        "redis3:redis"
      ],
      "LogConfig": {
        "Config": {},
        "Type": "json-file"
      },
      "MaximumIOBps": 0,
      "MaximumIOps": 0,
      "Memory": 0,
      "MemoryReservation": 0,
      "MemorySwap": 0,
      "MemorySwappiness": 60,
      "NanoCpus": 500000,
      "NetworkMode": "bridge",
      "OomKillDisable": false,
      "OomScoreAdj": 500,
      "PidMode": "",
      "PidsLimit": 0,
      "PortBindings": {
        "22/tcp": [
          {
            "HostPort": "11022"
          }
        ]
      },
      "Privileged": false,
      "PublishAllPorts": false,
      "ReadonlyRootfs": false,
      "RestartPolicy": {
        "MaximumRetryCount": 0,
        "Name": ""
      },
      "SecurityOpt": [],
      "ShmSize": 67108864,
      "StorageOpt": {},
      "Ulimits": [
        {}
      ],
      "VolumeDriver": "",
      "VolumesFrom": [
        "parent",
        "other:ro"
      ]
    },
    "Hostname": "",
    "Image": "ubuntu",
    "Labels": {
      "com.example.license": "GPL",
      "com.example.vendor": "Acme",
      "com.example.version": "1.0"
    },
    "NetworkDisabled": false,
    "NetworkingConfig": {
      "EndpointsConfig": {
        "database_nw": {},
        "isolated_nw": {
          "Aliases": [
            "server_x",
            "server_y"
          ],
          "IPAMConfig": {
            "IPv4Address": "172.20.30.33",
            "IPv6Address": "2001:db8:abcd::3033",
            "LinkLocalIPs": [
              "169.254.34.68",
              "fe80::3468"
            ]
          },
          "Links": [
            "container_1",
            "container_2"
          ]
        }
      }
    },
    "OpenStdin": false,
    "StdinOnce": false,
    "StopSignal": "SIGTERM",
    "StopTimeout": 10,
    "Tty": false,
    "User": "",
    "Volumes": {
      "/volumes/data": {}
    },
    "WorkingDir": ""
  }
}

Response 201

Container created successfully

application/json

Schema: ContainerCreateResponse

Response 400

bad parameter

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 404

no such image

application/json

Schema: ErrorResponse

Example

{
  "message": "No such image: c2ada9df5af8"
}

Response 409

conflict

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 500

server error

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Referenced schemas

#/components/schemas/ContainerConfig

#/components/schemas/ContainerCreateResponse

#/components/schemas/ErrorResponse

#/components/schemas/HostConfig

#/components/schemas/NetworkingConfig

Complete operation contract
{
  "operationId": "ContainerCreate",
  "parameters": [
    {
      "description": "Assign the specified name to the container. Must match\n`/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.\n",
      "in": "query",
      "name": "name",
      "schema": {
        "pattern": "^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$",
        "type": "string"
      }
    },
    {
      "description": "Platform in the format `os[/arch[/variant]]` used for image lookup.\n\nWhen specified, the daemon checks if the requested image is present\nin the local image cache with the given OS and Architecture, and\notherwise returns a `404` status.\n\nIf the option is not set, the host's native OS and Architecture are\nused to look up the image in the image cache. However, if no platform\nis passed and the given image does exist in the local image cache,\nbut its OS or architecture does not match, the container is created\nwith the available image, and a warning is added to the `Warnings`\nfield in the response, for example;\n\n    WARNING: The requested image's platform (linux/arm64/v8) does not\n             match the detected host platform (linux/amd64) and no\n             specific platform was requested\n",
      "in": "query",
      "name": "platform",
      "schema": {
        "default": "",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/ContainerConfig"
            },
            {
              "properties": {
                "HostConfig": {
                  "$ref": "#/components/schemas/HostConfig"
                },
                "NetworkingConfig": {
                  "$ref": "#/components/schemas/NetworkingConfig"
                }
              },
              "type": "object"
            }
          ],
          "example": {
            "AttachStderr": true,
            "AttachStdin": false,
            "AttachStdout": true,
            "Cmd": [
              "date"
            ],
            "Domainname": "",
            "Entrypoint": "",
            "Env": [
              "FOO=bar",
              "BAZ=quux"
            ],
            "ExposedPorts": {
              "22/tcp": {}
            },
            "HostConfig": {
              "AutoRemove": true,
              "Binds": [
                "/tmp:/tmp"
              ],
              "BlkioDeviceReadBps": [
                {}
              ],
              "BlkioDeviceReadIOps": [
                {}
              ],
              "BlkioDeviceWriteBps": [
                {}
              ],
              "BlkioDeviceWriteIOps": [
                {}
              ],
              "BlkioWeight": 300,
              "BlkioWeightDevice": [
                {}
              ],
              "CapAdd": [
                "NET_ADMIN"
              ],
              "CapDrop": [
                "MKNOD"
              ],
              "CgroupParent": "",
              "CpuPercent": 80,
              "CpuPeriod": 100000,
              "CpuQuota": 50000,
              "CpuRealtimePeriod": 1000000,
              "CpuRealtimeRuntime": 10000,
              "CpuShares": 512,
              "CpusetCpus": "0,1",
              "CpusetMems": "0,1",
              "DeviceRequests": [
                {
                  "Capabilities": [
                    [
                      "gpu",
                      "nvidia",
                      "compute"
                    ]
                  ],
                  "Count": -1,
                  "DeviceIDs\"": [
                    "0",
                    "1",
                    "GPU-fef8089b-4820-abfc-e83e-94318197576e"
                  ],
                  "Driver": "nvidia",
                  "Options": {
                    "property1": "string",
                    "property2": "string"
                  }
                }
              ],
              "Devices": [],
              "Dns": [
                "8.8.8.8"
              ],
              "DnsOptions": [
                ""
              ],
              "DnsSearch": [
                ""
              ],
              "GroupAdd": [
                "newgroup"
              ],
              "Links": [
                "redis3:redis"
              ],
              "LogConfig": {
                "Config": {},
                "Type": "json-file"
              },
              "MaximumIOBps": 0,
              "MaximumIOps": 0,
              "Memory": 0,
              "MemoryReservation": 0,
              "MemorySwap": 0,
              "MemorySwappiness": 60,
              "NanoCpus": 500000,
              "NetworkMode": "bridge",
              "OomKillDisable": false,
              "OomScoreAdj": 500,
              "PidMode": "",
              "PidsLimit": 0,
              "PortBindings": {
                "22/tcp": [
                  {
                    "HostPort": "11022"
                  }
                ]
              },
              "Privileged": false,
              "PublishAllPorts": false,
              "ReadonlyRootfs": false,
              "RestartPolicy": {
                "MaximumRetryCount": 0,
                "Name": ""
              },
              "SecurityOpt": [],
              "ShmSize": 67108864,
              "StorageOpt": {},
              "Ulimits": [
                {}
              ],
              "VolumeDriver": "",
              "VolumesFrom": [
                "parent",
                "other:ro"
              ]
            },
            "Hostname": "",
            "Image": "ubuntu",
            "Labels": {
              "com.example.license": "GPL",
              "com.example.vendor": "Acme",
              "com.example.version": "1.0"
            },
            "NetworkDisabled": false,
            "NetworkingConfig": {
              "EndpointsConfig": {
                "database_nw": {},
                "isolated_nw": {
                  "Aliases": [
                    "server_x",
                    "server_y"
                  ],
                  "IPAMConfig": {
                    "IPv4Address": "172.20.30.33",
                    "IPv6Address": "2001:db8:abcd::3033",
                    "LinkLocalIPs": [
                      "169.254.34.68",
                      "fe80::3468"
                    ]
                  },
                  "Links": [
                    "container_1",
                    "container_2"
                  ]
                }
              }
            },
            "OpenStdin": false,
            "StdinOnce": false,
            "StopSignal": "SIGTERM",
            "StopTimeout": 10,
            "Tty": false,
            "User": "",
            "Volumes": {
              "/volumes/data": {}
            },
            "WorkingDir": ""
          }
        }
      },
      "application/octet-stream": {
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/ContainerConfig"
            },
            {
              "properties": {
                "HostConfig": {
                  "$ref": "#/components/schemas/HostConfig"
                },
                "NetworkingConfig": {
                  "$ref": "#/components/schemas/NetworkingConfig"
                }
              },
              "type": "object"
            }
          ],
          "example": {
            "AttachStderr": true,
            "AttachStdin": false,
            "AttachStdout": true,
            "Cmd": [
              "date"
            ],
            "Domainname": "",
            "Entrypoint": "",
            "Env": [
              "FOO=bar",
              "BAZ=quux"
            ],
            "ExposedPorts": {
              "22/tcp": {}
            },
            "HostConfig": {
              "AutoRemove": true,
              "Binds": [
                "/tmp:/tmp"
              ],
              "BlkioDeviceReadBps": [
                {}
              ],
              "BlkioDeviceReadIOps": [
                {}
              ],
              "BlkioDeviceWriteBps": [
                {}
              ],
              "BlkioDeviceWriteIOps": [
                {}
              ],
              "BlkioWeight": 300,
              "BlkioWeightDevice": [
                {}
              ],
              "CapAdd": [
                "NET_ADMIN"
              ],
              "CapDrop": [
                "MKNOD"
              ],
              "CgroupParent": "",
              "CpuPercent": 80,
              "CpuPeriod": 100000,
              "CpuQuota": 50000,
              "CpuRealtimePeriod": 1000000,
              "CpuRealtimeRuntime": 10000,
              "CpuShares": 512,
              "CpusetCpus": "0,1",
              "CpusetMems": "0,1",
              "DeviceRequests": [
                {
                  "Capabilities": [
                    [
                      "gpu",
                      "nvidia",
                      "compute"
                    ]
                  ],
                  "Count": -1,
                  "DeviceIDs\"": [
                    "0",
                    "1",
                    "GPU-fef8089b-4820-abfc-e83e-94318197576e"
                  ],
                  "Driver": "nvidia",
                  "Options": {
                    "property1": "string",
                    "property2": "string"
                  }
                }
              ],
              "Devices": [],
              "Dns": [
                "8.8.8.8"
              ],
              "DnsOptions": [
                ""
              ],
              "DnsSearch": [
                ""
              ],
              "GroupAdd": [
                "newgroup"
              ],
              "Links": [
                "redis3:redis"
              ],
              "LogConfig": {
                "Config": {},
                "Type": "json-file"
              },
              "MaximumIOBps": 0,
              "MaximumIOps": 0,
              "Memory": 0,
              "MemoryReservation": 0,
              "MemorySwap": 0,
              "MemorySwappiness": 60,
              "NanoCpus": 500000,
              "NetworkMode": "bridge",
              "OomKillDisable": false,
              "OomScoreAdj": 500,
              "PidMode": "",
              "PidsLimit": 0,
              "PortBindings": {
                "22/tcp": [
                  {
                    "HostPort": "11022"
                  }
                ]
              },
              "Privileged": false,
              "PublishAllPorts": false,
              "ReadonlyRootfs": false,
              "RestartPolicy": {
                "MaximumRetryCount": 0,
                "Name": ""
              },
              "SecurityOpt": [],
              "ShmSize": 67108864,
              "StorageOpt": {},
              "Ulimits": [
                {}
              ],
              "VolumeDriver": "",
              "VolumesFrom": [
                "parent",
                "other:ro"
              ]
            },
            "Hostname": "",
            "Image": "ubuntu",
            "Labels": {
              "com.example.license": "GPL",
              "com.example.vendor": "Acme",
              "com.example.version": "1.0"
            },
            "NetworkDisabled": false,
            "NetworkingConfig": {
              "EndpointsConfig": {
                "database_nw": {},
                "isolated_nw": {
                  "Aliases": [
                    "server_x",
                    "server_y"
                  ],
                  "IPAMConfig": {
                    "IPv4Address": "172.20.30.33",
                    "IPv6Address": "2001:db8:abcd::3033",
                    "LinkLocalIPs": [
                      "169.254.34.68",
                      "fe80::3468"
                    ]
                  },
                  "Links": [
                    "container_1",
                    "container_2"
                  ]
                }
              }
            },
            "OpenStdin": false,
            "StdinOnce": false,
            "StopSignal": "SIGTERM",
            "StopTimeout": 10,
            "Tty": false,
            "User": "",
            "Volumes": {
              "/volumes/data": {}
            },
            "WorkingDir": ""
          }
        }
      }
    },
    "description": "Container to create",
    "required": true,
    "x-codegen-request-body-name": "body"
  },
  "responses": {
    "201": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContainerCreateResponse"
          }
        }
      },
      "description": "Container created successfully"
    },
    "400": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "bad parameter"
    },
    "404": {
      "content": {
        "application/json": {
          "example": {
            "message": "No such image: c2ada9df5af8"
          },
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "no such image"
    },
    "409": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "conflict"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "server error"
    }
  },
  "summary": "Create a container",
  "tags": [
    "Container"
  ]
}