# How to Configure CPU and Memory Limits for Containers in Apple Container

> Configure CPU and memory limits for containers using CLI flags or config files. Optimize resource allocation and prevent performance issues in Apple Container.

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

---

**Set CPU and memory limits using the `--cpus` and `--memory` CLI flags to override system defaults defined in [`config.toml`](https://github.com/apple/container/blob/main/config.toml), or modify the `[container]` table in `~/.config/container/config.toml` to change defaults persistently.**

Apple Container provides a three-tier configuration system for resource management. You can define CPU and memory constraints through system-wide configuration files, override them per-container using command-line arguments, or set machine-specific baselines for named environments. This layered approach ensures containers receive appropriate resources without requiring repetitive CLI arguments for every invocation.

## Understanding the Configuration Hierarchy

The `apple/container` tooling resolves resource limits through a precedence-based model defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift). The system evaluates configuration in this order:

1. **System-wide defaults** from `~/.config/container/config.toml`
2. **Per-machine defaults** for named container machines
3. **Command-line overrides** passed to specific commands

When you execute a command like `container run`, the system first loads the base configuration from [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) (which defines **4 vCPUs** and **1 GiB of memory** as defaults), applies any machine-specific settings from the `[machine]` table, then substitutes explicit `--cpus` or `--memory` values to produce the final `ContainerConfig` object passed to the runtime.

## Setting Resource Limits via CLI

The `container run` and `container create` commands expose `--cpus` and `--memory` flags that temporarily override configuration file settings. These flags accept integer values for CPU cores and human-readable memory strings (e.g., `16g`, `512m`) parsed by `Sources/ContainerPersistence/Measurement+Parse.swift`.

```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

```

Builder VMs and container machines support the same flags with their own default values:

```bash

# Builder defaults are typically 2 CPUs, 2 GiB RAM

container builder start --cpus 6 --memory 8g

# Create a machine with specific resources

container machine create --cpus 4 --memory 8g dev-machine

```

## Configuring Persistent Defaults in config.toml

To avoid repeating CLI flags, modify the `[container]` table in `~/.config/container/config.toml`. According to [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md), this file stores system-wide defaults that persist across sessions.

```toml

# ~/.config/container/config.toml

[container]
cpus = 2               # Default to 2 vCPUs per container

memory = "2g"         # Default to 2 GiB RAM per container

```

These values override the hardcoded defaults in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) (where `defaultCPUs = 4` and `defaultMemory = "1g"` are defined) for all subsequent container operations.

## Managing Machine-Specific Resources

Named container machines support independent resource profiles through the `[machine]` section in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) or via the `container machine set` command documented in [`docs/container-machine.md`](https://github.com/apple/container/blob/main/docs/container-machine.md).

```bash

# Set defaults for a machine named "dev"

container machine set -n dev cpus=4 memory=8G

```

These settings apply to future `container machine create -n dev` invocations unless explicitly overridden by CLI flags. This allows you to maintain different resource profiles for development, testing, and production environments.

## Summary

- **Configuration layers**: System defaults ([`config.toml`](https://github.com/apple/container/blob/main/config.toml)) → Machine settings (`[machine]` table) → CLI flags (`--cpus`, `--memory`)
- **Default values**: 4 vCPUs and 1 GiB RAM defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift)
- **CLI syntax**: `--cpus <int>` and `--memory <string>` (e.g., `16g`, `512m`)
- **Config file location**: `~/.config/container/config.toml` under the `[container]` table
- **Memory parsing**: Human-readable units handled by `Measurement+Parse.swift`

## Frequently Asked Questions

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

The default values of **4 vCPUs** and **1 GiB of memory** are hardcoded in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) within the `ContainerSystemConfig` struct. These values apply when no configuration file exists and no CLI flags are provided.

### What units does the `--memory` flag accept?

The `--memory` flag accepts human-readable strings parsed by `Sources/ContainerPersistence/Measurement+Parse.swift`. Valid formats include `32g` (gibibytes), `512m` (mebibytes), or `2G` (gigabytes). The parser handles both uppercase and lowercase suffixes.

### Can I set different limits for the builder VM?

Yes. The `container builder start` command accepts `--cpus` and `--memory` flags to configure the builder VM resources independently from running containers. Builder VMs typically default to 2 CPUs and 2 GiB RAM unless overridden.

### How do I change resources for an existing container machine?

Use `container machine set -n <machine-name> cpus=<value> memory=<value>` to modify default resources for a named machine. These changes affect future instances created with `container machine create` but do not retroactively modify currently running machines.