---
title: "Build an image"
method: POST
path: "/build"
tags: ["Image"]
---

# Build an image

`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.

## Query parameters

- `dockerfile` string
- `t` string
- `extrahosts` string
- `remote` string
- `q` boolean
- `nocache` boolean
- `cachefrom` string
- `pull` string
- `rm` boolean
- `forcerm` boolean
- `memory` integer
- `memswap` integer
- `cpushares` integer
- `cpusetcpus` string
- `cpuperiod` integer
- `cpuquota` integer
- `buildargs` string
- `shmsize` integer
- `squash` boolean
- `labels` string
- `networkmode` string
- `platform` string
- `target` string
- `outputs` string
- `version` '1' | '2'

## Headers

- `Content-type` 'application/x-tar'
- `X-Registry-Config` string

## Response `200`

no error

## Other responses

- `400` — Bad parameter
- `500` — server error

---

[API](https://skmtc.net/chapar-rest/apis/docker-engine-api.md) · [All operations](https://skmtc.net/chapar-rest/apis/docker-engine-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/chapar-rest/docker-engine-api/versions/3a78a994dd0d/schema)