# What Is the Containerization Swift Package? A Deep Dive into Apple's Container Runtime Library

> Explore Apple's Containerization Swift package, the core library for image handling, OCI specs, process spawning & filesystem mounts to build and run containers on macOS and Linux.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: deep-dive
- Published: 2026-06-25

---

**The Containerization Swift package is Apple's foundational library that provides low-level container runtime primitives—including image handling, OCI specifications, process spawning, and filesystem mounts—used throughout the apple/container repository to power container building and execution on macOS and Linux.**

The Containerization Swift package serves as the bedrock of Apple's open-source container ecosystem within the `apple/container` repository. This dependency provides the essential data structures, error handling, and platform abstractions that higher-level modules like `ContainerBuild` and `ContainerRuntimeClient` rely on to manage container lifecycles across Darwin and Linux kernels.

## Location and Version Pinning

The Containerization Swift package is maintained in a separate repository at [apple/containerization](https://github.com/apple/containerization) and imported as a dependency. In [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) at lines 55-57, the dependency is declared, while lines 25-27 pin the exact version using `scVersion = "0.34.0"`:

```swift
// Package.swift lines 25-27
let scVersion = "0.34.0"

// Package.swift lines 55-57
.package(url: "https://github.com/apple/containerization", from: scVersion),

```

This version pinning ensures reproducible builds across the container toolchain.

## Exported Modules and Architecture

The package exposes five primary Swift modules that separate concerns across the container stack:

- **Containerization**: Core data structures and runtime primitives
- **ContainerizationOCI**: OCI image specification and registry handling
- **ContainerizationOS**: Platform-specific abstractions for macOS
- **ContainerizationExtras**: Extended utilities for Linux-specific features
- **ContainerizationArchive**: Tar and compression utilities

These modules appear throughout the codebase, such as in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) (lines 23-27) where both `Containerization` and `ContainerizationOCI` are imported, and in `Sources/TerminalProgress/ProgressBar+Terminal.swift` (line 17) which imports `ContainerizationOS`.

## Core Data Types for Container Configuration

The library defines immutable data structures that model container configuration. Three critical types handle filesystem mounts, process execution, and security capabilities.

### Mount Specifications

The `Containerization.Mount` struct defines bind mounts and volume mappings. In [`Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift) (line 18) and [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) (line 134), this type configures how host directories attach to container namespaces:

```swift
import Containerization

// Define a bind-mount from host path to container path
let mount = Containerization.Mount(
    source: FilePath("/Users/me/data"),
    destination: FilePath("/app/data"),
    options: [.readOnly, .exec]
)

// Add the mount to a container configuration
var process = Containerization.Process()
process.mounts.append(mount)

```

### Process Configuration

The `Containerization.Process` struct encapsulates command execution context, working directories, and environment variables. This type serves as the primary interface for spawning containerized workloads.

### Linux Capabilities

Security contexts are managed through `Containerization.LinuxCapabilities`, which computes effective capability sets. The implementation in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) (lines 1174-1199) handles the translation between human-readable capability names and kernel bitmasks:

```swift
import Containerization

// Compute the effective set of capabilities for a container
let extraCaps = ["CAP_NET_ADMIN", "CAP_SYS_TIME"]
let dropCaps = ["CAP_SETUID"]
let effective = try Containerization.LinuxCapabilities.effectiveCapabilities(
    capAdd: extraCaps,
    capDrop: dropCaps
)

// Apply to a process configuration
var proc = Containerization.Process()
proc.linuxCapabilities = effective

```

## Error Handling with ContainerizationError

Runtime failures are wrapped in `ContainerizationError`, a custom error type that signals invalid arguments, state violations, or unsupported operations. Throughout the runtime services—such as at line 149 in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift)—errors are thrown using this unified type:

```swift
import Containerization
import ContainerizationError

do {
    // Attempt to start a container process
    try runtime.start(process: proc)
} catch let err as ContainerizationError {
    // Provide a detailed error message
    print("Failed to start container: \(err.message)")
}

```

## Cross-Platform Abstraction

The package abstracts platform differences through conditional compilation. On macOS, the `ContainerizationOS` layer interfaces with Darwin-specific APIs, while on Linux, the `ContainerizationExtras` and `ContainerizationOCI` layers map directly to kernel features like cgroups and namespaces. This architecture allows the `apple/container` repository to maintain a single codebase supporting both operating systems.

## OCI Image Handling

The `ContainerizationOCI` module handles Open Container Initiative (OCI) format images. In [`Sources/ContainerBuild/BuildPipelineHandler.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildPipelineHandler.swift) (line 52) and [`Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift) (line 18), this module parses image manifests and layer tarballs:

```swift
import ContainerizationOCI

let image = try OCIImage.fromFile(FilePath("/var/lib/containers/myimage.tar"))
print("Image ID: \(image.id)")

```

## Integration with Higher-Level APIs

While the Containerization Swift package provides low-level primitives, higher modules consume these through specialized clients. The `ContainerBuild` module in [`Sources/ContainerBuild/Builder.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift) (lines 1-30) demonstrates this pattern:

```swift
import ContainerBuild
import Containerization

let builder = Builder(
    sourceRoot: FilePath("/path/to/project"),
    imageName: "myapp:latest"
)

// Add a Dockerfile or BuildKit file
builder.addDockerfile(FilePath("/path/to/Dockerfile"))

// Run the build
try builder.build()

```

## Summary

- The **Containerization Swift package** is a version-pinned dependency (0.34.0) hosted at `apple/containerization` that provides low-level container runtime primitives.
- It exports five specialized modules: `Containerization`, `ContainerizationOCI`, `ContainerizationOS`, `ContainerizationExtras`, and `ContainerizationArchive`.
- Core types include `Containerization.Mount`, `Containerization.Process`, and `Containerization.LinuxCapabilities` for configuring container execution contexts.
- Errors are uniformly handled through `ContainerizationError`, implemented throughout the runtime services.
- The package abstracts platform differences between macOS and Linux, enabling cross-platform container management.

## Frequently Asked Questions

### What version of the Containerization Swift package does apple/container use?

The repository pins version **0.34.0** as defined by the `scVersion` constant in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) at lines 25-27. This specific version is imported as a package dependency at lines 55-57, ensuring consistent behavior across the container toolchain.

### How does the Containerization Swift package handle errors?

The package defines `ContainerizationError`, a custom error type that represents invalid arguments, state violations, and unsupported operations. Runtime services throughout the codebase throw this error type—for example, at line 149 in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift)—allowing callers to catch and handle container-specific failures uniformly.

### Which modules are exposed by the Containerization Swift package?

The package exposes five primary modules: **Containerization** (core primitives), **ContainerizationOCI** (OCI image specifications), **ContainerizationOS** (macOS platform layer), **ContainerizationExtras** (Linux-specific utilities), and **ContainerizationArchive** (compression and archiving). These modules are imported throughout the codebase, such as in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) and `ProgressBar+Terminal.swift`.

### Can the Containerization Swift package be used independently of the apple/container repository?

Yes, the package is developed independently in the `apple/containerization` repository and can be imported into any Swift project requiring low-level container runtime primitives. It provides the foundational APIs for image handling, process spawning, and filesystem mounts that any container toolset could leverage, though it is primarily designed to support the `ContainerBuild` and `ContainerRuntimeClient` modules within Apple's container ecosystem.