# How to Configure Memory and CPU for Containers in Apple's Container Runtime

> Learn to configure container memory and CPU with Apple's container runtime using command-line flags, config files, or the Swift API. Optimize your container performance today.

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

---

**Configure memory and CPU for containers using command-line flags (`--cpus`, `--memory`), the [`config.toml`](https://github.com/apple/container/blob/main/config.toml) configuration file, or the Swift API, with defaults defined in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) and validated at runtime in [`ContainersService.swift`](https://github.com/apple/container/blob/main/ContainersService.swift).**

The `apple/container` repository provides a Swift-based container runtime that allows precise control over resource allocation. Understanding how to configure memory and CPU settings ensures optimal performance for both development environments and production workloads.

## Configuration Layers

The container runtime applies CPU and memory settings through three distinct layers, defined in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) and enforced across the system.

### Default Values

When no overrides are specified, the runtime uses hard-coded defaults defined in the `ContainerConfig` and `BuildConfig` structs within [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift). Regular containers default to **4 CPUs** and **"1g"** (1 GiB) of memory, while the builder VM defaults to **2 CPUs** and **"2048mb"** (2 GiB) of memory.

These values are loaded from the `[container]` and `[build]` sections of the [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file if present, falling back to the code-defined constants when keys are missing.

### Command-Line Overrides

Per-container overrides take precedence through the `--cpus` and `--memory` flags. In [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift), the `Resource` struct parses these flags as `Int64?` and `String?` respectively. The [`Parser.swift`](https://github.com/apple/container/blob/main/Parser.swift) file then converts memory strings to byte counts using `Parser.memoryStringAsMiB` and `Parser.memoryStringAsBytes`, which rely on `Measurement.parse` from `Measurement+Parse.swift`.

### Runtime Validation

Before launching, [`ContainersService.swift`](https://github.com/apple/container/blob/main/ContainersService.swift) validates that requested memory meets the minimum threshold of **200 MiB**. If `configuration.resources.memoryInBytes` is below this value, the service returns an explicit error and prevents container creation.

## Memory Format Specification

Memory values use a **MemorySize** format parsed by `Measurement.parse` in `Sources/ContainerPersistence/Measurement+Parse.swift`. The format accepts binary units (powers of 1024) with these case-insensitive suffixes:

- `"b"` – bytes
- `"k"` – KiB (1024 bytes)
- `"mb"` – MiB (1024 KiB)
- `"g"` – GiB (1024 MiB)
- `"t"` – TiB (1024 GiB)

Plain integers without suffixes are interpreted as bytes. For example, `"4g"` converts to approximately 4,294,967,296 bytes (4 × 1024³).

## CPU Handling

CPU allocation uses plain integers representing **virtual CPUs**. The `--cpus` flag maps directly to an `Int64` value with no unit suffix required. The system stores this as `configuration.resources.cpus` and applies it to the container's cgroup limits. Unlike memory, CPU values undergo only basic integer parsing without additional runtime validation beyond type checking.

## Practical Configuration Examples

### 1. Command-Line Resource Allocation

Use the `--cpus` and `--memory` flags to set resources for a specific container run:

```bash
container run --cpus 2 --memory 4g myimage:latest

```

This command allocates 2 vCPUs and 4 GiB of RAM, overriding any default settings.

### 2. Permanent Defaults in config.toml

Set system-wide defaults by editing `$HOME/.config/container/config.toml`:

```toml
[container]
cpus   = 6
memory = "8g"

[build]
cpus   = 4
memory = "4096mb"

```

The runtime reads this file via `ContainerSystemConfig`, applying these values to all new containers and builder VMs unless overridden by flags.

### 3. Swift API Configuration

Programmatically configure resources using the `ContainerAPI` module:

```swift
import ContainerAPI

let resources = Resources(
    cpus: 3,
    memoryInBytes: try MemorySize("2g").measurement.converted(to: .bytes).value
)

let config = ContainerConfiguration(resources: resources)
try client.create(config)

```

The `MemorySize` initializer uses the same parsing logic as the CLI, ensuring consistency between programmatic and command-line interfaces.

### 4. Inspecting Resource Usage

Monitor actual resource consumption against configured limits:

```bash
container stats mycontainer

```

Output displays current CPU percentage and memory usage against limits (e.g., `Memory usage: 1.2 GiB / 8 GiB`), sourced from [`ContainerStats.swift`](https://github.com/apple/container/blob/main/ContainerStats.swift) which tracks `memoryUsageBytes` and `memoryLimitBytes`.

## Summary

- **Defaults**: 4 CPUs and 1 GiB memory for containers, 2 CPUs and 2 GiB for builder VMs, defined in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift)
- **Configuration methods**: Command-line flags (`--cpus`, `--memory`), [`config.toml`](https://github.com/apple/container/blob/main/config.toml) settings, or Swift API `Resources` struct
- **Memory format**: Binary units (b, k, mb, g, t) parsed by `Measurement.parse` with a 200 MiB minimum enforced by [`ContainersService.swift`](https://github.com/apple/container/blob/main/ContainersService.swift)
- **CPU format**: Plain integers representing vCPUs, stored as `Int64` without additional validation

## Frequently Asked Questions

### What is the minimum memory requirement for containers?

The runtime enforces a minimum memory allocation of **200 MiB** (approximately 209,715,200 bytes). If you specify a value below this threshold through any configuration method, [`ContainersService.swift`](https://github.com/apple/container/blob/main/ContainersService.swift) rejects the request with a validation error before creating the container.

### How does the memory suffix parsing work in container configuration?

The runtime uses `Measurement.parse` from `Measurement+Parse.swift` to interpret memory strings as binary units (powers of 1024). Suffixes are case-insensitive: `"k"` represents KiB, `"mb"` represents MiB, `"g"` represents GiB, and `"t"` represents TiB. Plain integers without suffixes are interpreted as raw bytes, ensuring flexibility across different configuration interfaces.

### Where are the default CPU and memory values defined?

Default values reside in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) within the `ContainerConfig` and `BuildConfig` structs. Regular containers default to 4 CPUs and `"1g"` memory, while the builder VM uses 2 CPUs and `"2048mb"` memory. These hard-coded values serve as fallbacks when the [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file lacks explicit entries or when command-line flags are omitted.

### Can I configure resources programmatically instead of using CLI flags?

Yes, the Swift API exposed in `ContainerAPI` allows direct configuration of the `Resources` struct. You can specify CPU counts as integers and memory as parsed `MemorySize` objects converted to bytes. This approach uses the same underlying validation and parsing logic as the command-line interface, ensuring consistent behavior across automation scripts and manual operations.