# How to Build the apple/container Project: Complete Guide for Apple Silicon

> Learn how to build the apple/container project on Apple Silicon. Follow this complete guide, run make clean all after setup, and get started with your project today.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-30

---

**Build the apple/container project on Apple silicon by running `make clean all` in the cloned repository after verifying Xcode 26 is set as the active developer directory.**

The `apple/container` repository provides a Swift-based command-line tool that runs OCI-compatible Linux containers on Apple-silicon Macs. Built with the Swift Package Manager (SPM), this project requires specific macOS and Xcode versions to compile the runtime services and CLI binary. This guide covers the complete build process from environment preparation to system-wide installation, based on the source structure defined in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) and the build automation in `Makefile`.

## Prerequisites for Building apple/container

### Hardware and Operating System Requirements

Building the `apple/container` project requires Apple silicon (ARM64) hardware and macOS 15 or newer, with macOS 26 recommended for full compatibility. Verify your architecture and OS version with:

```bash
uname -m
sw_vers -productVersion

```

The `vmnet` framework used for container networking may fail if you place the repository under `~/Documents` or `~/Desktop` on macOS 26. Clone the source to a path like `~/projects/container` to avoid this limitation, as documented in [`BUILDING.md`](https://github.com/apple/container/blob/main/BUILDING.md).

### Development Tools and Xcode Configuration

You must install Xcode 26 or later and set it as the active developer directory. The project declares Swift 6.2 in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift), which ships with Xcode 26:

```bash
xcode-select --switch /Applications/Xcode.app
xcode-select -p
swift --version  # Should report "Swift version 6.2"

```

## Clone and Prepare the Repository

Clone the repository from GitHub and navigate to the project root:

```bash
git clone https://github.com/apple/container.git
cd container

```

The repository structure includes:
- `Sources/` – Swift source code for the CLI and services
- `Tests/` – Unit and integration tests
- `docs/` – Technical documentation including [`technical-overview.md`](https://github.com/apple/container/blob/main/technical-overview.md)

## Build, Test, and Install

### Debug Build and Test Suite

Compile the debug version and validate functionality with the full test suite:

```bash
make clean
rm -rf test-data
make APP_ROOT=test-data all test integration

```

The `make all` command compiles the `container` binary and helper services into `bin/` and `libexec/`. The `make test` target runs unit tests, while `make integration` executes integration tests that exercise the full container stack against an isolated data directory.

### Release Build Configuration

For production-grade performance, build with release optimizations:

```bash
BUILD_CONFIGURATION=release make clean all test integration

```

Release builds strip debug symbols and enable compiler optimizations that improve the runtime performance of the `container-runtime-linux` and `container-network-vmnet` services.

### Generate Protobuf Stubs

If you modify the builder API, regenerate the gRPC Swift code:

```bash
make protos

```

This invokes the `grpc-swift` compiler via rules defined in `Protobuf.Makefile` to process the protocol buffer definitions from the `container-builder-shim` project.

### Install System-Wide Binaries

Install the compiled binaries to system directories using:

```bash
sudo make install

```

This copies:
- `bin/container` → `/usr/local/bin/container`
- Helper services (e.g., `container-runtime-linux`, `container-network-vmnet`) → `/usr/local/libexec/`

After installation, start the system daemon:

```bash
container system start

```

## Optional Development Workflows

### Local containerization Package Development

To develop against a local copy of the `containerization` dependency instead of the remote version:

1. Clone `containerization` adjacent to the `container` directory:
   ```bash
   cd ..
   git clone https://github.com/apple/containerization.git
   ```

2. Edit [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) (lines 56-57) to replace the versioned dependency:
   ```swift
   // Replace this:
   .package(url: "https://github.com/apple/containerization.git", exact: Version(stringLiteral: scVersion)),
   
   // With this:
   .package(path: "../containerization"),
   ```

3. Update the package resolution and rebuild:
   ```bash
   swift package update containerization
   make clean all
   bin/container system stop
   bin/container system start
   ```

### Custom Builder Shim Configuration

To test changes in the `container-builder-shim` project:

1. Clone and build the shim:
   ```bash
   git clone https://github.com/apple/container-builder-shim.git
   cd container-builder-shim
   container build -t builder .
   container rm -f buildkit
   ```

2. Configure the `container` tool to use your custom image by adding to `~/.config/container/config.toml`:
   ```toml
   [build]
   image = "builder:latest"
   ```

3. Run `container build` commands normally; the tool will use your local builder image instead of the default.

### Debug XPC Helpers

To attach a debugger to XPC services like `com.apple.container.container-runtime-linux.test`, set the environment variable before restarting the daemon:

```bash
export CONTAINER_DEBUG_LAUNCHD_LABEL=com.apple.container.container-runtime-linux.test
container system start

```

## Summary

- **Hardware requirement**: Apple silicon (ARM64) with macOS 15+ (macOS 26 recommended) is mandatory for building `apple/container`.
- **Build command**: `make clean all` creates debug binaries, while `BUILD_CONFIGURATION=release make clean all` creates optimized releases.
- **Installation**: `make install` copies the `container` CLI and services to `/usr/local/bin` and `/usr/local/libexec`.
- **Service management**: Use `container system start` to launch the daemon after installation.
- **Local development**: Edit [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) to point to a local `containerization` checkout via `.package(path: "../containerization")`.
- **Protobuf generation**: Run `make protos` after modifying the builder API to regenerate gRPC stubs.
- **Key source files**: [`Sources/CLI/main.swift`](https://github.com/apple/container/blob/main/Sources/CLI/main.swift) provides the entry point, while [`Sources/ContainerBuild/Builder.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift) handles the gRPC communication with the builder shim.

## Frequently Asked Questions

### What macOS version is required to build the apple/container project?

You need macOS 15 or newer to compile the project, though macOS 26 is recommended for full compatibility with the `vmnet` networking framework. The build process will fail on older versions due to dependencies on modern Apple frameworks and Swift 6.2 toolchain features.

### How do I generate protobuf stubs after modifying the builder API?

Run `make protos` from the repository root. This executes the `Protobuf.Makefile` rules that invoke `grpc-swift` on the `.proto` files from the `container-builder-shim` project, updating the generated Swift code in the `Sources/` directory.

### Can I build the apple/container project on Intel Macs?

No. The `apple/container` project exclusively supports Apple silicon (ARM64) hardware. The codebase relies on ARM64-specific virtualization frameworks and the `vmnet` implementation that are only available on Apple silicon Macs, as reflected in the platform requirements in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift).

### Where are the compiled binaries installed?

The `make install` command copies the `container` binary to `/usr/local/bin/` and helper services (such as `container-runtime-linux` and `container-network-vmnet`) to `/usr/local/libexec/`. These paths allow the system-wide `container` service to locate and execute the XPC helpers when you run `container system start`.