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

> Learn how to set resource limits for containers using --cpus and --memory flags. Allocate specific virtual CPU and memory for your container VMs.

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

---

**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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/docs/command-reference.md) and the implementation in [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/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.

```bash
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`](https://github.com/apple/container/blob/main/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.

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

```bash

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

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

```

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

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

```bash
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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/docs/command-reference.md).