# How to Configure Custom Subnets for Container Networks in Apple Container

> Configure custom subnets for container networks in Apple Container. Learn to use flags or config files for global defaults. Optimize your container networking.

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

---

**Use the `--subnet` and `--subnet-v6` flags when creating individual networks, or set the `subnet` and `subnetv6` keys in the `[network]` section of `~/.config/container/config.toml` to define global defaults for all new container networks.**

Container networking in the Apple Container runtime leverages macOS's `vmnet` framework to provide IPv4 and IPv6 connectivity for isolated workloads. While the system automatically assigns non-overlapping CIDR blocks when you create networks, production environments often require specific IP ranges for service discovery, firewall rules, or corporate network integration. This guide explains how to configure custom subnets for container networks using both CLI flags and configuration files, based on the official `apple/container` repository documentation.

## Per-Network Subnet Configuration with CLI Flags

When you need a specific CIDR block for a single network, pass explicit flags to the `container network create` command. According to the command reference in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (lines 777-791), the `--subnet` flag accepts an IPv4 CIDR, while `--subnet-v6` accepts an IPv6 CIDR.

### Creating a Network with Custom IPv4 and IPv6 Subnets

The following example creates a network named "frontend" with a custom IPv4 /24 and IPv6 /64 range:

```bash

# Create a network with explicit IPv4 and IPv6 subnets

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

```

As documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 317-322), these flags override any default settings and assign the specified ranges immediately upon network creation.

### Verifying Assigned Subnets

After creation, inspect the network to confirm the assigned ranges:

```bash
container ls --network frontend

```

The output displays the network name and the CIDR blocks that containers attached to this network will receive.

## Global Default Subnet Configuration

To avoid specifying subnets for every new network, configure default values in TOML configuration files. The runtime checks for settings in two locations: user-level configuration at `~/.config/container/config.toml` and system-wide configuration at [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml).

### User-Level Configuration

Create or edit `~/.config/container/config.toml` to set defaults for your user account. As specified in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 358-365) and the system configuration reference in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md) (lines 19-70), use the `[network]` section with the `subnet` and `subnetv6` keys:

```toml
[network]

# Default IPv4 subnet for networks created without an explicit --subnet flag

subnet = "192.168.100.0/24"

# Default IPv6 subnet for networks created without an explicit --subnet-v6 flag

subnetv6 = "fd00:abcd::/64"

```

### System-Wide Configuration

For multi-user systems, administrators can place the same `[network]` configuration in [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml). This applies the default subnets to all users on the system unless overridden by explicit CLI flags or user-level config files.

### Verifying Default Configuration

After saving the configuration file, create a network without subnet flags to verify the defaults apply:

```bash
container network create internal-net
container ls --network internal-net

```

The output should show `192.168.100.0/24` for IPv4 and `fd00:abcd::/64` for IPv6, confirming the settings from [`config.toml`](https://github.com/apple/container/blob/main/config.toml) are active.

## Subnet Validation and Overlap Detection

When you provide a custom subnet, the Apple Container runtime validates that the CIDR block does not overlap with existing container networks. If the check detects a conflict, the command aborts with an error indicating the colliding range. This safeguard ensures that containers on different networks can reach each other only through explicit routing, preventing accidental IP address collisions.

## Use Cases for Custom Subnets

Configuring explicit subnets provides several operational benefits:

- **Deterministic addressing:** Use known IP ranges for services that expect static addresses or hardcoded firewall rules.
- **Infrastructure integration:** Align container subnets with your corporate IP plan to simplify routing between container workloads and existing physical networks.
- **Conflict prevention:** On hosts running many networks, pre-assigning non-overlapping CIDRs prevents the automatic allocator from selecting ranges that collide with VPN clients or other network interfaces.

## Summary

- Use `--subnet` and `--subnet-v6` flags with `container network create` to configure custom subnets for individual networks
- Set global defaults by editing `~/.config/container/config.toml` or [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) with `[network]` section keys `subnet` and `subnetv6`
- The runtime validates custom subnets against existing networks to prevent overlapping CIDR blocks
- Custom subnets enable deterministic IP addressing and integration with existing infrastructure

## Frequently Asked Questions

### What is the default subnet range for container networks?

By default, the Apple Container runtime automatically selects non-overlapping IPv4 and IPv6 CIDR blocks from private ranges when creating networks. The specific ranges are chosen dynamically by the macOS `vmnet` framework to avoid conflicts with existing host networks.

### How do I check if a custom subnet overlaps with existing networks?

The runtime automatically performs overlap detection when you specify a custom subnet. If you attempt to create a network with a CIDR block that conflicts with an existing container network, the command aborts and displays an error indicating the conflicting range. You can also manually inspect existing networks using `container ls --network <name>` to view their assigned ranges before creating new ones.

### Can I customize subnets for existing networks?

No, you cannot modify the subnet configuration of an existing network after creation. To use a different subnet, you must create a new network with the desired CIDR block using `container network create` with the appropriate flags, then migrate containers to the new network.

### Where is the network configuration stored on macOS?

User-specific default subnets are stored in `~/.config/container/config.toml`, while system-wide defaults reside in [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml). Both files use TOML format with a `[network]` section containing `subnet` and `subnetv6` keys. Per-network configurations are stored internally by the runtime and managed through the `container network` CLI commands.