# How to Configure Custom Container Networks with Specific Subnets on macOS 26 > Learn to configure custom container networks with specific subnets on macOS 26. Use container network create with subnet flags for precise IPv4 and IPv6 control via vmnet. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-29 --- **Use the `container network create` command with `--subnet` and `--subnet-v6` flags to define IPv4 and IPv6 CIDR blocks, which the runtime validates and binds to the macOS vmnet framework via the `NetworkConfiguration` object.** The `apple/container` repository provides a native container runtime for macOS that leverages the vmnet framework to create isolated virtual networks. When running containers on macOS 26 (Sequoia), you can define custom network subnets to segment traffic and avoid IP conflicts with existing networks. This article explains how the CLI translates your subnet parameters into vmnet configurations and how to manage these networks throughout their lifecycle. ## How Container Networking Works on macOS The `container` tool implements networking through the macOS vmnet framework, creating Layer 2 segments that operate independently of your host's physical interfaces. When you execute `container network create`, the CLI constructs a **`NetworkConfiguration`** object defined in [`Sources/ContainerResource/Network/NetworkConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Network/NetworkConfiguration.swift). This structure captures your specified subnets in the `ipv4Subnet` and `ipv6Subnet` fields, then serializes them for the backend service. The **`NetworksService`** actor ([`Sources/ContainerAPIService/Server/Networks/NetworksService.swift`](https://github.com/apple/container/blob/main/Sources/ContainerAPIService/Server/Networks/NetworksService.swift)) handles the server-side validation. It checks that your CIDR blocks do not overlap with existing networks before instantiating either an `AllocationOnlyVmnetNetwork` or `ReservedVmnetNetwork` from the `Sources/NetworkVmnet/Server/` directory. These implementations translate the configuration into actual vmnet allocations managed by the operating system. ## Creating Networks with Custom Subnets ### Specifying IPv4 and IPv6 CIDR Blocks To create an isolated network with specific address ranges, use the `--subnet` and `--subnet-v6` flags during network creation. The runtime accepts standard CIDR notation and validates the syntax before committing the configuration. ```bash # Create a custom network with explicit IPv4 and IPv6 subnets container network create foo \ --subnet 192.168.100.0/24 \ --subnet-v6 fd00:1234::/64 ``` If you omit these flags, the runtime consults the user-wide configuration file at `~/.config/container/config.toml` for default values. ### Validating Network Configuration After creation, verify that the network exists with your specified parameters: ```bash container network list ``` The output displays the network name, state, and allocated subnets: ``` NETWORK STATE SUBNET default running 192.168.64.0/24 foo running 192.168.100.0/24 ``` The `NetworksService` prevents overlapping subnets during creation. If you attempt to define a CIDR block that intersects with an existing network, the command fails before modifying the vmnet framework. ## Configuring Default Subnet Ranges If you regularly use specific subnet ranges, modify the defaults in `~/.config/container/config.toml` to avoid repetitive flag usage: ```toml [network] subnet = "192.168.100.0/24" subnetv6 = "fd00:abcd::/64" ``` These values apply to any future `container network create` commands that omit the `--subnet` or `--subnet-v6` flags. The configuration file is read during the initialization phase of the `NetworksService` before building the `NetworkConfiguration` object. ## Attaching Containers to Custom Networks Once a network exists, attach containers using the `--network` flag. The runtime assigns IP addresses from your defined CIDR blocks via the vmnet DHCP service. ```bash # Run a container attached to the custom network container run -d --name my-web-server \ --network foo \ --rm web-test ``` Verify the container received an address from the correct subnet: ```bash container ls ``` The output shows the assigned IP within your custom range: ``` ID IMAGE OS ARCH STATE IP my-web-server web-test linux arm64 running 192.168.100.2 ``` Containers attached to the same network communicate directly at Layer 2, while remaining isolated from containers on other networks. ## Managing and Removing Networks Network deletion requires that no containers remain attached. Follow this workflow to clean up resources: ```bash # Stop any running containers on the network container stop my-web-server # Remove the network definition container network delete foo ``` The `NetworksService` checks for active allocations before removing the vmnet interface. If containers are still running, the command returns an error indicating dependencies exist. ## Summary - The `container` CLI uses the macOS vmnet framework through `NetworkConfiguration` objects defined in [`NetworkConfiguration.swift`](https://github.com/apple/container/blob/main/NetworkConfiguration.swift) to manage subnets. - Specify custom CIDR blocks with `--subnet` and `--subnet-v6` flags during `container network create`. - Default subnets can be configured permanently in `~/.config/container/config.toml`. - The `NetworksService` validates CIDR syntax and prevents overlapping networks before instantiating vmnet interfaces via `AllocationOnlyVmnetNetwork` or `ReservedVmnetNetwork`. - Attach containers with `--network ` and remove networks only after stopping all dependent containers. ## Frequently Asked Questions ### Can I use any subnet range for container networks on macOS 26? The `container` runtime validates that your CIDR blocks do not overlap with existing container networks or the host's network interfaces. According to the [`NetworksService.swift`](https://github.com/apple/container/blob/main/NetworksService.swift) implementation, the system checks for conflicts before creating the vmnet interface. Private ranges such as `192.168.x.x/24` or IPv6 ULA addresses like `fd00::/64` work correctly, provided they are not already allocated. ### What happens if I don't specify subnet flags when creating a network? When `--subnet` or `--subnet-v6` are omitted, the runtime reads default values from `~/.config/container/config.toml`. If no defaults exist in that file, the system uses built-in fallback ranges. The `NetworkConfiguration` initialization in [`NetworkConfiguration.swift`](https://github.com/apple/container/blob/main/NetworkConfiguration.swift) handles this merge logic between CLI flags and configuration file values. ### How do containers receive IP addresses from my custom subnet? The vmnet framework provides DHCP services automatically. When you attach a container with `--network`, the `AllocationOnlyVmnetNetwork` or `ReservedVmnetNetwork` implementation requests an IP from the vmnet subsystem, which allocates an address from the CIDR range defined in your `NetworkConfiguration`. You can view the assigned address using `container ls`. ### Why does network deletion fail with a dependency error? The `NetworksService` maintains referential integrity between networks and running containers. If you attempt `container network delete` while containers are still attached, the service returns an error because the vmnet interface cannot be destroyed while in use. You must stop and remove all containers on the network before the deletion succeeds.