# How to Build an OCI Image from a Dockerfile Using Apple Container > Learn to build an OCI image from a Dockerfile using Apple Container. Compile your Dockerfile with container build for a standards-compliant OCI image. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-05 --- **Use the `container build` command to compile a Dockerfile into a standards-compliant OCI image by running the build inside a lightweight isolation VM, then tag the output with `-t` for local storage or registry pushes.** Apple Container provides a secure, virtualization-based workflow for converting Dockerfiles into OCI-compliant images on macOS and Linux. The `container build` command orchestrates this process by spawning a dedicated builder virtual machine (VM) that handles layer compilation without affecting your host system or requiring Docker Desktop. ## Understanding the Builder VM Architecture When you invoke `container build`, the Apple Container CLI automatically provisions a **builder VM** if one is not already running. This architecture is documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) and [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md). The builder VM isolates the entire build process inside a lightweight virtualized environment. By default, the VM is provisioned with **2 GiB of RAM** and **2 CPUs**, though you can adjust these resources to match your build complexity. The VM runs a container-based build engine that reads your build context, processes Dockerfile instructions, and assembles the final image layers. ### OCI-Compliant Image Generation Inside the builder VM, the build engine tar-packs your build context (the directory you specify) and streams it into a Docker daemon running within the VM. This daemon executes each Dockerfile instruction—creating layers according to OCI specifications—and assembles an OCI-compliant image manifest. The resulting image is stored in the local container image store and can be referenced by the tag you provide during the build process. ## Managing the Builder VM Lifecycle While the builder VM starts automatically when you run `container build`, you can manage it explicitly for resource-intensive projects. ### Starting a Custom Builder VM To provision a builder with more resources before building, use `container builder start` as described in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md): ```bash container builder start --cpus 8 --memory 32g ``` This creates a high-performance build environment suitable for large compilation tasks or multi-stage builds. ### Stopping the Builder VM When you have finished building images, shut down the VM to reclaim system resources: ```bash container builder stop ``` ## Building Your First OCI Image The simplest workflow requires only a single command from your project directory containing a `Dockerfile`: ```bash container build --tag my-app:latest . ``` This command: 1. Starts the builder VM (if not running) 2. Streams the current directory (`.`) as the build context 3. Processes the `Dockerfile` found in the root of that context 4. Tags the resulting OCI image as `my-app:latest` in the local store ### Using Custom Dockerfile Locations If your Dockerfile uses a non-standard name or resides in a subdirectory, specify it with the `-f` or `--file` flag: ```bash container build -f Dockerfile.prod -t my-app:prod . ``` You can apply multiple tags to a single build output by repeating the `-t` flag: ```bash container build \ -f Dockerfile.prod \ -t my-app:prod \ -t my-app:1.0.0 \ . ``` ## Advanced Build Options Apple Container supports several flags to fine-tune the build process, documented in `docs/command-reference.md#container-build`: ### Multi-Architecture Builds Build for multiple CPU architectures (such as `arm64` and `amd64`) simultaneously using the `--arch` flag. The builder automatically configures the appropriate cross-compilation environment as detailed in `docs/how-to.md#multi-arch-builds`: ```bash container build \ --arch arm64 \ --arch amd64 \ -t registry.example.com/my-app:latest \ -f Dockerfile . ``` ### Build-Time Variables and Caching Pass build arguments to your Dockerfile using `--build-arg`: ```bash container build --build-arg VERSION=1.0.0 -t my-app:latest . ``` Disable layer caching for reproducible clean builds with `--no-cache`: ```bash container build --no-cache -t my-app:latest . ``` ### Debugging and Multi-Stage Targets Build up to a specific stage in a multi-stage Dockerfile using `--target`, or enable verbose output for troubleshooting with `--debug`: ```bash container build --target builder --debug -t my-app:builder . ``` ## Summary - **`container build`** is the primary command for converting Dockerfiles into OCI images using Apple Container. - The command runs inside a **builder VM** that isolates the build process and defaults to 2 GiB RAM and 2 CPUs. - Control VM resources explicitly using **`container builder start`** with `--cpus` and `--memory` flags. - Reference custom Dockerfiles with **`--file`** or **`-f`**, and apply multiple tags by repeating **`-t`**. - Build for multiple architectures using **`--arch`** flags for cross-platform distribution. - View complete option documentation in **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)**. ## Frequently Asked Questions ### How does Apple Container isolate the build process from my host system? According to the `apple/container` source code and [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md), the `container build` command spawns a lightweight "builder" VM that runs the build engine inside a virtualized environment. This VM isolates the Docker daemon and build context, ensuring that build processes cannot affect the host filesystem or security posture. ### Can I build OCI images for multiple architectures simultaneously? Yes. Pass the `--arch` flag multiple times to request builds for different architectures (e.g., `arm64` and `amd64`). The builder VM will provision the appropriate cross-compilation environments automatically, as implemented in the build engine referenced in `docs/how-to.md#multi-arch-builds`. ### Where is the built OCI image stored after the build completes? The resulting OCI-compliant image is stored in the **local container image store** maintained by Apple Container on your machine. You can reference it locally by the tag specified during build (e.g., `my-app:latest`), or push it to a remote registry using `container push `. ### How do I perform a clean build without using cached layers? Pass the `--no-cache` flag to `container build`. This instructs the builder VM to execute every Dockerfile instruction from scratch, ignoring any previously built layers, which is useful for reproducibility testing or debugging layer-related issues.