ifcfg - Python Network Interface Wrapper

0.24 · active · verified Thu Apr 16

Ifcfg is a cross-platform Python library designed for parsing the output of system network configuration commands like `ifconfig` (Unix/Linux/macOS) and `ipconfig` (Windows). It provides a structured way to access network interface information such as IP addresses, netmasks, MAC addresses, and hostnames. The library includes a fallback mechanism to the `ip` command for modern Unix systems where `ifconfig` might be deprecated or unavailable. Currently at version 0.24, it sees active maintenance with several releases per year to address compatibility and add features.

Common errors

```
RuntimeError: Got results that don't belong to a device
```
cause This error indicates that the `ifcfg` parser encountered a line in the `ifconfig` or `ip` command output that it couldn't associate with any known network interface device, likely due to an unexpected output format or malformed data.

fix This often points to an unexpected system command output format. Ensure your system's `ifconfig`/`ip` tools are standard versions. If running on a non-standard Linux/Unix distribution or an older/newer OS version, consider submitting an issue to the `ifcfg` GitHub repository with your `ifconfig`/`ip` output for review. Manually inspecting the raw command output might reveal discrepancies.
```
OSError: [Errno 2] No such file or directory: 'ifconfig'
```
cause The system could not find the `ifconfig` (or `ip`/`ipconfig` on other OSes) command in the system's PATH. `ifcfg` relies on executing these external commands to gather network interface information.

fix Install the necessary network utilities for your operating system (e.g., `net-tools` for `ifconfig` or `iproute2` for `ip` on Linux, which is usually installed by default). Ensure the directory containing the command (e.g., `/sbin` or `/usr/sbin`) is in your system's PATH environment variable.
```
KeyError: 'inet' or KeyError: 'ether'
```
cause Attempting to access a network interface property (e.g., 'inet', 'ether') that either doesn't exist for a particular interface or wasn't parsed successfully from the command output. This can happen if an interface lacks certain attributes (e.g., no IPv4 address) or if the parsing failed due to an unexpected output format.

fix Always use the `.get()` method when accessing interface dictionary keys, providing a default value (e.g., `interface_data.get('inet', 'N/A')` or `interface_data.get('inet4', [])`). If fields are unexpectedly missing, review the system's `ifconfig`/`ip` command output manually for that interface to ensure the data is present and correctly formatted for `ifcfg` to parse.

Warnings

breaking Starting with version 0.20, `ifcfg` will raise an exception if neither `ip` nor `ifconfig` commands are found on the system. Prior versions might have silently failed or returned empty results.
Fix: Ensure that `ifconfig` (or equivalent) or `ip` utilities are installed and accessible in the system's PATH. For Linux, `iproute2` (which provides `ip`) is generally preferred.
gotcha The parsing relies on regex patterns matching the output of `ifconfig`/`ipconfig`/`ip` commands. System locale settings can alter command output, leading to parsing failures or incomplete data. Version 0.21 introduced a fix to force the 'C' locale for command execution, but non-standard system configurations can still cause issues.
Fix: Upgrade to `ifcfg` 0.21 or newer. If issues persist, verify that your system's `ifconfig` or `ip` commands produce English-like output when run under a 'C' locale (e.g., `LC_ALL=C ifconfig`).
gotcha The `inet` field (single IPv4 address) is primarily for backward compatibility. Interfaces can have multiple IPv4 addresses. For comprehensive IPv4 address discovery, always use the `inet4` field, which returns a list of all IPv4 addresses for an interface.
Fix: When retrieving IPv4 addresses, iterate through `interface_data.get('inet4', [])` instead of relying solely on `interface_data.get('inet')`.

Install

pip install ifcfg Install ifcfg

Imports

ifcfg
```
import ifcfg
```

Quickstart

This quickstart retrieves all network interfaces and prints key details like MAC, IPv4, IPv6, netmask, and MTU. It then attempts to access specific details for a commonly named interface (e.g., 'eth0' on Linux or 'en0' on macOS).

import ifcfg
import json

interfaces = ifcfg.interfaces()

# Print all interfaces and their details
for name, interface_data in interfaces.items():
    print(f"Interface: {name}")
    print(f"  MAC Address: {interface_data.get('ether')}")
    print(f"  IPv4 Addresses: {interface_data.get('inet4')}")
    print(f"  IPv6 Addresses: {interface_data.get('inet6')}")
    print(f"  Netmask: {interface_data.get('netmask')}")
    print(f"  MTU: {interface_data.get('mtu')}")
    print("\n")

# Access a specific interface (e.g., 'eth0' or 'en0')
# Note: Interface names vary by OS and configuration
# Example: Get primary IPv4 for a common interface name
eth0_info = interfaces.get('eth0') or interfaces.get('en0') # Try common names
if eth0_info:
    print(f"Primary IPv4 for 'eth0' or 'en0': {eth0_info.get('inet')}")
    print(f"All IPv4s for 'eth0' or 'en0': {eth0_info.get('inet4')}")
else:
    print("Interface 'eth0' or 'en0' not found.")

view raw JSON →