# How to Configure Apple Container: A Complete Guide to TOML System Settings

> Configure Apple Container easily using TOML system settings. Follow this guide to create your config file and restart the service for seamless integration.

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

---

**Configure Apple Container by creating a `~/.config/container/config.toml` file with TOML tables like `[container]` and `[build]`, then restart the service with `container system stop` and `container system start` to apply changes.**

Apple Container is an open-source containerization platform that reads system-wide settings from a TOML configuration file at startup. The configuration system maps each top-level table directly onto Swift structs defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), using a *first-match-wins* precedence chain to merge user overrides with hard-coded defaults. Understanding this configuration pipeline allows you to customize resource limits, DNS settings, and build parameters while maintaining type safety.

## Configuration File Location and Precedence

Apple Container searches for [`config.toml`](https://github.com/apple/container/blob/main/config.toml) in two locations, stopping at the first file found:

1. **User file** – `~/.config/container/config.toml`
2. **Package-install file** – `<install-root>/etc/container/config.toml`

If a key is missing from both files, the system falls back to hard-coded defaults defined in the Swift model classes such as `ContainerConfig` and `BuildConfig`. This hierarchy ensures user-specific settings always override system-wide installations without modifying package files.

## Core Configuration Sections

Each TOML table maps one-to-one to a Swift class in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift). Only specify the keys you wish to override; unspecified values retain their defaults.

### Container Resources (ContainerConfig)

The `[container]` table controls default CPU and memory allocations for new containers. According to the source code in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift), the `ContainerConfig` class supplies these defaults:

```swift
final public class ContainerConfig: Codable, Sendable {
    public static let defaultCPUs = 4
    public static let defaultMemory = try! MemorySize("1g")
    // ...
}

```

To override these defaults, specify integer values for `cpus` and memory strings like `"4g"` or `"2048mb"`:

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

```

### Build Settings (BuildConfig)

The `[build]` table configures the containerization engine used during image builds. The `BuildConfig` class defines defaults including `defaultRosetta`, `defaultCPUs`, `defaultMemory`, and `defaultImage`:

```toml
[build]
cpus = 2
memory = "2048mb"
rosetta = true
image = "ghcr.io/apple/container-builder-shim/builder:0.11.0"

```

### Network, DNS, and Registry

Additional tables include `[network]` for subnet CIDRs, `[dns]` for domain settings, `[registry]` for default domains (defaulting to `"docker.io"`), `[kernel]` for binary paths, and `[vminit]` for initialization images. The `NetworkConfig` and `DNSConfig` classes handle these sections, with most values defaulting to `nil` unless explicitly configured.

## Step-by-Step Configuration Guide

### 1. Create the User Configuration Directory

Initialize the configuration directory and file:

```bash
mkdir -p ~/.config/container
touch ~/.config/container/config.toml

```

### 2. Define Your TOML Overrides

Edit `~/.config/container/config.toml` with only the sections you need to change. This example increases container resources and sets a custom DNS domain:

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

[dns]
domain = "test"

```

The keys map directly to Swift struct properties (e.g., `container.cpus` maps to `ContainerConfig.cpus`).

### 3. Restart the Container Service

Configuration is read once at process startup. Apply changes by restarting the daemon:

```bash
container system stop
container system start

```

These commands are defined in the `container` CLI reference documentation.

### 4. Verify the Applied Configuration

Dump the merged configuration to confirm your overrides took effect:

```bash
container system property list

```

For machine-readable output suitable for scripting, use JSON format:

```bash
container system property list --format json

```

The output displays the final resolved values including your custom settings alongside inherited defaults.

## Advanced Configuration Options

### Plugin-Specific Settings

Plugins can expose their own configuration tables under `[plugin.<id>]`. The main loader decodes these sections into plugin-specific structs defined in `Sources/ContainerPlugin/`, ensuring isolation between extensions. Consult individual plugin documentation for available keys within each plugin namespace.

### Memory Size and CIDR Formats

The TOML parser uses custom types defined in `Sources/ContainerPersistence/Measurement+Parse.swift`. The `MemorySize` type accepts strings such as `"4g"`, `"512mb"`, or `"1t"`, while `CIDRv4` and `CIDRv6` types handle network notation like `"192.168.100.0/24"`. These convert to strongly-typed Swift values during decoding.

## Summary

- **Apple Container** uses a TOML configuration file located at `~/.config/container/config.toml` (user) or `<install-root>/etc/container/config.toml` (system).
- Configuration sections like `[container]`, `[build]`, and `[dns]` map directly to Swift structs in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift).
- Default values are defined as static constants (e.g., `ContainerConfig.defaultCPUs = 4`) and are overridden only by explicitly specified keys.
- Changes require a service restart via `container system stop` and `container system start` to take effect.
- Verify active configuration using `container system property list --format json`.

## Frequently Asked Questions

### What is the default location for the Apple Container configuration file?

The primary location is `~/.config/container/config.toml` in the user's home directory. If this file does not exist, the system falls back to `<install-root>/etc/container/config.toml` installed with the package. Missing keys in either file use hard-coded defaults from the Swift source.

### How do I reset Apple Container settings to default values?

Remove or rename your user configuration file at `~/.config/container/config.toml` and restart the service. Without a user config file, the system uses package defaults or built-in constants defined in classes like `ContainerConfig` and `BuildConfig`.

### What format does Apple Container use for memory sizes in the TOML file?

Memory sizes use human-readable strings parsed by the `MemorySize` type. Valid formats include `"512mb"`, `"4g"`, `"1t"` (terabytes), or raw byte integers. The parsing logic resides in `Sources/ContainerPersistence/Measurement+Parse.swift`.

### Do I need to restart the service after editing config.toml?

Yes. Apple Container reads the TOML configuration only once at process startup. After modifying [`config.toml`](https://github.com/apple/container/blob/main/config.toml), you must run `container system stop` followed by `container system start` to reload the configuration into the running daemon.