# What Is the Containerization Package in Apple Container?

> Discover the containerization package in Apple Container. Learn about the open-source Swift library for VM-backed Linux containers, OCI image handling, and process management.

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

---

**The containerization package is the open-source Containerization Swift library that provides the VM-backed Linux container runtime, OCI image handling, and process management for the Apple Container CLI.**

The `apple/container` repository provides a command-line tool for running Linux containers on macOS Apple Silicon. At its core, this tool delegates low-level container, image, and process management to the **containerization package**—an open-source Swift library that wraps Apple's Virtualization and vmnet frameworks to deliver a high-level, OCI-compatible API.

## Defining the Containerization Package

The containerization package is the `Containerization` Swift library hosted at `https://github.com/apple/containerization`. According to the `apple/container` [README.md](https://github.com/apple/container/blob/main/README.md#L6-L11), the `container` binary "uses the Containerization Swift package for low-level container, image, and process management."

This library implements the VM-backed container abstraction, handling VM creation, filesystem mounting, networking, OCI image handling, and process execution. It exposes Swift types such as `LinuxContainer`, `ContainerConfiguration`, `DockerImage`, and `UnixSocketConfiguration` that the CLI and server components consume.

## Architecture and Integration

Apple Container follows a layered architecture where the containerization package serves as the foundational runtime layer.

### Dependency Declaration in Package.swift

The dependency is explicitly declared in the project's manifest. In [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) at lines 55-57, the containerization package is pinned as an exact version dependency:

```swift
.package(url: "https://github.com/apple/containerization.git", exact: Version(stringLiteral: scVersion)),

```

This declaration ensures the `container` binary links against a specific version of the containerization library, providing stable APIs for VM management and container lifecycle operations.

### Core Components and Services

The containerization package integrates with several architectural components:

- **`container` CLI**: Parses user commands (run, build, image push) and calls high-level APIs from `ContainerCommands`, which imports `Containerization` to manipulate images and containers.
- **`container-apiserver`**: A launch agent that owns the VM and spawns XPC helpers. It uses `Containerization` to create a `LinuxContainer`, configure CPU/memory/mounts, and drive lifecycle events.
- **XPC helpers** (`container-runtime-linux`, `container-core-images`, `container-network-vmnet`): These per-service helpers import `Containerization` (e.g., `import Containerization` in **RuntimeService.swift** at lines 23-27) and call types such as `LinuxContainer`, `Mount`, and `Process`.

## Key APIs and Types in the Containerization Package

The containerization package exposes several critical types that abstract macOS virtualization primitives.

### LinuxContainer

The `LinuxContainer` type represents a VM-backed Linux container instance. In **Sources/Services/RuntimeLinux/Server/RuntimeService.swift** (lines 23-27), the service instantiates this type to manage container lifecycles. The `ConfigureContainer` helper at lines 80-86 translates high-level `ContainerConfiguration` objects into low-level `LinuxContainer.Configuration` fields.

### ContainerConfiguration

This struct encapsulates resource limits and system settings including CPU count, memory allocation, mount points, and socket forwarding. It bridges the gap between CLI arguments and Virtualization framework requirements.

### OCI Image Handling

The package provides `ContainerImage` and related types for OCI-compliant image operations. According to **Sources/ContainerImagesService/Server/ImagesService.swift** (lines 20-24), these APIs support image pull, push, and storage operations using the containerization library's abstractions.

## Practical Implementation Examples

Below are minimal Swift snippets demonstrating how Apple Container leverages the containerization package.

### Creating a Linux Container

This example reflects the patterns found in `RuntimeService.configureContainer`:

```swift
import Containerization

// 1️⃣ Build a LinuxContainer.Configuration (CPU, memory, mounts, etc.)
var cfg = LinuxContainer.Configuration()
cfg.cpus = 2
cfg.memoryInBytes = 2 * 1024 * 1024 * 1024          // 2 GiB
cfg.mounts = [
    // Map the host rootFS into the container
    Mount(source: URL(filePath: "/path/to/rootfs"), destination: "/"),
]

// 2️⃣ Create a virtual-machine manager (VZVirtualMachineManager is provided by Apple)
let vmm = VZVirtualMachineManager(
    kernel: /* pre‑built VZLinuxBootKernel */,
    initialFilesystem: cfg.mounts[0].asMount,
    rosetta: false,
    logger: Logger(label: "example")
)

// 3️⃣ Build the container
let container = try LinuxContainer(
    id: "example‑container",
    rootfs: cfg.mounts[0].asMount,
    vmm: vmm,
    logger: Logger(label: "container")
) { cfg in
    // Additional low‑level tweaks (e.g., sysctls)
    cfg.sysctl["net.ipv4.ip_forward"] = "1"
}

// 4️⃣ Start the container’s init process
try container.start()

```

### Loading OCI Images

Image handling as implemented in the container commands layer:

```swift
import Containerization

// Load an image from a local tarball (or a remote registry)
let image = try ContainerImage(path: URL(filePath: "/tmp/alpine.tar"))

// Access layers and metadata
print("Image name: \(image.name)")
print("Layers count: \(image.manifest.layers.count)")

```

### XPC Communication

The XPC helpers use the containerization package to bridge inter-process communication:

```swift
import ContainerXPC
import Containerization

let client = XPCClient(endpoint: xpc_endpoint_create(connection))
let request = XPCMessage()
request.set(key: "command", value: "run")
request.set(key: "image", value: "docker.io/library/alpine:latest")

// Send request to the runtime service
let reply = try await client.send(request)
let containerID = reply.string(key: "containerID")
print("Started container with ID: \(containerID ?? "nil")")

```

## Source File References

Key implementation files that demonstrate containerization package usage:

- **[`Package.swift`](https://github.com/apple/container/blob/main/Package.swift)** (lines 55-57): Declares the `containerization` dependency.
- **[`README.md`](https://github.com/apple/container/blob/main/README.md)** (lines 6-11): Documents the package's role in low-level container management.
- **[`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift)** (lines 23-27, 80-86): Core runtime service creating and configuring `LinuxContainer` instances.
- **[`Sources/ContainerCommands/ContainerCommands.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/ContainerCommands.swift)** (lines 4-8): CLI layer importing `Containerization` for bundle preparation.
- **[`Sources/Services/ContainerImagesService/Server/ImagesService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerImagesService/Server/ImagesService.swift)** (lines 20-24): Image service demonstrating pull and storage operations.

## Summary

- The **containerization package** is the open-source `Containerization` Swift library providing the core runtime for Apple Container.
- It wraps Apple's Virtualization and vmnet frameworks to expose OCI-compatible container APIs.
- Key types include `LinuxContainer`, `ContainerConfiguration`, and `ContainerImage`.
- The dependency is declared in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) lines 55-57 and consumed by the CLI, API server, and XPC helpers.
- It handles VM creation, filesystem mounting, networking, and process execution for Linux containers on Apple Silicon.

## Frequently Asked Questions

### What is the containerization package in Apple Container?

The containerization package is the open-source `Containerization` Swift library that implements the VM-backed Linux container abstraction. It provides the runtime logic for OCI image handling, VM lifecycle management, and process execution that the `container` CLI relies on.

### How does the Containerization package interact with Apple's Virtualization framework?

The package wraps the `VZVirtualMachineManager` and related Virtualization framework APIs to create and manage Linux VMs. It translates high-level container configurations into Virtualization framework primitives, handling CPU, memory, and filesystem mount configurations.

### Where is the containerization package dependency declared?

The dependency is declared in **Package.swift** at lines 55-57 using `.package(url: "https://github.com/apple/containerization.git", exact: Version(stringLiteral: scVersion))`. This pins the Apple Container tool to a specific version of the containerization library.

### What are the main types exposed by the Containerization package?

The package exposes `LinuxContainer` for VM management, `ContainerConfiguration` for resource settings, `Mount` for filesystem mappings, `ContainerImage` for OCI image operations, and `Process` for containerized process execution. These types are imported across the CLI and XPC helper services.