Search or ask Docker

Build an image

POST /build — Docker Engine API 1.57.

View Markdown
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.

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

dockerfile query

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

Type: string

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

t query

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.

Type: string

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

extrahosts query

Extra hosts to add to /etc/hosts

Type: string

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

remote query

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.

Type: string

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

q query

Suppress verbose build output.

Type: boolean

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

nocache query

Do not use the cache when building the image.

Type: boolean

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

cachefrom query

JSON array of images used for build cache resolution.

Type: string

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

pull query

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

Type: string

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

rm query

Remove intermediate containers after a successful build.

Type: boolean

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

forcerm query

Always remove intermediate containers, even upon failure.

Type: boolean

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

memory query

Set memory limit for build.

Type: integer

All schema constraints and annotations
{
  "format": "int64",
  "type": "integer"
}

memswap query

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

Type: integer

All schema constraints and annotations
{
  "format": "int64",
  "type": "integer"
}

cpushares query

CPU shares (relative weight).

Type: integer

All schema constraints and annotations
{
  "format": "int64",
  "type": "integer"
}

cpusetcpus query

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

Type: string

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

cpuperiod query

The length of a CPU period in microseconds.

Type: integer

All schema constraints and annotations
{
  "format": "int64",
  "type": "integer"
}

cpuquota query

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

Type: integer

All schema constraints and annotations
{
  "format": "int64",
  "type": "integer"
}

buildargs query

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.

Type: string

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

shmsize query

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

Type: integer

All schema constraints and annotations
{
  "format": "int64",
  "type": "integer"
}

squash query

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

Type: boolean

All schema constraints and annotations
{
  "type": "boolean"
}

labels query

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

Type: string

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

networkmode query

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.

Type: string

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

X-Registry-Config header

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.

Type: string

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

platform query

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

Type: string

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

target query

Target build stage

Type: string

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

outputs query

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"}}]

Type: string

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

version query

Version of the builder backend to use.

  • 1 is the first generation classic (deprecated) builder in the Docker daemon (default)
  • 2 is BuildKit

Type: string

All schema constraints and annotations
{
  "default": "1",
  "enum": [
    "1",
    "2"
  ],
  "type": "string"
}

Request and responses

Request

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

application/octet-stream

Type: string

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

Request

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

application/x-tar

Type: string

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

Response 200

no error

application/json

Response 400

Bad parameter

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/ErrorResponse

Complete operation contract
{
  "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"
  ]
}