How to Set Resource Limits for Containers Using `--cpus` and `--memory` Flags

Use the --cpus and --memory flags with container run, container builder start, or container machine create to allocate specific virtual CPU and memory resources to the lightweight VM that hosts your containers.

The apple/container project isolates workloads by running each container inside a lightweight virtual machine (VM) provisioned with default resources. By default, this VM receives 1 GiB of RAM and 4 vCPUs, but you can customize these allocations using the --cpus and --memory resource flags when you create or run containers.

Understanding Default VM Resource Allocation

The virtualization layer in container enforces specific defaults depending on the container type:

• Process containers (container run): 1 GiB RAM, 4 vCPUs
• Builder containers (container builder start): 2 GiB RAM, 2 vCPUs

You can inspect these defaults in the project documentation at docs/how-to.md.

Configuring CPU Limits with --cpus

The --cpus flag allocates a specific number of virtual CPUs to the VM.

According to the command reference in docs/command-reference.md and the implementation in Sources/CLI/ContainerCLI.swift, this flag accepts:

• Integer values (e.g., 2, 8)
• Fractional values (e.g., 1.5, 0.5)

The value passes directly to the macOS Virtualization framework, which caps the number of vCPUs the VM may schedule.

container run --rm --cpus 8 --memory 32g my-image

Setting Memory Limits with --memory

The --memory flag controls the VM's RAM allocation.

As documented in docs/how-to.md, this flag accepts size values with the following suffixes:

• K (kilobytes)
• M (megabytes)
• G (gigabytes)
• T (terabytes)
• P (petabytes)

The system allocates memory with 1 MiB granularity. If you omit this flag, the container inherits the default memory allocation.

container run --rm --cpus 4 --memory 8G alpine:latest

Applying Resource Flags to Process Containers

When running standard containers, append the flags to the container run command:

# Allocate 8 vCPUs and 32 GiB RAM

container run --rm --cpus 8 --memory 32g my-image

Optimizing Builder Container Resources

Builder containers require specific resource configurations for efficient builds. Use the same flags with container builder start:

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

To modify resources on an already-running builder, you must recreate the VM:

container builder stop
container builder delete
container builder start --cpus 8 --memory 32g

Provisioning Container Machines with Custom Resources

For persistent VM environments that host multiple containers, use container machine create:

container machine create --cpus 4 --memory 8G --set-default alpine:3.22

This creates a container machine VM with 4 vCPUs and 8 GiB RAM, as implemented in the CLI logic at Sources/CLI/ContainerCLI.swift.

Summary

• Process containers default to 4 vCPUs and 1 GiB RAM, while builder containers default to 2 vCPUs and 2 GiB RAM.
• Use --cpus <n> to allocate virtual CPUs, accepting integers or fractions like 1.5.
• Use --memory <size> to set RAM limits using suffixes K, M, G, T, or P with 1 MiB granularity.
• Apply these flags to container run, container builder start, and container machine create commands.
• Modify existing builder resources by stopping, deleting, and restarting the builder with new flags.

Frequently Asked Questions

What are the default resource limits for containers in apple/container?

Process containers receive 1 GiB of RAM and 4 vCPUs by default, while builder containers are allocated 2 GiB of RAM and 2 vCPUs. These defaults are defined in the docs/how-to.md documentation and enforced by the macOS Virtualization framework.

Can I use fractional CPU values with the --cpus flag?

Yes, the --cpus flag accepts fractional values such as 1.5 or 0.5. The implementation in Sources/CLI/ContainerCLI.swift passes these values directly to the underlying virtualization framework, allowing fine-grained control over CPU allocation.

How do I change resources for an existing builder container?

You cannot modify resources on a running builder directly. You must first stop the builder with container builder stop, delete it with container builder delete, and then recreate it using container builder start with the desired --cpus and --memory values.

What units does the --memory flag support?

The --memory flag supports size suffixes including K (kilobytes), M (megabytes), G (gigabytes), T (terabytes), and P (petabytes). The system allocates memory with 1 MiB granularity, as documented in the command reference at docs/command-reference.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}