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

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 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 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 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 – SPM manifest defining dependencies like containerization, swift-argument-parser, and grpc-swift.

Clone and Prepare the Environment

Clone the repository and verify your environment:

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:

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:

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:

# 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:

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:

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:

   cd ..
   git clone https://github.com/apple/containerization.git

2. Edit Package.swift (lines 56-57) to replace the remote dependency with a local path:

   // 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:

   swift package update containerization
   make clean all

4. Restart services to pick up changes:

   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:

   git clone https://github.com/apple/container-builder-shim.git
   cd container-builder-shim

2. Build and register a custom builder image:

   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:

   [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:

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 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 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 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 utility script included in the repository, which handles upgrade and downgrade operations for system-wide installations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}