# How to Build the apple/container Project from Source: Complete macOS Guide

> Build the apple/container project from source on macOS. Follow this guide to clone, compile, test, and install binaries using Xcode on Apple silicon Macs.

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

---

**To build the apple/container project from source, clone the repository to an Apple silicon Mac running macOS 15 or newer, run `make clean all test integration` with Xcode 26 active, and install the binaries with `sudo make install`.**

The `apple/container` repository is Apple's Swift-based command-line tool for running OCI-compatible Linux containers on Apple silicon Macs. Building from source requires the Swift Package Manager (SPM) and a specific development environment configuration. This guide covers the complete build pipeline using the actual `Makefile` targets and [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) dependencies found in the repository.

## Prerequisites

### Hardware and Software Requirements

Building the apple/container project requires specific Apple hardware and development tools:

- **Apple silicon Mac** (arm64). Run `uname -m` to verify your architecture reports `arm64`.
- **macOS 15** (minimum) or macOS 26 (recommended). Check with `sw_vers -productVersion`.
- **Xcode 26** or later set as the active developer directory. Verify with `xcode-select -p` and ensure it points to your Xcode installation.
- **Swift 6.2** toolchain. The [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) file declares this version requirement; verify with `swift --version`.

**Important:** Avoid placing the repository under `~/Documents` or `~/Desktop` on macOS 26. The `vmnet` framework may fail to initialize from these paths. Instead, clone to a directory like `~/projects/container` as documented in the [`BUILDING.md`](https://github.com/apple/container/blob/main/BUILDING.md) file.

### Repository Structure

After cloning `https://github.com/apple/container.git`, the key directories include:

- `Sources/` – Swift source code for the CLI, services, and plugins.
- `Tests/` – Unit and integration tests executed by `make test`.
- `Makefile` – Convenience wrappers for SPM commands.
- [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) – SPM manifest defining dependencies like `containerization`, `swift-argument-parser`, and `grpc-swift`.

## Clone and Prepare the Environment

Clone the repository and verify your environment:

```bash
git clone https://github.com/apple/container.git
cd container
xcode-select --switch /Applications/Xcode.app

```

Ensure Xcode 26 is active before proceeding. The build system uses the active developer directory to locate the Swift compiler and macOS SDKs.

## Build the Project

### Debug Builds

Compile the debug version of the `container` binary and all helper services:

```bash
make clean all

```

The `make all` target compiles the `container` binary into `bin/` and helper services (such as `container-runtime-linux` and `container-network-vmnet`) into `libexec/`. The `make clean` step removes previous build artifacts to ensure a fresh compilation.

### Release Builds

For optimized production binaries, set the `BUILD_CONFIGURATION` environment variable:

```bash
BUILD_CONFIGURATION=release make clean all

```

**Release builds** enable compiler optimizations that improve runtime performance but increase compilation time. Use this configuration for system-wide installations.

### Running Tests

Execute the full test suite to verify the build:

```bash

# Run unit tests only

make test

# Run integration tests (requires isolated data directory)

rm -rf test-data
make APP_ROOT=test-data integration

# Run everything (clean build + test + integration)

make clean all test integration

```

The `make integration` target exercises the full container stack including runtime and networking components.

## Install System-Wide

Install the compiled binaries to `/usr/local`:

```bash
sudo make install

```

`make install` copies files to the following destinations:

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

After installation, start the system daemon:

```bash
container system start

```

Use `container system stop` to halt the services.

## Advanced: Local Development

### Linking Against Local containerization Package

To modify both `container` and the underlying `containerization` library simultaneously:

1. Clone `containerization` next 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 remote dependency with a local path:
   
   ```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
   ```

4. Restart services to pick up changes:
   
   ```bash
   bin/container system stop
   bin/container system start
   ```

### Using Local container-builder-shim

To test changes in the builder shim:

1. Clone the shim repository:
   
   ```bash
   git clone https://github.com/apple/container-builder-shim.git
   cd container-builder-shim
   ```

2. Build and register a custom builder image:
   
   ```bash
   container build -t builder .
   container rm -f buildkit
   ```

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

### Debugging XPC Helpers

To attach a debugger to XPC services, set the `CONTAINER_DEBUG_LAUNCHD_LABEL` environment variable before restarting the daemon:

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

```

This workflow is documented in the [`BUILDING.md`](https://github.com/apple/container/blob/main/BUILDING.md) file under the *Debug XPC Helpers* section.

## Summary

- **Prerequisites**: Apple silicon Mac, macOS 15+, Xcode 26, Swift 6.2 toolchain.
- **Build command**: `make clean all` for debug, or `BUILD_CONFIGURATION=release make clean all` for release.
- **Testing**: `make test` runs unit tests; `make integration` runs full stack tests.
- **Installation**: `sudo make install` copies binaries to `/usr/local/bin` and `/usr/local/libexec`.
- **Protobuf generation**: Run `make protos` after modifying builder API definitions.
- **Local development**: Edit [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) to use `.package(path: "../containerization")` for simultaneous library development.

## Frequently Asked Questions

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

You need **macOS 15** as the minimum version, though **macOS 26** is recommended according to the [`BUILDING.md`](https://github.com/apple/container/blob/main/BUILDING.md) documentation. The `vmnet` framework and other dependencies require recent macOS APIs only available in these versions.

### Can I build this project on an Intel Mac?

No. The `apple/container` project requires **Apple silicon** (arm64 architecture). The codebase depends on Apple silicon-specific frameworks and virtualization capabilities. Verify your architecture with `uname -m` before attempting to build.

### How do I regenerate the gRPC protobuf code?

Run `make protos` from the repository root. This invokes the `grpc-swift` compiler on the protocol buffer definitions in the `container-builder-shim` project. You only need to run this after modifying the builder API `.proto` files, as the generated Swift stubs are typically committed to the repository.

### Where are the binaries installed and how do I uninstall?

The `make install` command copies the `container` binary to `/usr/local/bin/container` and helper services to `/usr/local/libexec/`. To uninstall, manually remove these files or use the [`scripts/update-container.sh`](https://github.com/apple/container/blob/main/scripts/update-container.sh) utility script included in the repository, which handles upgrade and downgrade operations for system-wide installations.