# How to Set Up a Development Environment for apple/container: Complete Guide

> Set up your apple/container development environment with this complete guide. Get started quickly on macOS 15+ with Xcode 26, Swift 6.2, and the cloned repository.

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

---

**To set up a development environment for apple/container, you need an Apple silicon Mac running macOS 15 or later, Xcode 26 with Swift 6.2, and the repository cloned alongside its sibling containerization package; then build using `make APP_ROOT=test-data all test integration`.**

The **apple/container** repository provides a Swift-based command-line tool that runs OCI-compatible containers as lightweight VM-based sandboxes on Apple silicon Macs. Setting up a local development environment requires specific hardware, toolchain versions, and a particular repository layout to handle the project's dependency on the separate **containerization** package. This guide covers the complete setup process from cloning to running your first container locally.

## Prerequisites

Before building apple/container, verify your system meets the following requirements defined in the repository's [`README.md`](https://github.com/apple/container/blob/main/README.md) and [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift):

- **Hardware:** Apple silicon (M1, M2, or later)
- **Operating System:** macOS 15 minimum; macOS 26 recommended
- **Xcode:** Version 26 set as the active developer directory
- **Swift:** Version 6.2 (declared in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift))
- **Tools:** `make`, `git`, and `bash` (standard on macOS)

Optional but recommended for advanced development: `protobuf`, `grpc`, and `swift-protobuf` via Homebrew if you plan to regenerate gRPC code.

## Clone the Repository and Dependencies

The `container` project depends on the **containerization** package (defined as a dependency in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift)). To work on both projects simultaneously or ensure compatibility, clone them side-by-side:

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

```

Your directory structure should look like this:

```

~/projects/
├── container/
└── containerization/

```

This layout is required because the build scripts in [`BUILDING.md`](https://github.com/apple/container/blob/main/BUILDING.md) assume the sibling directory structure when using `swift package edit` to develop against a local copy of the containerization code.

## Configure the Build Environment

Set Xcode 26 as your active developer directory and verify your Swift toolchain:

```bash
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
swift --version   # Should display Swift 6.2

```

No additional dependencies are required for a standard build, as the Swift Package Manager handles all Swift package resolution automatically via the [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) manifest.

## Build and Test the Project

The repository includes a `Makefile` that wraps the Swift Package Manager and provides standard development workflows. The recommended development build command is:

```bash
make APP_ROOT=test-data all test integration

```

This command:
- Sets `APP_ROOT=test-data` to isolate the services from real user data
- Builds all binaries into `bin/` and `libexec/` via the `all` target
- Runs unit tests via the `test` target
- Executes integration tests via the `integration` target

For a release-optimized build, use:

```bash
BUILD_CONFIGURATION=release make all

```

To install the binaries system-wide after building:

```bash
sudo make install

```

## Run the Container System Locally

After a successful build, start the container daemon:

```bash
bin/container system start

```

Verify the installation by running a test container:

```bash
bin/container run -d --name hello debian:bookworm echo "Hello, world!"

```

When finished testing, stop the system:

```bash
bin/container system stop

```

## Develop Using a Local Copy of Containerization

To modify low-level container primitives in the **containerization** package while working on **container**, you must point the main project to your local copy:

1. Edit [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) to replace the remote URL with a local path reference
2. Execute the Swift Package Manager edit commands:

```bash
/usr/bin/swift package edit --path ../containerization containerization
/usr/bin/swift package update containerization

```

3. Rebuild with `make clean all`

When finished, revert to the remote dependency by restoring the original [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) line or running `swift package unedit containerization`.

## Debugging and Code Quality Tools

The repository provides tools to maintain code quality and debug running services:

**Pre-commit Hooks:** Install git hooks that run `swift-format` and enforce license headers:

```bash
make pre-commit

```

**Debug XPC Helpers:** To debug the XPC helpers (such as the Linux runtime in `Sources/Plugins/RuntimeLinux/`), set the environment variable before starting:

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

```

This causes the helper to pause on launch, waiting for a debugger to attach, as documented in [`BUILDING.md`](https://github.com/apple/container/blob/main/BUILDING.md).

## Summary

- **Hardware Requirements:** Apple silicon Mac with macOS 15+ and Xcode 26
- **Repository Layout:** Clone both `container` and `containerization` side-by-side for local development
- **Build Command:** Use `make APP_ROOT=test-data all test integration` for development builds
- **Key Files:** Configuration lives in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift), build logic in `Makefile`, and detailed instructions in [`BUILDING.md`](https://github.com/apple/container/blob/main/BUILDING.md)
- **Local Development:** Use `swift package edit` to develop against local changes in the containerization dependency
- **Entry Point:** The CLI implementation is located in [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift)

## Frequently Asked Questions

### What hardware is required to build apple/container?

You must use an Apple silicon Mac (M1, M2, or later). The project builds and runs only on macOS, specifically version 15 or later, with macOS 26 recommended for full compatibility according to the [`README.md`](https://github.com/apple/container/blob/main/README.md) requirements section.

### Why do I need to clone the containerization repository separately?

The `container` project depends on the `containerization` package as defined in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift). While the package manager can fetch this automatically from the remote URL, cloning it locally allows you to modify low-level container primitives and test changes using `swift package edit`. The build scripts assume a side-by-side directory structure when working with local copies.

### How do I run the test suite after building?

Execute `make APP_ROOT=test-data test` for unit tests or `make APP_ROOT=test-data integration` for the integration test suite. The `APP_ROOT=test-data` parameter is critical as it forces the services to use an isolated test directory rather than touching real user data on your system.

### Can I contribute to the project without installing the Release version?

Yes. After building with `make all`, you can run the locally compiled binaries directly from the `bin/` directory without running `sudo make install`. Use `bin/container system start` to test your changes, and refer to `Sources/ContainerCommands/` for the implementation of commands like `run`, `build`, and `system`.