# What Is the Containerization Swift Package in Apple's Container Tool?

> Discover how the Containerization Swift package powers container building execution and networking on macOS and Linux providing essential runtime primitives.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: internals
- Published: 2026-07-03

---

**The Containerization Swift package is Apple's core library that implements low-level container runtime primitives, providing the data structures, error handling, and OS abstractions that power container building, execution, and networking across macOS and Linux.**

The Containerization Swift package serves as the foundational dependency for the `apple/container` repository, supplying the essential APIs that higher-level modules rely on to manage container lifecycles. Pinned to version `0.34.0` in the repository's [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift), this external library abstracts platform-specific implementations into reusable Swift modules. It handles everything from OCI image specifications to Linux capability management, enabling the container tool to operate consistently across different operating systems.

## Core Responsibilities and Architecture

The Containerization Swift package provides the fundamental container APIs that sit beneath the tool's higher-level functionality. According to the source code in `apple/container`, this library supplies the primitives for image handling, OCI specifications, process spawning, filesystem mounts, and network configuration.

The dependency is declared in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) at line 55, where the repository imports the package from its external location at `https://github.com/apple/containerization`. The exact version used is pinned to `0.34.0` as specified in lines 25-27 of the same file, ensuring reproducible builds across development environments.

## Key Modules and Data Types

The package exports several distinct Swift modules that handle specific aspects of containerization. These modules appear throughout the codebase, demonstrating their integral role in the architecture.

### Containerization and ContainerizationOCI

The primary `Containerization` module exposes core data structures such as `Containerization.Mount`, `Containerization.Process`, and `Containerization.LinuxCapabilities`. These types are heavily referenced in runtime services—for example, `Containerization.Mount` appears at line 134 in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) and line 18 in [`Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift).

The `ContainerizationOCI` module handles OCI (Open Container Initiative) standards. In [`Sources/ContainerBuild/BuildPipelineHandler.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildPipelineHandler.swift) at line 52, and [`Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift) at line 18, the codebase imports this module to parse and manipulate OCI image formats.

### ContainerizationOS and Cross-Platform Abstraction

For platform-specific operations, the `ContainerizationOS` module abstracts operating system differences. On macOS, this layer provides the necessary interfaces, while on Linux it coordinates with `ContainerizationExtras` to map to underlying kernel features. This module is imported at line 17 in `Sources/TerminalProgress/ProgressBar+Terminal.swift`, demonstrating its use in terminal and OS-level operations.

### ContainerizationExtras and ContainerizationArchive

Additional specialized modules include `ContainerizationExtras` for extended functionality and `ContainerizationArchive` for handling compressed container images. These modules support the build pipeline and runtime persistence layers throughout the repository.

## Error Handling with ContainerizationError

The package defines `ContainerizationError` as a custom error type that signals invalid arguments, state violations, or unsupported operations. Throughout the runtime services, particularly in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift), the code throws `ContainerizationError` to handle failure conditions—such as at line 149 and throughout lines 1174-1199 where capability configuration errors are managed.

This centralized error type allows higher-level modules to catch and handle container-specific failures consistently, providing detailed error messages that aid in debugging runtime issues.

## Integration with Higher-Level Components

Higher-level modules within the `apple/container` repository import the Containerization Swift package directly to implement specific functionality:

- **ContainerBuild**: Uses the package's primitives to construct container images, referencing the `Builder` type defined in [`Sources/ContainerBuild/Builder.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift).
- **ContainerRuntimeClient**: Manages active containers using `Containerization.Process` and mount configurations.
- **ContainerNetworkServer**: Configures network interfaces using the package's networking abstractions.
- **ContainerPersistence**: Serializes and deserializes configuration data using the package's data structures.

The imports are visible throughout the service layer. For instance, [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) imports both `Containerization` and `ContainerizationOCI` at lines 23-27, while `Sources/TerminalProgress/ProgressBar+Terminal.swift` imports `ContainerizationOS` at line 17.

## Practical Usage Examples

Below are practical implementations demonstrating how the `apple/container` repository utilizes the Containerization Swift package.

### Creating a Mount Specification

```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)

```

*Source reference*: `Containerization.Mount` is referenced in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) (line 134) and [`Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift) (line 18).

### Configuring Linux Capabilities

```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

```

*Source reference*: Capability handling is implemented in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) (lines 1174-1199).

### Handling Containerization Errors

```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)")
}

```

*Source reference*: `ContainerizationError` is thrown throughout the runtime services (e.g., line 149 in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift)).

### Building an Image with the Builder API

```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()

```

*Source reference*: The high-level `Builder` type lives in [`Sources/ContainerBuild/Builder.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift) (lines 1-30).

### Using the Containerization OCI Module

```swift
import ContainerizationOCI

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

```

*Source reference*: OCI utilities appear 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).

## Summary

- The **Containerization Swift package** is the foundational library providing low-level container runtime primitives for the `apple/container` repository.
- Version **0.34.0** is pinned in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) (lines 25-27, 55) and imported as a dependency from the external `apple/containerization` repository.
- The package exposes multiple modules including `Containerization`, `ContainerizationOCI`, `ContainerizationOS`, `ContainerizationExtras`, and `ContainerizationArchive`.
- Core data types like `Containerization.Process`, `Containerization.Mount`, and `Containerization.LinuxCapabilities` handle container configuration across platform-specific implementations.
- `ContainerizationError` provides centralized error handling for invalid arguments, state violations, and unsupported operations throughout the runtime services.
- Higher-level modules such as `ContainerBuild`, `ContainerRuntimeClient`, and `ContainerNetworkServer` rely on these primitives to implement container building, execution, and networking.

## Frequently Asked Questions

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

The repository pins the Containerization Swift package to version **0.34.0**. This version constraint is defined in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) at lines 25-27, where `scVersion = "0.34.0"` is declared, and the dependency is registered at line 55.

### How does the Containerization Swift package handle platform differences between macOS and Linux?

The package abstracts platform differences through specialized modules. On **macOS**, it uses the `ContainerizationOS` layer for system integration. On **Linux**, it supplies `ContainerizationExtras` and `ContainerizationOCI` layers that map directly to underlying kernel features. This abstraction allows the `apple/container` tool to maintain consistent APIs across operating systems while leveraging platform-specific capabilities.

### What are the main modules exported by the Containerization Swift package?

The package exports five primary Swift modules: `Containerization` (core types and primitives), `ContainerizationOCI` (Open Container Initiative standards), `ContainerizationOS` (operating system abstractions), `ContainerizationExtras` (extended functionality), and `ContainerizationArchive` (image compression handling). These modules are imported throughout the codebase, such as in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) (lines 23-27) and `ProgressBar+Terminal.swift` (line 17).

### How does ContainerizationError improve error handling in the container tool?

`ContainerizationError` is a custom error type defined in the package that standardizes error reporting across the container runtime. It signals specific failure conditions including invalid arguments, state violations, and unsupported operations. The type is thrown throughout runtime services—particularly in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) (e.g., line 149)—enabling higher-level code to catch container-specific failures and provide detailed diagnostic messages.