Network component

The network component is a global configuration for all types of networks (WiFi, Ethernet).

# Example configuration
network:
    enable_ipv6: true
    min_ipv6_addr_count: 2
    enable_high_performance: true

Configuration variables

enable_ipv6 (Optional, boolean): Enables IPv6 support. Defaults to false. Always true on nRF52 because IPv4 is not supported.
min_ipv6_addr_count (Optional, integer): ESPHome considers the network to be connected when it has one IPv4 address and this number of IPv6 addresses. Defaults to 0 so as to not hang on boot with networks where IPv6 is not enabled. 2 is typically a reasonable value for configurations requiring IPv6.
enable_high_performance (Optional, boolean): Explicitly enables or disables high-performance networking optimizations. Only supported on ESP32 devices. When not specified, this is automatically enabled by components that benefit from optimized network settings. Set to false to disable these optimizations if they cause memory issues on your device. Defaults to component-driven behavior.
priority (Optional, list): Order of preference for network interfaces when more than one is configured. Only supported on the ESP32 family of devices. Each list entry names one of the supported interface types (ethernet or wifi); the first entry is the most preferred. Required when both ethernet: and wifi: are configured, and must then list every configured interface. See Multi-Interface Support.

High-performance networking

The network component can automatically apply optimized settings for components that require high throughput or low latency, such as media streaming. When enabled, this feature configures both the lwIP TCP/IP stack and WiFi driver with settings optimized for performance.

PSRAM-Aware Optimizations

The optimization level depends on whether PSRAM is guaranteed to be available (configured via the Psram component with ignore_not_found: false):

With PSRAM guaranteed:

TCP send/receive buffers: 512KB windows with window scaling enabled
WiFi RX buffers: 512 dynamic buffers
WiFi TX buffers: 32 static buffers
AMPDU aggregation: Optimized block acknowledgment windows

Without PSRAM (or when not guaranteed):

TCP send/receive buffers: 65KB windows
WiFi RX buffers: 64 dynamic buffers
WiFi TX buffers: 64 dynamic buffers
AMPDU aggregation: Standard block acknowledgment windows

NOTE

The lwIP library used for the network component currently only implements IPv6 SLAAC according to RFC4862. The interface identifier (IID) is directly generated from the device MAC address. This has various security and privacy implications described in RFC7721, as this might leak outside of the smart home network and makes the device uniquely identifiable. Therefore, the address generation does not comply to RFC7217.

Multi-Interface Support

Devices with more than one network interface — for example an ESP32 with both WiFi and Ethernet — can declare a priority list stating which interface ESPHome should prefer. This list is required to use wifi: and ethernet: together; without it, configuring both is rejected during validation, matching the single-interface behavior of earlier releases.

network:
  priority:
    - ethernet
    - wifi

Each entry is a plain interface name, either ethernet or wifi. Each interface may appear at most once, and the list and the configuration must match in both directions: every interface named in the list must have its own component block configured, and every configured interface must appear in the list — with both wifi: and ethernet: present, priority naming only one of them is rejected during validation. The first entry is the most-preferred interface. Support for other interface types is planned.

The priority list controls three things:

Setup order: interfaces are brought up at boot in list order, so the preferred interface connects first.
Reported address: the preferred interface determines the address used to reach the device — its use_address (when configured) applies, and its IP addresses are the ones ESPHome reports. If the preferred interface has no valid IP address, for example while it is disabled or still connecting, ESPHome falls back to the other interface’s addresses.
Default route: the first connected interface in the list carries the device’s outgoing traffic. When that interface loses its connection — cable unplugged, link lost, or disabled at runtime — the route moves to the next connected interface automatically, and moves back when the preferred interface reconnects. The DNS servers of the interface that owns the route are used. Every change is logged as Default interface: ....

Running both network stacks at the same time uses a significant amount of memory. To keep the less-preferred interface powered down until it is needed, set enable_on_boot: false on that interface and turn it on later with the wifi.enable or ethernet.enable action. A powered-down interface cannot take over the route automatically; it participates in failover only once it has been enabled.