Build an image | Docker Engine API documentation

Build an image Run in API Explorer

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.

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.

Headers

Content-type string

Value is application/x-tar. Default value is application/x-tar.
X-Registry-Config string
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. 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.

Query parameters

dockerfile string

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

Default value is Dockerfile.
t string

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.
extrahosts string

Extra hosts to add to /etc/hosts
remote string

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.
q boolean

Suppress verbose build output.

Default value is false.
nocache boolean

Do not use the cache when building the image.

Default value is false.
cachefrom string

JSON array of images used for build cache resolution.
pull string

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

Remove intermediate containers after a successful build.

Default value is true.
forcerm boolean

Always remove intermediate containers, even upon failure.

Default value is false.
memory integer

Set memory limit for build.
memswap integer

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

CPU shares (relative weight).
cpusetcpus string

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

The length of a CPU period in microseconds.
cpuquota integer

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

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.
shmsize integer

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

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

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

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.
platform string

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

Default value is empty.
target string

Target build stage

Default value is empty.
outputs string

BuildKit output configuration

Default value is empty.
version string
Version of the builder backend to use.
- 1 is the first generation classic (deprecated) builder in the Docker daemon (default)
- 2 is BuildKit
Values are 1 or 2. Default value is 1.

application/octet-stream

Body

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

string(binary)

Responses

200

no error
400 application/json

Bad parameter
Hide response attribute Show response attribute object
- message string Required
  
  The error message.
500 application/json

server error
Hide response attribute Show response attribute object
- message string Required
  
  The error message.

POST /build

curl \
 --request POST 'http://api.example.com/v1.49/build' \
 --header "Content-type: application/x-tar" \
 --header "X-Registry-Config: string" \
 --data-binary '@file'

Response examples (400)

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

Response examples (400)

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

Response examples (500)

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

Response examples (500)

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