# How Apple Container Achieves OCI Image Compatibility with Other Runtimes

> Discover how Apple Container achieves OCI image compatibility. Learn how its ContainerizationOCI library ensures spec compliance for seamless integration with other runtimes.

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

---

**Apple Container ensures OCI image compatibility by routing every image operation through the ContainerizationOCI library, which strictly implements the OCI Image Specification types, validation logic, and storage layout.**

The `apple/container` project implements a Swift-based container runtime built atop the Containerization open-source stack. By delegating all image parsing, validation, and storage to a dedicated OCI-aware library, the runtime delivers complete **OCI image compatibility**, enabling seamless consumption of images from Docker, Podman, and BuildKit while producing images that any OCI-compliant runtime can execute.

## The ContainerizationOCI Library Foundation

All image-related operations in `container` funnel through **ContainerizationOCI**, a Swift package declared in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) (lines 92–112). This library implements the verbatim OCI Image Specification, providing strongly-typed representations of `Image`, `Manifest`, `Platform`, and `Reference`. According to [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md) (lines 20–33), the codebase explicitly *“consumes and produces standard OCI images”*, making interoperability a foundational design constraint rather than an afterthought.

By centralizing image handling in this library, `container` guarantees that every manifest, config, and layer blob adheres to the canonical OCI schema before touching the network or storage.

## Strict Reference Parsing and Validation

Before any network request, user-supplied image strings undergo rigid validation to ensure they conform to OCI reference grammar.

### Reference Grammar Enforcement

In [`Sources/ContainerCommands/Image/ImageList.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Image/ImageList.swift) (line 123), CLI commands invoke `ContainerizationOCI.Reference.parse` to transform text like `docker.io/library/ubuntu:22.04` into a structured object. This routine validates the name, tag, and optional digest components, rejecting malformed references before they reach the content store.

### Registry Hostname Validation

When adding a new registry endpoint, [`Sources/ContainerResource/Registry/RegistryResource.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Registry/RegistryResource.swift) (lines 52–70) applies `nameValid(_:)`, which uses the exact regular-expression pattern defined by the OCI distribution specification. This includes support for IPv6 literals and optional ports, preventing ill-formed registry URLs from being persisted.

## Platform-Aware Image Resolution

OCI images frequently bundle multi-architecture manifests. To ensure the correct variant is executed, [`Sources/ContainerBuild/BuildImageResolver.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildImageResolver.swift) (lines 24–30 and 94–98) extracts the `Platform` (OS, architecture, variant) from the manifest and retrieves the matching `ContainerizationOCI.Image` payload. This guarantees that the image handed to the VM matches the requested platform, following the same resolution logic used by Docker and Podman.

## Canonical OCI Storage Layout

`container` stores image blobs in an unchanged, canonical OCI layout: raw compressed layers, config JSON, and manifests are written to `blobs/sha256/...` with an accompanying [`index.json`](https://github.com/apple/container/blob/main/index.json). Because the content store preserves the exact bytes received from registries, other runtimes reading these files encounter a **standard OCI directory layout** that requires no translation. Conversely, when `container` pulls from a Docker registry, it writes layers verbatim, ensuring that Docker-created images load without modification.

## Cross-Runtime Export and Import

The `container image save` command generates tarballs that follow the OCI Image Layout specification. Internally, this executes `ImageResource.save`, which organizes the archive exactly as defined by the OCI standard. These tarballs can be imported directly using `docker load` or `podman load`. Similarly, `container image load` accepts OCI-layout tarballs from any source, verifying the manifest schema before acceptance, ensuring bidirectional compatibility.

## Practical Implementation Examples

### Building an OCI-Compliant Image

```swift
import ContainerizationOCI
import ContainerBuild

let builder = try Builder(
    contentStore: store,
    config: .init(),
    containerSystemConfig: systemConfig
)

// Parse and pull a base image using OCI reference syntax
let baseRef = try ContainerizationOCI.Reference.parse("docker.io/library/ubuntu:22.04")
let baseImage = try await builder.pull(reference: baseRef, platform: .current)

// Add a layer and commit
let layer = try Layer(contentsOf: URL(fileURLWithPath: "./myapp"))
try builder.add(layer: layer, to: baseImage)

let newImage = try await builder.commit(
    from: baseImage,
    tag: "myorg/myapp:latest",
    platform: .current
)

```

### Pulling from Any OCI Registry

```swift
import ContainerizationOCI
import ContainerAPIClient

let ref = try ContainerizationOCI.Reference.parse("ghcr.io/apple/example:1.2.3")
let platform = ContainerizationOCI.Platform.current

// Fetches from cache or network, returns a spec-compliant Image object
let image = try await ClientImage.fetch(
    reference: ref,
    platform: platform,
    containerSystemConfig: config,
    progressUpdate: { /* handle progress */ }
)

print("Config digest: \(image.config.digest)")

```

### Exporting for Other Runtimes

```swift
import ContainerCommands

// Creates an OCI-layout tarball compatible with docker load
try ImageResource.save(
    image: myImage,
    to: URL(fileURLWithPath: "./myapp-oci.tar")
)

```

## Summary

- **ContainerizationOCI Library**: Centralizes all image handling in a spec-compliant Swift package defined in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift), ensuring every operation implements the OCI Image Specification.
- **Strict Validation**: `ContainerizationOCI.Reference.parse` and `RegistryResource.nameValid(_:)` enforce OCI grammar and hostname rules before storage.
- **Platform Resolution**: `BuildImageResolver` extracts the correct multi-arch manifest platform, matching the behavior of Docker and Podman.
- **Canonical Storage**: Blobs are stored in the standard `blobs/sha256` layout, allowing other runtimes to read `container`’s store directly.
- **Interchangeable Export**: `ImageResource.save` produces OCI Image Layout tarballs that import cleanly into any OCI-compatible runtime.

## Frequently Asked Questions

### What library provides OCI compatibility in Apple Container?

The **ContainerizationOCI** Swift package, declared as a dependency in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) (lines 92–112), provides all OCI types and validation logic. Every image operation—parsing, building, pulling, and exporting—routes through this library to guarantee spec compliance.

### Can container run images built with Docker or Podman?

Yes. Because `container` stores image layers, manifests, and configs in the **canonical OCI layout** without modification, it can execute images created by Docker, Podman, BuildKit, or any OCI-compliant tool. The content store at `blobs/sha256/...` is readable by any runtime that supports the OCI Image Specification.

### How does container handle multi-architecture images?

`container` uses `BuildImageResolver` ([`Sources/ContainerBuild/BuildImageResolver.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildImageResolver.swift), lines 94–98) to inspect OCI manifest lists, extract the `Platform` object matching the host OS and architecture, and fetch the corresponding image configuration. This ensures the correct binary variant is executed, identical to the platform selection logic in Docker.

### What storage format does container use for images?

`container` uses the **OCI Image Layout** format, storing blobs under `blobs/sha256/` with an [`index.json`](https://github.com/apple/container/blob/main/index.json) index file. This canonical layout means the on-disk representation is immediately readable by other OCI tools without conversion or export.