Network Interface Utilities for Node.js

1.1.0 · abandoned · verified Tue Apr 21

The `network-interfaces` package provides synchronous utility functions for retrieving and filtering network interface and IP address information in Node.js. It acts as a wrapper around Node.js's built-in `os.networkInterfaces()` method, offering simplified functions like `toIp`, `toIps`, `fromIp`, `getInterface`, and `getInterfaces` with optional filtering by internal status and IP version (IPv4/IPv6). The current stable version is 1.1.0, last published in 2017. Due to its age and lack of maintenance, it is considered abandoned. Users are encouraged to directly use `os.networkInterfaces()` or seek more actively maintained alternatives for robust network interface management in modern Node.js applications, especially if TypeScript support or ESM compatibility is required.

Common errors

```
Error: No IP address found for interface 'eth0'
```
cause The specified network interface name either does not exist on the system or has no IP addresses matching the filter criteria (e.g., `ipVersion`, `internal`).

fix Verify the interface name and ensure your filtering options (e.g., `ipVersion: 4`, `internal: false`) correctly match available addresses. Use `ni.getInterfaces()` to list existing interfaces with their properties.
```
Error: No network interface name found for IP address '192.168.1.1'
```
cause The provided IP address is not associated with any active network interface on the system, or it does not match the specified filter options.

fix Confirm the IP address is active and correctly configured on one of the system's network interfaces. Adjust filtering options if they are too restrictive.
```
TypeError: ni.toIp is not a function
```
cause This typically occurs in an ESM context where `require` is not used, or if the import statement is incorrect for a CommonJS-style package.

fix Ensure you are using `const ni = require('network-interfaces');` in CommonJS modules (`.js` files without `"type": "module"` in `package.json` or `.cjs` files). If using ESM, be aware of the package's age and potential lack of native ESM support; a bundler might be needed or consider `import * as ni from 'network-interfaces';` as a fallback, though direct `os.networkInterfaces` is preferred for modern projects.

Warnings

breaking The package is considered abandoned and has not been updated since 2017. It may not be compatible with newer Node.js versions or incorporate modern features/fixes. Direct usage of Node.js's built-in `os.networkInterfaces()` is recommended for better compatibility and maintenance.
Fix: Migrate to `os.networkInterfaces()` for core functionality or consider an actively maintained alternative. Ensure thorough testing on your target Node.js version.
gotcha Several functions (`toIp`, `fromIp`, `getInterface`) throw a synchronous `Error` if no matching interface or IP address is found, rather than returning `null` or an empty array. This requires explicit `try...catch` blocks for robust error handling.
Fix: Always wrap calls to potentially failing functions in `try...catch` blocks: `try { const ip = ni.toIp('nonexistent'); } catch (e) { console.error(e.message); }`
gotcha The library does not provide TypeScript type definitions natively. While `@types/network-interfaces` exists, its maintenance status should be verified independently. Using the package in a TypeScript project without up-to-date types will result in type errors.
Fix: Install `@types/network-interfaces` (`npm install --save-dev @types/network-interfaces`) or define custom types if the `@types` package is outdated. For new projects, consider libraries with native TypeScript support.
gotcha The filtering options (`internal` and `ipVersion`) only acknowledge exact matches. For instance, `ipVersion: 4` will exclude IPv6 addresses entirely, and `internal: false` will strictly filter out loopback interfaces. Be precise with your filter requirements.
Fix: Carefully define your `options` object based on whether you need internal/external interfaces or specific IP versions. If both are needed, omit the respective filter property.

Install

npm install network-interfaces npm
yarn add network-interfaces yarn
pnpm add network-interfaces pnpm

Imports

ni
wrong:
```
import ni from 'network-interfaces';
```
correct:
```
const ni = require('network-interfaces');
```
The package was published before widespread ESM adoption in Node.js. While `import ni from 'network-interfaces';` might work with bundlers or Node.js's ESM loader, it's primarily designed for CommonJS. There are no explicit ESM exports.

Quickstart

This quickstart demonstrates how to use `network-interfaces` to find external IPv4 interface names, retrieve an IP address for a given interface, and determine an interface name from a specific IP address, including error handling.

const ni = require('network-interfaces');

try {
  // Get all IPv4 external interface names
  const externalIpv4Interfaces = ni.getInterfaces({
    internal: false,
    ipVersion: 4
  });
  console.log('External IPv4 Interfaces:', externalIpv4Interfaces);

  if (externalIpv4Interfaces.length > 0) {
    const firstInterfaceName = externalIpv4Interfaces[0];
    // Get the first IPv4 address for a specific interface
    const firstIpv4 = ni.toIp(firstInterfaceName, { ipVersion: 4 });
    console.log(`First IPv4 address for ${firstInterfaceName}:`, firstIpv4);

    // Get the interface name from an IP address (e.g., localhost)
    const loopbackInterface = ni.fromIp('127.0.0.1');
    console.log('Interface for 127.0.0.1:', loopbackInterface);
  } else {
    console.log('No external IPv4 interfaces found.');
  }

} catch (error) {
  console.error('An error occurred:', error.message);
}

view raw JSON →