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.
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 in which network interfaces are brought up at boot. Each list entry names one of the supported interface types (ethernet, wifi, openthread, or modem) and may optionally specify a per-interface timeout. 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 decribed 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 SPI Ethernet — can declare a priority list to control the order in which interfaces are brought up at boot and which one ESPHome prefers when more than one is connected.

network:
  priority:
    - ethernet
    - wifi

In the example above, Ethernet is started first and used as the default route while it is connected; WiFi is started afterwards and is used only if Ethernet is unavailable. The first entry in the list is the most-preferred interface.

Each entry may either be a plain interface name or a mapping with an optional per-interface timeout:

network:
  priority:
    - ethernet:
        timeout: 30s
    - wifi

The timeout value bounds how long ESPHome waits for that interface to come up before starting the next one in the list. It accepts the usual ESPHome time format (for example 30s, 1min, 500ms). A plain integer is interpreted as seconds. When omitted, ESPHome waits indefinitely for that interface.

Configuration variables (priority entries)

interface (Required, string): One of ethernet, wifi, openthread, or modem. The entry is written as the interface name itself (either as a string list item or as the single key of a mapping). Each interface may appear at most once. Every interface named here must also have its own top-level component block configured.
timeout (Optional, Time): How long to wait for this interface to come up before moving on to the next one in the list. Defaults to waiting indefinitely.