---
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` integer
- `shmsize` integer
- `squash` boolean
- `labels` string
- `networkmode` string

## 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/docker/apis/engine.md) · [All operations](https://skmtc.net/docker/apis/engine/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/docker/engine/versions/400730735b03/schema)