# How to Create a Container Network with a Custom Subnet in Apple Container

> Learn how to create a container network with a custom subnet in Apple Container using flags or configuration files. Easily customize your network settings.

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

---

**Create a network with a custom subnet by passing the `--subnet` and `--subnet-v6` flags to `container network create`, or configure default subnets permanently in `~/.config/container/config.toml` under the `[network]` section.**

The Apple Container runtime leverages macOS's `vmnet` framework to provide network isolation for containers. While the system automatically assigns non-overlapping CIDR blocks when you create networks, you can define custom IPv4 and IPv6 subnets to ensure deterministic container addressing that aligns with your infrastructure requirements.

## Setting a Custom Subnet During Network Creation

You can specify exact CIDR ranges when creating individual networks using command-line flags. According to the documentation in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 317-322), the `--subnet` flag accepts an IPv4 CIDR block, while `--subnet-v6` accepts an IPv6 CIDR block.

Create a network named `frontend` with specific IPv4 and IPv6 ranges:

```bash
container network create frontend \
    --subnet 192.168.200.0/24 \
    --subnet-v6 fd00:dead:beef::/64

```

As documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (lines 777-791), these flags map directly to the network configuration stored by the runtime. After creation, containers attached to this network will receive IP addresses from the specified `192.168.200.0/24` and `fd00:dead:beef::/64` pools.

## Configuring Default Subnets Globally

To avoid specifying subnets for every new network, configure default values in TOML configuration files. This applies to all networks created without explicit `--subnet` flags.

### User-Level Configuration

Create or edit `~/.config/container/config.toml` to set personal defaults:

```toml
[network]

# Default IPv4 subnet for networks created without --subnet

subnet = "192.168.100.0/24"

# Default IPv6 subnet for networks created without --subnet-v6

subnetv6 = "fd00:abcd::/64"

```

As noted in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 358-365), these values apply to all networks created by the current user when explicit flags are omitted.

### System-Wide Configuration

For multi-user environments, place the same `[network]` configuration in [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml). This system-level file uses identical TOML keys and applies to all users on the machine, as detailed in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md) (lines 19-70).

## Validation and Conflict Prevention

The runtime implements overlap detection to prevent IP conflicts. When you specify a custom subnet, the system validates that the CIDR block does not intersect with any existing container network. If a conflict is detected, the `container network create` command aborts with an error specifying the overlapping range. This safeguard ensures network isolation is maintained unless explicitly routed otherwise.

## Verifying Network Configuration

After creating a network, inspect its assigned subnets using the list command:

```bash
container ls --network frontend

```

The output displays the network name and the specific CIDR blocks that attached containers will receive, confirming whether your custom subnets or the defaults were applied.

## Summary

- Use `container network create <name> --subnet <CIDR> --subnet-v6 <CIDR>` for per-network custom subnets
- Configure persistent defaults in `~/.config/container/config.toml` or [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) under the `[network]` section using the `subnet` and `subnetv6` keys
- The runtime validates custom subnets against existing networks to prevent overlap
- Verify assigned subnets with `container ls --network <name>`

## Frequently Asked Questions

### Can I specify both IPv4 and IPv6 subnets simultaneously?

Yes. The `container network create` command accepts both `--subnet` for IPv4 and `--subnet-v6` for IPv6 in a single invocation. For example: `--subnet 192.168.10.0/24 --subnet-v6 fd00::/64`. Both ranges will be assigned to the network and containers will receive addresses from each family.

### What happens if my custom subnet overlaps with an existing network?

The command fails with an error indicating the conflicting range. The Apple Container runtime checks for subnet overlap during creation to ensure that containers on different networks remain isolated unless explicitly connected through routing.

### Where are the default subnet configurations stored?

User-specific defaults reside in `~/.config/container/config.toml`, while system-wide defaults are located in [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml). Both use the same TOML structure with a `[network]` section containing `subnet` and `subnetv6` keys, as defined in the system configuration documentation.

### Do changes to the config file affect existing networks?

No. Modifications to either the user or system configuration files only apply to networks created after the change. Existing networks retain their original subnet assignments unless explicitly removed and recreated with new parameters.