# How to Set CPU and Memory Limits for Containers in Apple Container > Learn to set CPU and memory limits for containers in Apple Container using CLI flags or config files. Optimize your container performance and resource allocation today. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-10 --- **Configure container resource limits using the `--cpus` and `--memory` CLI flags for per-container overrides, or set persistent defaults in `~/.config/container/config.toml` under the `[container]` section.** The Apple Container framework manages resource allocation through a layered configuration system implemented in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift). You can constrain CPU and memory via command-line arguments, configuration files, or machine-specific defaults, with values cascading from system settings through CLI flags to the final `ContainerConfig` object passed to the runtime. ## Understanding the Configuration Hierarchy The framework determines final resource values by evaluating three configuration layers in order of precedence: 1. **System-wide defaults** – Stored in `~/.config/container/config.toml` under the `[container]` table, as documented in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md) 2. **Machine-specific defaults** – Set via `container machine set` or the `[machine]` section in config.toml per [`docs/container-machine.md`](https://github.com/apple/container/blob/main/docs/container-machine.md) 3. **CLI overrides** – Provided via `--cpus` and `--memory` flags at runtime, documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) According to [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), the hardcoded system defaults initialize to `defaultCPUs = 4` and `defaultMemory = "1g"`, meaning containers receive 4 virtual CPUs and 1 GiB of RAM unless explicitly configured otherwise. ## Configuring System-Wide Defaults Create or edit `~/.config/container/config.toml` to establish baseline resources for all containers on your system. The `[container]` table defines values that apply when you omit CLI flags. ```toml # ~/.config/container/config.toml [container] cpus = 2 # Default to 2 CPUs per container memory = "2g" # Default to 2 GiB RAM per container ``` The framework parses these values using `Sources/ContainerPersistence/Measurement+Parse.swift`, which handles human-readable memory formats like `"16g"` or `"512m"`. These settings persist across reboots and apply to every `container run` invocation unless overridden by flags, as shown in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md). ## Overriding Limits via Command-Line Flags Override defaults for individual containers using the `--cpus` and `--memory` flags with `container run` or `container create`. These flags replace the defaults for the specific container you are launching. ```bash # Use system defaults (4 CPUs, 1 GiB) container run -d my-image # Override CPU count only container run -d --cpus 6 my-image # → 6 CPUs, 1 GiB RAM # Override both CPU and memory container run -d --cpus 8 --memory 16g my-image # → 8 CPUs, 16 GiB RAM ``` The CLI processor reads the system config, applies any per-machine defaults, then substitutes explicit `--cpus` and `--memory` values into the `ContainerConfig` object before passing it to the low-level container runtime. ## Configuring Builder and Machine Resources Builder VMs and container machines maintain separate resource defaults that you can modify independently from standard container defaults. ### Builder VM Configuration The builder VM defaults to 2 CPUs and 2 GiB RAM according to the `BuildConfig` implementation. Adjust these resources when starting the builder: ```bash container builder start --cpus 6 --memory 8g ``` ### Container Machine Configuration Set persistent defaults for named machines using the `container machine set` command. These values apply to future `container machine create` operations for that specific machine name. ```bash # Set defaults for a machine named "dev" container machine set -n dev cpus=4 memory=8G ``` Future invocations of `container machine create -n dev` inherit these defaults unless CLI flags specify otherwise. Per-machine configuration resides in the `[machine]` section of [`config.toml`](https://github.com/apple/container/blob/main/config.toml) as documented in [`docs/container-machine.md`](https://github.com/apple/container/blob/main/docs/container-machine.md). ## Summary - **Default values**: 4 CPUs and 1 GiB RAM defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) - **Configuration file**: Edit `~/.config/container/config.toml` under `[container]` for system-wide defaults - **Memory parsing**: Human-readable strings (e.g., `"32g"`, `"512m"`) processed by `Measurement+Parse.swift` - **CLI overrides**: Use `--cpus` and `--memory` with `container run`, `container create`, or `container machine create` - **Builder defaults**: 2 CPUs and 2 GiB RAM unless specified with `container builder start --cpus` and `--memory` - **Machine defaults**: Use `container machine set` to configure named machine templates ## Frequently Asked Questions ### What are the default CPU and memory limits for new containers? According to [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), the system initializes with `defaultCPUs = 4` and `defaultMemory = "1g"`. If you never specify limits in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) or via CLI flags, every container receives 4 virtual CPUs and 1 GiB of RAM. ### How do I set persistent defaults for all containers on my system? Edit `~/.config/container/config.toml` and add a `[container]` section with `cpus` and `memory` keys. For example, setting `cpus = 2` and `memory = "2g"` changes the baseline from 4 CPUs/1 GiB to 2 CPUs/2 GiB for all future containers unless overridden by command-line flags. ### Can I override resource limits for a single container without changing the defaults? Yes, use the `--cpus` and `--memory` flags with `container run` or `container create`. These flags immediately override both system defaults and machine-specific settings for that specific container instance, encoding the final values into the `ContainerConfig` object passed to the runtime. ### How do I configure resources for the builder VM separately from regular containers? The builder VM uses separate defaults (2 CPUs, 2 GiB) defined in `BuildConfig`. Use `container builder start --cpus --memory ` to override these temporarily. For persistent builder machine configuration, use `container machine set` to define defaults for the specific builder machine name.