# Known Limitations and Issues with Apple's Container Runtime

> Discover known limitations and issues with Apple Container Runtime, including memory reclamation, networking restrictions on macOS 15, and manual kernel updates.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: known-issues
- Published: 2026-07-01

---

**Apple's container runtime has several documented limitations including incomplete memory ballooning that prevents RAM reclamation, restricted networking capabilities on macOS 15, and manual kernel update requirements.**

The `apple/container` repository provides a lightweight container runtime built on top of the Containerization package, utilizing per-container virtual machines rather than shared VMs. While this design delivers strong isolation and fast boot times, the current implementation contains specific constraints regarding memory management, platform compatibility, and runtime configuration that developers must consider when deploying workloads.

## Memory Management Constraints

### Partial Memory Ballooning Behavior

The runtime architecture relies on the **macOS Virtualization framework**, which only supports limited memory reclamation. According to [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md) (lines 55-60), when a container's VM frees pages back to Linux, those pages are **not** returned to the host macOS system.

This partial ballooning means memory-intensive containers may retain more host RAM than they actively use, even after freeing memory internally. The documentation advises restarting containers periodically to force memory pages back to the host system.

## macOS 15 Compatibility Limitations

### Network Isolation Restrictions

On macOS 15, the **vmnet framework** provides only isolated network segments. Containers cannot communicate with each other, which limits multi-container application architectures and service discovery mechanisms.

### Missing Multiple Network Support

The `container network` commands are unavailable on macOS 15. Additionally, the `--network` flag on `container run` and `container create` commands fails, as documented in [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md) (lines 61-77).

### IP Address Assignment Issues

Because the network XPC helper must start before the first container launches, vmnet can sometimes assign unexpected CIDR ranges. This causes containers to lose network connectivity unpredictably, requiring container restarts to restore proper networking.

## Runtime Configuration Constraints

### Default Runtime Helper Requirements

The default runtime helper is **`container-runtime-linux`**. Changing this requires explicitly setting the `--runtime` flag, as noted in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (line 71). Any custom runtime must implement the same XPC API surface, creating a high barrier for alternative runtime implementations.

### Kernel Update Process

Updating the Linux kernel used by the runtime requires manual intervention. Developers must execute `container system update` or perform a manual installation, referenced in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (line 1541), as the process is not fully automated.

## Practical Workarounds and Mitigations

The following command-line snippets illustrate workarounds for the most common limitations:

```bash

# Increase memory limit for memory-heavy containers (default is 1GiB)

container run --rm --memory 8g --cpus 4 my-image

# Restart container to force memory reclamation to host

container stop my-big-container
container start my-big-container

# Avoid --network flag on macOS 15; containers automatically attach to default vmnet

container run --rm my-image

# Specify custom runtime helper when implementing alternative XPC interfaces

container run --runtime my-custom-runtime my-image

```

## Key Source Files for Debugging

Understanding these specific files helps developers investigate runtime behavior and limitations:

- **[`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md)** – Documents memory ballooning behavior and macOS 15 network limitations
- **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)** – Defines the `--runtime` flag and kernel update commands
- **[`Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift)** – Implements the default `container-runtime-linux` helper
- **[`Sources/Plugins/RuntimeLinux/config.toml`](https://github.com/apple/container/blob/main/Sources/Plugins/RuntimeLinux/config.toml)** – Declares the plugin configuration for Linux container runtime
- **`Makefile`** – Handles building and codesigning of the runtime binary
- **[`BUILDING.md`](https://github.com/apple/container/blob/main/BUILDING.md)** – Provides debugging instructions for the runtime helper

## Summary

- **Memory ballooning** is incomplete; freed pages remain allocated to the VM rather than returning to the host macOS system
- **macOS 15** lacks full network functionality, preventing container-to-container communication and multiple network configurations
- **Kernel updates** require manual execution via `container system update` rather than automatic updates
- **Custom runtimes** must implement the XPC API surface and be specified with the `--runtime` flag

## Frequently Asked Questions

### Why does Apple's container runtime not return freed memory to the host?

The macOS Virtualization framework only supports limited memory reclamation. When a container's Linux VM frees pages, they remain allocated to the virtual machine rather than being returned to macOS. Developers should restart containers periodically to reclaim host memory, as documented in the technical overview.

### Can containers communicate with each other when running on macOS 15?

No. On macOS 15, the vmnet framework only provides isolated networks, preventing container-to-container communication. This limitation is resolved in macOS 26, which provides the necessary virtualization APIs for full networking support and cross-container connectivity.

### How do I update the Linux kernel used by Apple's container runtime?

Use the command `container system update` or perform a manual installation. The update process is not fully automated as of the current implementation, requiring explicit user intervention to apply kernel updates documented in the command reference.

### What file controls the default runtime helper behavior?

The **[`Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift)** file implements the default `container-runtime-linux` helper, while **[`Sources/Plugins/RuntimeLinux/config.toml`](https://github.com/apple/container/blob/main/Sources/Plugins/RuntimeLinux/config.toml)** declares the plugin configuration. Changes to runtime behavior require modifications to these files followed by rebuilding via the `Makefile`.