sgl-project/sglang · error · ImportError

Environment variable SGLANG_LOCAL_IP_NIC requires package ne

Error message

Environment variable SGLANG_LOCAL_IP_NIC requires package netifaces, please install it through 'pip install netifaces'

What it means

Setting SGLANG_LOCAL_IP_NIC tells get_local_ip_by_nic to find the host IP attached to a specific NIC via the third-party netifaces package. If that package is not installed, the ImportError is re-raised with instructions to pip install netifaces.

Source

Thrown at python/sglang/srt/utils/network.py:273

    if socket_type == zmq.PUSH:
        set_send_opt()
    elif socket_type == zmq.PULL:
        set_recv_opt()
    elif socket_type in [zmq.DEALER, zmq.REQ, zmq.REP, zmq.PAIR]:
        set_send_opt()
        set_recv_opt()
    else:
        raise ValueError(f"Unsupported socket type: {socket_type}")


def get_local_ip_by_nic(interface: str = None) -> Optional[str]:
    if not (interface := interface or os.environ.get("SGLANG_LOCAL_IP_NIC", None)):
        return None
    try:
        import netifaces
    except ImportError as e:
        raise ImportError(
            "Environment variable SGLANG_LOCAL_IP_NIC requires package netifaces, please install it through 'pip install netifaces'"
        ) from e

    try:
        addresses = netifaces.ifaddresses(interface)
        if netifaces.AF_INET in addresses:
            for addr_info in addresses[netifaces.AF_INET]:
                ip = addr_info.get("addr")
                if ip and ip != "127.0.0.1" and ip != "0.0.0.0":
                    return ip
        if netifaces.AF_INET6 in addresses:
            for addr_info in addresses[netifaces.AF_INET6]:
                ip = addr_info.get("addr")
                if ip and not ip.startswith("fe80::") and ip != "::1":
                    return ip.split("%")[0]
    except (ValueError, OSError) as e:
        logger.warning(
            f"{e} Can not get local ip from NIC. Please verify whether SGLANG_LOCAL_IP_NIC is set correctly."

View on GitHub (pinned to 0132848349)

Solutions

pip install netifaces in the environment running sglang.
Or unset SGLANG_LOCAL_IP_NIC and rely on get_local_ip_by_remote fallback.
Prefer SGLANG_LOCAL_IP if a plain IP address is known — it avoids the dependency.

Example fix

# before
export SGLANG_LOCAL_IP_NIC=eth0  # ImportError: netifaces missing

# after
pip install netifaces
export SGLANG_LOCAL_IP_NIC=eth0

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if os.environ.get("SGLANG_LOCAL_IP_NIC") and importlib.util.find_spec("netifaces") is None:
    raise SystemExit("pip install netifaces or unset SGLANG_LOCAL_IP_NIC")

Prevention

Prefer SGLANG_LOCAL_IP with a literal IP to avoid the dependency.
Include netifaces in the environment lockfile when NIC selection is used.

When it happens

Trigger: Exporting SGLANG_LOCAL_IP_NIC=eth0 (or passing interface=...) on a host where netifaces is not in the environment.

Common situations: Multi-homed GPU nodes where users pin the interconnect NIC; minimal/conda environments missing the optional dependency.

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/17b8cfcf52f998bc. Report an issue: GitHub.