# Build an image


[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 /build`

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.


## 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/octet-stream' \
  --data-binary @request-body \
  'http://localhost/v1.57/build'
```


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


## Parameters

### dockerfile

Location: query. Required: no.

Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.

```json
{
  "description": "Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.",
  "in": "query",
  "name": "dockerfile",
  "pointer": "/paths/~1build/post/parameters/0",
  "schema": {
    "default": "Dockerfile",
    "type": "string"
  }
}
```

### t

Location: query. Required: no.

A name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.

```json
{
  "description": "A name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.",
  "in": "query",
  "name": "t",
  "pointer": "/paths/~1build/post/parameters/1",
  "schema": {
    "type": "string"
  }
}
```

### extrahosts

Location: query. Required: no.

Extra hosts to add to /etc/hosts

```json
{
  "description": "Extra hosts to add to /etc/hosts",
  "in": "query",
  "name": "extrahosts",
  "pointer": "/paths/~1build/post/parameters/2",
  "schema": {
    "type": "string"
  }
}
```

### remote

Location: query. Required: no.

A Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.

```json
{
  "description": "A Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.",
  "in": "query",
  "name": "remote",
  "pointer": "/paths/~1build/post/parameters/3",
  "schema": {
    "type": "string"
  }
}
```

### q

Location: query. Required: no.

Suppress verbose build output.

```json
{
  "description": "Suppress verbose build output.",
  "in": "query",
  "name": "q",
  "pointer": "/paths/~1build/post/parameters/4",
  "schema": {
    "default": false,
    "type": "boolean"
  }
}
```

### nocache

Location: query. Required: no.

Do not use the cache when building the image.

```json
{
  "description": "Do not use the cache when building the image.",
  "in": "query",
  "name": "nocache",
  "pointer": "/paths/~1build/post/parameters/5",
  "schema": {
    "default": false,
    "type": "boolean"
  }
}
```

### cachefrom

Location: query. Required: no.

JSON array of images used for build cache resolution.

```json
{
  "description": "JSON array of images used for build cache resolution.",
  "in": "query",
  "name": "cachefrom",
  "pointer": "/paths/~1build/post/parameters/6",
  "schema": {
    "type": "string"
  }
}
```

### pull

Location: query. Required: no.

Attempt to pull the image even if an older image exists locally.

```json
{
  "description": "Attempt to pull the image even if an older image exists locally.",
  "in": "query",
  "name": "pull",
  "pointer": "/paths/~1build/post/parameters/7",
  "schema": {
    "type": "string"
  }
}
```

### rm

Location: query. Required: no.

Remove intermediate containers after a successful build.

```json
{
  "description": "Remove intermediate containers after a successful build.",
  "in": "query",
  "name": "rm",
  "pointer": "/paths/~1build/post/parameters/8",
  "schema": {
    "default": true,
    "type": "boolean"
  }
}
```

### forcerm

Location: query. Required: no.

Always remove intermediate containers, even upon failure.

```json
{
  "description": "Always remove intermediate containers, even upon failure.",
  "in": "query",
  "name": "forcerm",
  "pointer": "/paths/~1build/post/parameters/9",
  "schema": {
    "default": false,
    "type": "boolean"
  }
}
```

### memory

Location: query. Required: no.

Set memory limit for build.

```json
{
  "description": "Set memory limit for build.",
  "in": "query",
  "name": "memory",
  "pointer": "/paths/~1build/post/parameters/10",
  "schema": {
    "format": "int64",
    "type": "integer"
  }
}
```

### memswap

Location: query. Required: no.

Total memory (memory + swap). Set as `-1` to disable swap.

```json
{
  "description": "Total memory (memory + swap). Set as `-1` to disable swap.",
  "in": "query",
  "name": "memswap",
  "pointer": "/paths/~1build/post/parameters/11",
  "schema": {
    "format": "int64",
    "type": "integer"
  }
}
```

### cpushares

Location: query. Required: no.

CPU shares (relative weight).

```json
{
  "description": "CPU shares (relative weight).",
  "in": "query",
  "name": "cpushares",
  "pointer": "/paths/~1build/post/parameters/12",
  "schema": {
    "format": "int64",
    "type": "integer"
  }
}
```

### cpusetcpus

Location: query. Required: no.

CPUs in which to allow execution (e.g., `0-3`, `0,1`).

```json
{
  "description": "CPUs in which to allow execution (e.g., `0-3`, `0,1`).",
  "in": "query",
  "name": "cpusetcpus",
  "pointer": "/paths/~1build/post/parameters/13",
  "schema": {
    "type": "string"
  }
}
```

### cpuperiod

Location: query. Required: no.

The length of a CPU period in microseconds.

```json
{
  "description": "The length of a CPU period in microseconds.",
  "in": "query",
  "name": "cpuperiod",
  "pointer": "/paths/~1build/post/parameters/14",
  "schema": {
    "format": "int64",
    "type": "integer"
  }
}
```

### cpuquota

Location: query. Required: no.

Microseconds of CPU time that the container can get in a CPU period.

```json
{
  "description": "Microseconds of CPU time that the container can get in a CPU period.",
  "in": "query",
  "name": "cpuquota",
  "pointer": "/paths/~1build/post/parameters/15",
  "schema": {
    "format": "int64",
    "type": "integer"
  }
}
```

### buildargs

Location: query. Required: no.

JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.

For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.

[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)


```json
{
  "description": "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.\n\nFor example, the build arg `FOO=bar` would become `{\"FOO\":\"bar\"}` in JSON. This would result in the query parameter `buildargs={\"FOO\":\"bar\"}`. Note that `{\"FOO\":\"bar\"}` should be URI component encoded.\n\n[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)\n",
  "in": "query",
  "name": "buildargs",
  "pointer": "/paths/~1build/post/parameters/16",
  "schema": {
    "type": "string"
  }
}
```

### shmsize

Location: query. Required: no.

Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.

```json
{
  "description": "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.",
  "in": "query",
  "name": "shmsize",
  "pointer": "/paths/~1build/post/parameters/17",
  "schema": {
    "format": "int64",
    "type": "integer"
  }
}
```

### squash

Location: query. Required: no.

Squash the resulting images layers into a single layer. *(Experimental release only.)*

```json
{
  "description": "Squash the resulting images layers into a single layer. *(Experimental release only.)*",
  "in": "query",
  "name": "squash",
  "pointer": "/paths/~1build/post/parameters/18",
  "schema": {
    "type": "boolean"
  }
}
```

### labels

Location: query. Required: no.

Arbitrary key/value labels to set on the image, as a JSON map of string pairs.

```json
{
  "description": "Arbitrary key/value labels to set on the image, as a JSON map of string pairs.",
  "in": "query",
  "name": "labels",
  "pointer": "/paths/~1build/post/parameters/19",
  "schema": {
    "type": "string"
  }
}
```

### networkmode

Location: query. Required: no.

Sets the networking mode for the run commands during build. Supported
standard values are: `bridge`, `host`, `none`, and `container:<name|id>`.
Any other value is taken as a custom network's name or ID to which this
container should connect to.


```json
{
  "description": "Sets the networking mode for the run commands during build. Supported\nstandard values are: `bridge`, `host`, `none`, and `container:\u003cname|id\u003e`.\nAny other value is taken as a custom network's name or ID to which this\ncontainer should connect to.\n",
  "in": "query",
  "name": "networkmode",
  "pointer": "/paths/~1build/post/parameters/20",
  "schema": {
    "type": "string"
  }
}
```

### X-Registry-Config

Location: header. Required: no.

This is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.

The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](/reference/api/engine/version/v1.57/#authentication). For example:

```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```

Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API.


```json
{
  "description": "This is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.\n\nThe key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:\n\n```\n{\n  \"docker.example.com\": {\n    \"username\": \"janedoe\",\n    \"password\": \"hunter2\"\n  },\n  \"https://index.docker.io/v1/\": {\n    \"username\": \"mobydock\",\n    \"password\": \"conta1n3rize14\"\n  }\n}\n```\n\nOnly the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API.\n",
  "in": "header",
  "name": "X-Registry-Config",
  "pointer": "/paths/~1build/post/parameters/21",
  "schema": {
    "type": "string"
  }
}
```

### platform

Location: query. Required: no.

Platform in the format os[/arch[/variant]]

```json
{
  "description": "Platform in the format os[/arch[/variant]]",
  "in": "query",
  "name": "platform",
  "pointer": "/paths/~1build/post/parameters/22",
  "schema": {
    "default": "",
    "type": "string"
  }
}
```

### target

Location: query. Required: no.

Target build stage

```json
{
  "description": "Target build stage",
  "in": "query",
  "name": "target",
  "pointer": "/paths/~1build/post/parameters/23",
  "schema": {
    "default": "",
    "type": "string"
  }
}
```

### outputs

Location: query. Required: no.

BuildKit output configuration in the format of a stringified JSON array of objects.
Each object must have two top-level properties: `Type` and `Attrs`.
The `Type` property must be set to 'moby'.
The `Attrs` property is a map of attributes for the BuildKit output configuration.
See https://docs.docker.com/build/exporters/oci-docker/ for more information.

Example:

```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```


```json
{
  "description": "BuildKit output configuration in the format of a stringified JSON array of objects.\nEach object must have two top-level properties: `Type` and `Attrs`.\nThe `Type` property must be set to 'moby'.\nThe `Attrs` property is a map of attributes for the BuildKit output configuration.\nSee https://docs.docker.com/build/exporters/oci-docker/ for more information.\n\nExample:\n\n```\n[{\"Type\":\"moby\",\"Attrs\":{\"type\":\"image\",\"force-compression\":\"true\",\"compression\":\"zstd\"}}]\n```\n",
  "in": "query",
  "name": "outputs",
  "pointer": "/paths/~1build/post/parameters/24",
  "schema": {
    "default": "",
    "type": "string"
  }
}
```

### version

Location: query. Required: no.

Version of the builder backend to use.

- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)


```json
{
  "description": "Version of the builder backend to use.\n\n- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)\n- `2` is [BuildKit](https://github.com/moby/buildkit)\n",
  "in": "query",
  "name": "version",
  "pointer": "/paths/~1build/post/parameters/25",
  "schema": {
    "default": "1",
    "enum": [
      "1",
      "2"
    ],
    "type": "string"
  }
}
```

## Request and responses

### Request  application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.


Schema:

```json
{
  "format": "binary",
  "type": "string"
}
```










### Request  application/x-tar

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.


Schema:

```json
{
  "format": "binary",
  "type": "string"
}
```










### Response 200 application/json

no error











### Response 400 application/json

Bad parameter


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
{
  "description": "Build an image from a tar archive with a `Dockerfile` in it.\n\nThe `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).\n\nThe Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.\n\nThe build is canceled if the client drops the connection by quitting or being killed.\n",
  "operationId": "ImageBuild",
  "parameters": [
    {
      "description": "Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.",
      "in": "query",
      "name": "dockerfile",
      "schema": {
        "default": "Dockerfile",
        "type": "string"
      }
    },
    {
      "description": "A name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.",
      "in": "query",
      "name": "t",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Extra hosts to add to /etc/hosts",
      "in": "query",
      "name": "extrahosts",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "A Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.",
      "in": "query",
      "name": "remote",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Suppress verbose build output.",
      "in": "query",
      "name": "q",
      "schema": {
        "default": false,
        "type": "boolean"
      }
    },
    {
      "description": "Do not use the cache when building the image.",
      "in": "query",
      "name": "nocache",
      "schema": {
        "default": false,
        "type": "boolean"
      }
    },
    {
      "description": "JSON array of images used for build cache resolution.",
      "in": "query",
      "name": "cachefrom",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Attempt to pull the image even if an older image exists locally.",
      "in": "query",
      "name": "pull",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Remove intermediate containers after a successful build.",
      "in": "query",
      "name": "rm",
      "schema": {
        "default": true,
        "type": "boolean"
      }
    },
    {
      "description": "Always remove intermediate containers, even upon failure.",
      "in": "query",
      "name": "forcerm",
      "schema": {
        "default": false,
        "type": "boolean"
      }
    },
    {
      "description": "Set memory limit for build.",
      "in": "query",
      "name": "memory",
      "schema": {
        "format": "int64",
        "type": "integer"
      }
    },
    {
      "description": "Total memory (memory + swap). Set as `-1` to disable swap.",
      "in": "query",
      "name": "memswap",
      "schema": {
        "format": "int64",
        "type": "integer"
      }
    },
    {
      "description": "CPU shares (relative weight).",
      "in": "query",
      "name": "cpushares",
      "schema": {
        "format": "int64",
        "type": "integer"
      }
    },
    {
      "description": "CPUs in which to allow execution (e.g., `0-3`, `0,1`).",
      "in": "query",
      "name": "cpusetcpus",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "The length of a CPU period in microseconds.",
      "in": "query",
      "name": "cpuperiod",
      "schema": {
        "format": "int64",
        "type": "integer"
      }
    },
    {
      "description": "Microseconds of CPU time that the container can get in a CPU period.",
      "in": "query",
      "name": "cpuquota",
      "schema": {
        "format": "int64",
        "type": "integer"
      }
    },
    {
      "description": "JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.\n\nFor example, the build arg `FOO=bar` would become `{\"FOO\":\"bar\"}` in JSON. This would result in the query parameter `buildargs={\"FOO\":\"bar\"}`. Note that `{\"FOO\":\"bar\"}` should be URI component encoded.\n\n[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)\n",
      "in": "query",
      "name": "buildargs",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.",
      "in": "query",
      "name": "shmsize",
      "schema": {
        "format": "int64",
        "type": "integer"
      }
    },
    {
      "description": "Squash the resulting images layers into a single layer. *(Experimental release only.)*",
      "in": "query",
      "name": "squash",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "description": "Arbitrary key/value labels to set on the image, as a JSON map of string pairs.",
      "in": "query",
      "name": "labels",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Sets the networking mode for the run commands during build. Supported\nstandard values are: `bridge`, `host`, `none`, and `container:\u003cname|id\u003e`.\nAny other value is taken as a custom network's name or ID to which this\ncontainer should connect to.\n",
      "in": "query",
      "name": "networkmode",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "This is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.\n\nThe key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:\n\n```\n{\n  \"docker.example.com\": {\n    \"username\": \"janedoe\",\n    \"password\": \"hunter2\"\n  },\n  \"https://index.docker.io/v1/\": {\n    \"username\": \"mobydock\",\n    \"password\": \"conta1n3rize14\"\n  }\n}\n```\n\nOnly the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API.\n",
      "in": "header",
      "name": "X-Registry-Config",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Platform in the format os[/arch[/variant]]",
      "in": "query",
      "name": "platform",
      "schema": {
        "default": "",
        "type": "string"
      }
    },
    {
      "description": "Target build stage",
      "in": "query",
      "name": "target",
      "schema": {
        "default": "",
        "type": "string"
      }
    },
    {
      "description": "BuildKit output configuration in the format of a stringified JSON array of objects.\nEach object must have two top-level properties: `Type` and `Attrs`.\nThe `Type` property must be set to 'moby'.\nThe `Attrs` property is a map of attributes for the BuildKit output configuration.\nSee https://docs.docker.com/build/exporters/oci-docker/ for more information.\n\nExample:\n\n```\n[{\"Type\":\"moby\",\"Attrs\":{\"type\":\"image\",\"force-compression\":\"true\",\"compression\":\"zstd\"}}]\n```\n",
      "in": "query",
      "name": "outputs",
      "schema": {
        "default": "",
        "type": "string"
      }
    },
    {
      "description": "Version of the builder backend to use.\n\n- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)\n- `2` is [BuildKit](https://github.com/moby/buildkit)\n",
      "in": "query",
      "name": "version",
      "schema": {
        "default": "1",
        "enum": [
          "1",
          "2"
        ],
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/octet-stream": {
        "schema": {
          "format": "binary",
          "type": "string"
        }
      },
      "application/x-tar": {
        "schema": {
          "format": "binary",
          "type": "string"
        }
      }
    },
    "description": "A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.",
    "x-codegen-request-body-name": "inputStream"
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {}
      },
      "description": "no error"
    },
    "400": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Bad parameter"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "server error"
    }
  },
  "summary": "Build an image",
  "tags": [
    "Image"
  ]
}
```

## Referenced schemas

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




