Skip to main content
Builds an OCI image from a local build context. It reads a Dockerfile (default Dockerfile) or Containerfile and produces an image tagged with -t option. The build runs in isolation using BuildKit, and resource limits may be set for the build process itself. When no -f/--file is specified, the build command will look for Dockerfile first, then fall back to Containerfile if Dockerfile is not found.

​
Usage

container build [<options>] [<context-dir>]

​
Arguments

​
context-dir
string
default:"."
Build directory

​
Options

​
-a, --arch
string
Add the architecture type to the build
​
--build-arg
string
Set build-time variables (format: key=val)
​
-c, --cpus
number
default:"2"
Number of CPUs to allocate to the builder container
​
-f, --file
string
Path to Dockerfile
​
-l, --label
string
Set a label (format: key=val)
​
-m, --memory
string
default:"2048MB"
Amount of builder container memory (1MiByte granularity), with optional K, M, G, T, or P suffix
​
--no-cache
boolean
Do not use cache
​
-o, --output
string
default:"type=oci"
Output configuration for the build (format: type=<oci|tar|local>[,dest=])
​
--os
string
Add the OS type to the build
​
--platform
string
Add the platform to the build (format: os/arch[/variant], takes precedence over —os and —arch)
​
--progress
string
default:"auto"
Progress type (format: auto|plain|tty)
​
--pull
boolean
Pull latest image
​
-q, --quiet
boolean
Suppress build output
​
-t, --tag
string
Name for the built image (can be specified multiple times)
​
--target
string
Set the target build stage
​
--vsock-port
number
default:"8088"
Builder shim vsock port

​
Examples

# build an image and tag it as my-app:latest
container build -t my-app:latest .

# use a custom Dockerfile
container build -f docker/Dockerfile.prod -t my-app:prod .

# pass build args
container build --build-arg NODE_VERSION=18 -t my-app .

# build the production stage only and disable cache
container build --target production --no-cache -t my-app:prod .

# build with multiple tags
container build -t my-app:latest -t my-app:v1.0.0 -t my-app:stable .

Build docs developers (and LLMs) love

Get started for freeTalk to us