# Create a container


[API catalog](/reference/api/) · [Docker Engine overview](/reference/api/engine/version/v1.57/) · [Product manual](https://docs.docker.com/engine/) · [OpenAPI specification](/reference/api/engine/version/v1.57.yaml)

API version: 1.57





`POST /containers/create`



## Connection and access

[API connection and authentication guidance](/reference/api/engine/version/v1.57/#connection)


Server: `/v1.57`

Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement.

```json
null
```

## Example request

Replace placeholders and provide the required credentials or request body.

```console
curl \
  --request POST \
  --unix-socket "${DOCKER_SOCKET:-/var/run/docker.sock}" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-binary @request-body \
  'http://localhost/v1.57/containers/create'
```


Prepare request-body using the selected media type and schema.


## Parameters

### name

Location: query. Required: no.

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


```json
{
  "description": "Assign the specified name to the container. Must match\n`/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.\n",
  "in": "query",
  "name": "name",
  "pointer": "/paths/~1containers~1create/post/parameters/0",
  "schema": {
    "pattern": "^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$",
    "type": "string"
  }
}
```

### platform

Location: query. Required: no.

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


```json
{
  "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",
  "pointer": "/paths/~1containers~1create/post/parameters/1",
  "schema": {
    "default": "",
    "type": "string"
  }
}
```

## Request and responses

### Request  application/json

Container to create


Schema:

```json
{
  "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  application/octet-stream

Container to create


Schema:

```json
{
  "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 application/json

Container created successfully


Schema:

```json
{
  "$ref": "#/components/schemas/ContainerCreateResponse"
}
```










### Response 400 application/json

bad parameter


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


### Response 404 application/json

no such image


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Example:
```json
{
  "message": "No such image: c2ada9df5af8"
}
```


### Response 409 application/json

conflict


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


### Response 500 application/json

server error


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


## Complete operation contract

```json
{
  "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"
  ]
}
```

## Referenced schemas

- [#/components/schemas/ContainerConfig](/reference/api/engine/version/v1.57/schemas/ContainerConfig/)

- [#/components/schemas/ContainerCreateResponse](/reference/api/engine/version/v1.57/schemas/ContainerCreateResponse/)

- [#/components/schemas/ErrorResponse](/reference/api/engine/version/v1.57/schemas/ErrorResponse/)

- [#/components/schemas/HostConfig](/reference/api/engine/version/v1.57/schemas/HostConfig/)

- [#/components/schemas/NetworkingConfig](/reference/api/engine/version/v1.57/schemas/NetworkingConfig/)




