# How to Configure Custom Subnets for Container Networks on macOS

> Learn how to configure custom subnets for container networks on macOS. Use the --subnet flag or config file for flexible network setups.

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

---

**You can configure custom subnets for Apple Container networks by using the `--subnet` and `--subnet-v6` flags when creating a network, or by setting default values in the `~/.config/container/config.toml` configuration file.**

The **Apple Container** runtime leverages macOS's `vmnet` framework to provide network connectivity for containers. By default, the system automatically assigns non-overlapping IPv4 and IPv6 CIDR blocks, but you can explicitly define custom subnets to ensure deterministic addressing or integrate with existing infrastructure. This guide covers the specific methods to configure these subnets at both the network and system level according to the `apple/container` source code.

## Setting Custom Subnets Per Network

When creating a new container network, you can explicitly define the IPv4 and IPv6 ranges using command-line flags. This approach overrides any default settings for that specific network.

### Using the --subnet and --subnet-v6 Flags

According to [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 317-322), the `container network create` command accepts `--subnet` for IPv4 and `--subnet-v6` for IPv6 CIDR notation. The runtime validates that these ranges do not conflict with existing container networks before creation.

```bash

# Create a network named "frontend" with specific IPv4 and IPv6 ranges

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 accept standard CIDR notation. After creation, verify the assigned subnets using:

```bash
container ls --network frontend

```

## Configuring Default Subnets Globally

To avoid specifying subnets for every new network, you can configure default values in TOML configuration files. The runtime checks these defaults whenever you omit the `--subnet` or `--subnet-v6` flags.

### User-Level Configuration

Edit or create the file at `~/.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), use the `[network]` section with the `subnet` and `subnetv6` keys:

```toml
[network]

# Default IPv4 subnet for new networks

subnet = "192.168.100.0/24"

# Default IPv6 subnet for new networks

subnetv6 = "fd00:abcd::/64"

```

After saving the configuration, any subsequent `container network create` command that omits explicit subnet flags will automatically use these values. You can verify this by creating a test network and inspecting its configuration:

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

```

### System-Wide Configuration

For multi-user systems, administrators can set defaults in [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) using the same TOML structure. As documented in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md) (lines 19-70), this file uses identical `[network]` section keys (`subnet` and `subnetv6`) to define system-wide defaults that apply to all users unless overridden by user-level configs or CLI flags.

## Validation and Overlap Detection

The Apple Container runtime implements safeguards to prevent network conflicts. When you specify a custom subnet—whether via CLI or configuration file—the system checks against existing container networks to ensure no overlap exists. If the requested CIDR block conflicts with an active network, the command aborts with an error indicating the specific conflicting range. This ensures that containers on separate networks can only communicate through explicit routing configurations.

## Summary

- **Per-network configuration**: Use `--subnet` and `--subnet-v6` flags with `container network create` to specify exact CIDR blocks for individual networks.
- **Global defaults**: Set `subnet` and `subnetv6` keys in the `[network]` section of `~/.config/container/config.toml` for user-level defaults, or [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) for system-wide defaults.
- **Validation**: The runtime automatically checks for subnet overlaps and prevents creation of conflicting networks.
- **Documentation**: Reference [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md), [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md), and [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) in the `apple/container` repository for authoritative syntax details.

## Frequently Asked Questions

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

The Apple Container runtime performs automatic validation when you create a network with custom subnets. If the provided CIDR block overlaps with an existing container network, the `container network create` command fails immediately with an error message identifying the conflicting range. You can also inspect existing networks using `container ls --network <name>` to view current subnet allocations before creating new ones.

### What configuration file format does Apple Container use?

Apple Container uses **TOML** (Tom's Obvious, Minimal Language) for configuration files. The user-level config resides at `~/.config/container/config.toml`, while system-wide settings are stored in [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml). Both files use a `[network]` section containing `subnet` for IPv4 and `subnetv6` for IPv6 CIDR definitions, as defined in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md).

### Can I set different default subnets for individual users versus system-wide?

Yes. The runtime supports hierarchical configuration: user-level settings in `~/.config/container/config.toml` take precedence over system-wide settings in [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml), which in turn take precedence over built-in defaults. This allows administrators to define baseline subnets in [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) while permitting individual users to override them with personal configurations.

### Does Apple Container support both IPv4 and IPv6 custom subnets?

Yes. The runtime supports dual-stack networking. Use the `--subnet` flag for IPv4 CIDR notation and `--subnet-v6` for IPv6 when creating networks via CLI. In configuration files, set the `subnet` key for IPv4 and `subnetv6` for IPv6. Both can be specified simultaneously to create networks with full dual-stack connectivity.