# How to Set Memory and CPU Limits for a Container in apple/container > Learn how to set memory and CPU limits for your container. Discover the three-layer hierarchy: system defaults, persistent config, and CLI overrides for precise resource control. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-05 --- **You configure CPU and memory limits through a three-layer hierarchy: system-wide defaults defined in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) (4 CPUs and 1 GiB), persistent values in `~/.config/container/config.toml`, and immediate overrides via the `--cpus` and `--memory` CLI flags.** The `apple/container` project determines resource allocation by layering configuration sources. Understanding how [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) defines defaults, how [`config.toml`](https://github.com/apple/container/blob/main/config.toml) persists preferences, and how command-line arguments override both ensures precise resource control without repetitive typing. ## Configuration Hierarchy and Precedence Resource limits resolve in strict order of specificity: CLI flags override per-machine settings, which override the system-wide `[container]` table in [`config.toml`](https://github.com/apple/container/blob/main/config.toml). ### System-Wide Defaults When you never specify limits, the system falls back to hardcoded defaults in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift): - `defaultCPUs = 4` - `defaultMemory = "1g"` These values populate the `ContainerConfig` struct and apply to every new container unless superseded by configuration files or flags. According to the source, these defaults translate to **4 vCPUs** and **1 GiB of RAM** per container instance. ### Per-Machine Overrides For container machines (VMs that host containers), the `[machine]` section in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) can establish defaults tied to specific machine names. The `container machine set` command writes these values, which persist for future `container machine create` invocations. For example, setting `cpus=4 memory=8G` on a machine named "dev" causes all subsequent creations of that machine to inherit those resources unless CLI flags intervene. ### Command-Line Overrides The highest precedence belongs to explicit flags. The `container run` and `container create` commands expose `--cpus` and `--memory` parameters that completely replace defaults for that specific invocation. The same flags work for `container builder start` (configuring the build VM) and `container machine create` (configuring new machine VMs). ## Setting Resource Limits in Practice ### Overriding Defaults with CLI Flags Use the `--cpus` and `--memory` flags to specify resources for individual containers: ```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 ``` As implemented in the CLI parsing logic, these flags accept integer CPU counts and human-readable memory strings (e.g., `16g`, `32g`). ### Configuring Persistent Defaults in config.toml To change defaults for all containers without typing flags repeatedly, edit `~/.config/container/config.toml`: ```toml [container] cpus = 2 # default to 2 CPUs per container memory = "2g" # default to 2 GiB RAM per container ``` The `Sources/ContainerPersistence/Measurement+Parse.swift` file handles parsing of these string values, supporting human-readable units like `"1g"`, `"2g"`, or `"512m"`. ### Adjusting Builder and Machine Resources Build environments and container machines support the same resource parameters with their own default scopes: **Builder VM:** ```bash # Start builder with 6 CPUs and 8 GiB RAM (overrides BuildConfig defaults) container builder start --cpus 6 --memory 8g ``` **Container Machines:** ```bash # Set persistent defaults for machine "dev" container machine set -n dev cpus=4 memory=8G ``` Future invocations of `container machine create -n dev` inherit these settings unless explicitly overridden. ## Key Implementation Files - **[`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift)**: Defines `defaultCPUs`, `defaultMemory`, and the `ContainerConfig` struct. - **`Sources/ContainerPersistence/Measurement+Parse.swift`**: Parses memory strings (e.g., `"32g"`) into byte values. - **[`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md)**: Documents the [`config.toml`](https://github.com/apple/container/blob/main/config.toml) schema and `[container]` table. - **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)**: Reference for `--cpus` and `--memory` flag syntax. ## Summary - **Default resources** are 4 CPUs and 1 GiB RAM, defined in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift). - **Configuration file** at `~/.config/container/config.toml` stores system-wide and per-machine defaults under the `[container]` and `[machine]` tables. - **CLI flags** `--cpus` and `--memory` override all other settings for `container run`, `container create`, `container builder start`, and `container machine create`. - **Memory values** use human-readable strings parsed by `Measurement+Parse.swift` (e.g., `"16g"`, `"512m"`). ## Frequently Asked Questions ### What are the default CPU and memory limits? The system defaults to **4 vCPUs** and **1 GiB of RAM** for every container. These values originate from `defaultCPUs = 4` and `defaultMemory = "1g"` in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift). ### Where is the container configuration file located? The configuration file resides at `~/.config/container/config.toml`. This file stores the `[container]` table for system-wide defaults and the `[machine]` table for per-machine resource preferences. ### Can I set CPU and memory limits for the builder VM? Yes. The `container builder start` command accepts `--cpus` and `--memory` flags to configure the build environment. For example, `container builder start --cpus 6 --memory 8g` allocates 6 CPUs and 8 GiB RAM to the builder instance. ### What units does the memory parameter accept? The `--memory` flag and [`config.toml`](https://github.com/apple/container/blob/main/config.toml) values accept human-readable strings such as `1g`, `2g`, or `512m`. The `Sources/ContainerPersistence/Measurement+Parse.swift` module parses these strings into byte measurements for the runtime.