# How to Configure Resource Limits (CPU, Memory) for Containers in apple/container > Learn how to configure CPU and memory resource limits for containers in apple/container. Explore default settings, persistent configurations, and command-line overrides for optimal performance. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-15 --- **Resource limits in the `apple/container` project are configured through a hierarchical system: system-wide defaults defined in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift), persistent settings in [`config.toml`](https://github.com/apple/container/blob/main/config.toml), and immediate overrides via the `--cpus` and `--memory` command-line flags.** The `apple/container` repository provides a Swift-based container runtime that manages computational resources through a structured configuration hierarchy. Understanding how to configure CPU and memory resource limits ensures optimal performance for containerized workloads while preventing resource contention on the host system. ## Understanding the Resource Configuration Hierarchy The `container` CLI determines resource allocation through three distinct layers, applied in order of precedence: 1. **System-wide defaults** – Hardcoded values and [`config.toml`](https://github.com/apple/container/blob/main/config.toml) settings that apply to all containers 2. **Per-machine defaults** – Configuration specific to named container machines 3. **Command-line overrides** – Immediate flags that supersede all other settings This layered approach allows you to set sensible defaults while retaining flexibility for specific workloads. ## System-Wide Defaults in ContainerSystemConfig.swift Default resource limits are defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), where the `ContainerSystemConfig` struct specifies `defaultCPUs = 4` and `defaultMemory = "1g"`. Without explicit configuration, every container receives **4 vCPUs** and **1 GiB of RAM**. You can customize these defaults by creating a [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file in your configuration directory: ```toml # ~/.config/container/config.toml [container] cpus = 2 # default to 2 vCPUs per container memory = "2g" # default to 2 GiB RAM per container ``` The system configuration schema is documented in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md), which details the `[container]` table structure for persistent defaults. ## Overriding Limits via CLI Commands The `container run` and `container create` commands expose `--cpus` and `--memory` flags that replace system defaults for specific container instances. These flags accept integer values for CPUs and human-readable strings (e.g., `32g`, `512m`) for memory. ```bash # Use system defaults (4 CPUs, 1 GiB) container run -d my-image # Override only CPU count container run -d --cpus 6 my-image # Override both CPU and memory container run -d --cpus 8 --memory 16g my-image ``` According to [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) and [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), these flags are parsed during command execution and encoded into a `ContainerConfig` object before passing to the low-level runtime. ## Configuring Builder and Machine VM Resources Resource limits also apply to virtual machines used for building images and running persistent machines. The `container builder start` command accepts the same `--cpus` and `--memory` flags, with builder defaults typically set to 2 CPUs and 2 GiB RAM. ```bash # Configure builder VM with 6 CPUs and 8 GiB RAM container builder start --cpus 6 --memory 8g ``` For named container machines, use the `container machine set` command to establish persistent defaults that apply to future `container machine create` operations: ```bash # Set defaults for a machine named "dev" container machine set -n dev cpus=4 memory=8G ``` These per-machine settings, documented in [`docs/container-machine.md`](https://github.com/apple/container/blob/main/docs/container-machine.md), are stored in the `[machine]` section of [`config.toml`](https://github.com/apple/container/blob/main/config.toml) and apply unless overridden by CLI flags. ## How Memory Values Are Parsed The `container` CLI accepts human-readable memory strings like `32g`, `512m`, or `1.5gb`. These values are parsed by `Sources/ContainerPersistence/Measurement+Parse.swift`, which converts the string representations into internal memory measurements before allocation. This parsing supports both binary (GiB, MiB) and decimal (GB, MB) suffixes, though the default configuration uses `1g` to represent 1 GiB. ## Summary - **Default values** are defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) as 4 CPUs and 1 GiB memory - **Persistent configuration** is stored in `~/.config/container/config.toml` under the `[container]` section - **CLI overrides** use `--cpus` and `--memory` flags with `container run`, `container create`, and `container builder start` - **Machine-specific defaults** can be set via `container machine set` and stored in the `[machine]` table - **Memory parsing** is handled by `Measurement+Parse.swift`, supporting human-readable formats like `16g` or `512m` ## Frequently Asked Questions ### What is the default CPU and memory allocation for new containers? By default, the `container` CLI assigns **4 vCPUs** and **1 GiB of memory** to every new container. These values are hardcoded in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) as `defaultCPUs = 4` and `defaultMemory = "1g"`, and they apply unless you specify alternatives in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) or via command-line flags. ### How do I permanently change resource defaults for all containers? Create a [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file in your configuration directory (typically `~/.config/container/`) and set values under the `[container]` table. For example, setting `cpus = 2` and `memory = "2g"` establishes new system-wide defaults that apply to all subsequently created containers unless overridden by CLI flags. ### Can I set different resource limits for builder VMs versus runtime containers? Yes. While runtime containers use the `[container]` table defaults, builder VMs can be configured separately using the `--cpus` and `--memory` flags with `container builder start`. Additionally, persistent machines managed via `container machine` can have specific defaults set using `container machine set`, which stores configuration in the `[machine]` section of [`config.toml`](https://github.com/apple/container/blob/main/config.toml). ### What format does the `--memory` flag accept? The `--memory` flag accepts human-readable size strings such as `512m`, `2g`, `16gb`, or `1.5gi`. These strings are parsed by `Sources/ContainerPersistence/Measurement+Parse.swift`, which converts them into internal memory measurements. While the default configuration uses `g` to denote gibibytes (GiB), the parser supports various suffixes for both binary and decimal units.