# How to Use Existing OCI Images with Apple’s Container Tool

> Use existing OCI images directly with Apple's container tool. Discover how this OCI-first tool integrates seamlessly with Docker Hub, private registries, and local storage.

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

---

**Yes, Apple’s `container` tool is built OCI‑first and consumes standard OCI images from Docker Hub, private registries, or local storage without requiring conversion.**

The `apple/container` repository provides a lightweight container runtime for macOS that is fully compliant with the Open Container Initiative (OCI) specifications. Because the tool is implemented in Swift via the underlying **Containerization** package, it natively supports the OCI Image Specification and can pull, run, build, and push images that work with Docker, Buildah, or any other OCI-aware runtime.

## OCI-First Architecture

According to the [README](https://github.com/apple/container/blob/main/README.md), the tool both **consumes** and **produces** OCI‑compatible images. As documented in [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md), the CLI communicates with the **Containerization** Swift package to handle image manifests, layers, and configurations exactly as defined by the OCI Image Spec. This means any existing image that conforms to the specification—regardless of whether it was built with Docker, Podman, or BuildKit—can be used unchanged.

## Supported OCI Workflows

The `container` CLI provides explicit commands for interacting with OCI images across the full container lifecycle.

### Pulling Images from Registries

The `container pull` command fetches image manifests, layers, and configuration files from any OCI‑compliant registry. This operation validates registry hostnames according to the OCI Distribution specification, as implemented in [`Sources/ContainerResource/Registry/RegistryResource.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Registry/RegistryResource.swift).

```bash
container pull docker.io/library/alpine:latest

```

### Running OCI Images

When you execute `container run`, the tool starts a lightweight VM, loads the OCI image layers, and executes the entrypoint defined in the image’s OCI configuration. This behavior is documented in the Technical Overview and confirmed by the VM orchestration logic in the source.

```bash
container run docker.io/library/alpine:latest \
    --env PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
    --exec /bin/sh -c "echo Hello from Alpine inside a macOS VM!"

```

### Building OCI-Compatible Images

The `container build` command uses BuildKit under the hood to produce OCI‑compatible images. As noted in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), the output is written directly to the local content store in OCI format.

```bash
container build -t myorg/ubuntu-with-curl:latest .

```

### Saving and Exporting

You can export any local image to a tarball that follows the OCI Image Layout specification. The implementation in [`Sources/ContainerCommands/Image/ImageSave.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Image/ImageSave.swift) explicitly creates "an OCI compatible tar archive" containing the manifest, configuration, and layer blobs.

```bash
container image save myorg/ubuntu-with-curl:latest -o ubuntu-curl.tar

```

### Pushing to Registries

The `container push` command uploads image manifests and layers using the OCI Distribution spec. The registry interaction logic in [`Sources/ContainerResource/Registry/RegistryResource.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Registry/RegistryResource.swift) validates hostnames and ensures compliance with OCI standards, while [`Sources/ContainerCommands/Registry/RegistryLogin.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Registry/RegistryLogin.swift) handles authentication via the macOS Keychain.

```bash
container push myorg/ubuntu-with-curl:latest myregistry.example.com/myorg/ubuntu-with-curl:latest

```

## Complete Usage Examples

Below is a complete workflow demonstrating how to use existing OCI images without modification.

**1. Pull an existing image from Docker Hub:**

```bash
container pull docker.io/library/alpine:latest

```

**2. Run the image interactively:**

```bash
container run docker.io/library/alpine:latest \
    --env PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
    --exec /bin/sh -c "echo Hello from Alpine inside a macOS VM!"

```

**3. Build a new OCI image from a Dockerfile:**

```bash
cat > Dockerfile <<'EOF'
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl
CMD ["bash"]
EOF

container build -t myorg/ubuntu-with-curl:latest .

```

**4. Save the image to an OCI Layout tarball:**

```bash
container image save myorg/ubuntu-with-curl:latest -o ubuntu-curl.tar

```

**5. Push to a private registry:**

```bash
container push myorg/ubuntu-with-curl:latest myregistry.example.com/myorg/ubuntu-with-curl:latest

```

> **Note:** Ensure the `container` system service is running (`container system start`) before executing these commands.

## Key Implementation Files

The following source files confirm the tool’s OCI compatibility:

- **[`README.md`](https://github.com/apple/container/blob/main/README.md)** — Declares that `container` works with OCI‑compatible images.
- **[`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md)** — Describes the OCI‑first design and interoperability guarantees.
- **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)** — Documents CLI flags for building, pulling, and running OCI images.
- **[`Sources/ContainerCommands/Image/ImageSave.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Image/ImageSave.swift)** — Implements saving images as OCI‑compatible tar archives.
- **[`Sources/ContainerResource/Registry/RegistryResource.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Registry/RegistryResource.swift)** — Handles OCI registry hostname validation and distribution spec compliance.
- **[`Sources/ContainerCommands/Registry/RegistryLogin.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Registry/RegistryLogin.swift)** — Manages OCI registry authentication with Keychain integration.

## Summary

- Apple’s `container` tool is **OCI‑first**, meaning it natively consumes and produces standard OCI images.
- You can **pull**, **run**, **build**, **save**, and **push** images without conversion or modification.
- The tool validates registry compliance against the OCI Distribution specification.
- All image exports follow the OCI Image Layout spec, ensuring portability with other runtimes.

## Frequently Asked Questions

### Can I run Docker Hub images without conversion?

Yes. Images from Docker Hub, GHCR, or any OCI‑compliant registry work immediately. The `container pull` command downloads the manifest and layers exactly as Docker or Podman would, and `container run` executes the OCI config’s entrypoint without transformation.

### Does Apple’s container tool support OCI Image Layout exports?

Yes. The `container image save` command creates tar archives that strictly follow the OCI Image Layout specification. This is explicitly implemented in [`Sources/ContainerCommands/Image/ImageSave.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Image/ImageSave.swift), which preserves the manifest, configuration, and layer blobs in the standard directory structure.

### What registry authentication methods are supported?

The tool supports standard OCI registry authentication via the `container login` command, which stores credentials in the macOS Keychain. The implementation in [`Sources/ContainerCommands/Registry/RegistryLogin.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Registry/RegistryLogin.swift) and [`Sources/ContainerResource/Registry/RegistryResource.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Registry/RegistryResource.swift) handles token exchange and hostname validation according to the OCI Distribution spec.

### Is there any image format that isn’t supported?

The tool requires strict OCI Image Specification compliance. Legacy Docker schema v1 images or non‑OCI formats (such as proprietary VM disk images) are not supported. If an image works with Docker or Podman today, it is OCI‑compliant and will work with Apple’s `container` tool.