# How to Configure CPU, Memory, and Disk Resources in Apple Container

> Learn how to configure CPU, memory, and disk resources for Apple Container using config.toml and CLI flags. Optimize your container performance today.

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

---

**Resource limits in Apple Container are configured through the [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file for persistent defaults and CLI flags for per-container overrides, while disk space is managed via system-wide housekeeping commands.**

Apple Container runs each workload inside a lightweight virtual machine, requiring explicit configuration of compute resources to ensure optimal performance. Understanding how to configure container resources prevents resource contention on macOS hosts and ensures workloads receive adequate CPU and memory. This guide covers the configuration file schema, command-line overrides, and disk management strategies based on the `apple/container` source code.

## Setting Persistent Defaults in config.toml

Apple Container stores persistent defaults in the `[container]` section of [`config.toml`](https://github.com/apple/container/blob/main/config.toml). These values apply to every container unless explicitly overridden.

### The Configuration File Location

The user-specific configuration file resides at `~/.config/container/config.toml`. When you execute `container run` or `container create` without explicit resource flags, the system reads these defaults.

### CPU and Memory Syntax

Set default **vCPUs** using the `cpus` key (integer) and **RAM** using the `memory` key (quoted string). According to the schema in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md), the default configuration allocates **4 CPUs** and **1 GB** of memory:

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

```

### MemorySize Format

The `memory` field accepts binary units: `b` (bytes), `k` (kibibytes), `m` (mebibytes), `g` (gibibytes), `t` (tebibytes), and `p` (pebibytes). The parser is case-insensitive and implemented in `Sources/TerminalProgress/Measurement+Parse.swift`.

Example configuration:

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

```

## Overriding Resources with CLI Flags

For per-command overrides, use the `--cpus` and `--memory` flags with `container run`, `container create`, or `container builder start`. These flags allocate specific resources to the backing VM for that container instance.

### Flag Syntax

Both flags accept the same binary units as the configuration file. For example:

```bash
container run --rm --cpus 8 --memory 32g myimage

```

If omitted, the command inherits values from [`config.toml`](https://github.com/apple/container/blob/main/config.toml). As documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md), CLI flags take precedence over file-based defaults.

## Managing Disk Usage

Unlike CPU and memory, Apple Container does not enforce per-container disk quotas. Instead, disk usage accumulates across images, containers, and volumes on the host filesystem.

### Inspecting Disk Consumption

Use `container system df` to view total, used, and reclaimable space across all resources. This command reports storage statistics as referenced in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md).

### Reclaiming Space

Run `container system prune` to remove stopped containers, dangling images, and unused volumes. For a more aggressive cleanup that removes all unused images, add the `-a` flag.

```bash

# View current usage

container system df

# Remove unused resources

container system prune -a

```

## Summary

- Configure persistent CPU and memory defaults in `~/.config/container/config.toml` under the `[container]` section.
- Override defaults per container using `--cpus` and `--memory` flags with binary units (k, m, g, t).
- Disk space is managed system-wide via `container system df` and `container system prune`; no per-container limits exist.
- Memory values are parsed by the helper in `Sources/TerminalProgress/Measurement+Parse.swift` using standard binary prefixes.

## Frequently Asked Questions

### Where is the Apple Container configuration file located?

The configuration file is located at `~/.config/container/config.toml`. This user-specific file stores default resource allocations that apply to every container unless overridden by CLI flags.

### Can I set disk quotas per container in Apple Container?

No, Apple Container does not support per-container disk quotas. Containers, images, and volumes share the host filesystem. You manage disk usage globally using `container system df` to inspect usage and `container system prune` to reclaim space from stopped containers and unused images.

### What units are supported for memory allocation?

Apple Container supports binary size units: `b` (bytes), `k` (kibibytes), `m` (mebibytes), `g` (gibibytes), `t` (tebibytes), and `p` (pebibytes). These are case-insensitive and parsed by the `Measurement+Parse.swift` utility in the source code.

### Do CLI flags override config.toml settings?

Yes. When you specify `--cpus` or `--memory` on the command line with `container run`, `container create`, or `container builder start`, these values take precedence over the defaults defined in [`config.toml`](https://github.com/apple/container/blob/main/config.toml). If no flags are provided, the system falls back to the configuration file values.