{"id":15717,"library":"network-interfaces","title":"Network Interface Utilities for Node.js","description":"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.","status":"abandoned","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/Wizcorp/network-interfaces","tags":["javascript","interface","interfaces","network","ip"],"install":[{"cmd":"npm install network-interfaces","lang":"bash","label":"npm"},{"cmd":"yarn add network-interfaces","lang":"bash","label":"yarn"},{"cmd":"pnpm add network-interfaces","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import ni from 'network-interfaces';","symbol":"ni","correct":"const ni = require('network-interfaces');"}],"quickstart":{"code":"const ni = require('network-interfaces');\n\ntry {\n  // Get all IPv4 external interface names\n  const externalIpv4Interfaces = ni.getInterfaces({\n    internal: false,\n    ipVersion: 4\n  });\n  console.log('External IPv4 Interfaces:', externalIpv4Interfaces);\n\n  if (externalIpv4Interfaces.length > 0) {\n    const firstInterfaceName = externalIpv4Interfaces[0];\n    // Get the first IPv4 address for a specific interface\n    const firstIpv4 = ni.toIp(firstInterfaceName, { ipVersion: 4 });\n    console.log(`First IPv4 address for ${firstInterfaceName}:`, firstIpv4);\n\n    // Get the interface name from an IP address (e.g., localhost)\n    const loopbackInterface = ni.fromIp('127.0.0.1');\n    console.log('Interface for 127.0.0.1:', loopbackInterface);\n  } else {\n    console.log('No external IPv4 interfaces found.');\n  }\n\n} catch (error) {\n  console.error('An error occurred:', error.message);\n}","lang":"javascript","description":"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."},"warnings":[{"fix":"Migrate to `os.networkInterfaces()` for core functionality or consider an actively maintained alternative. Ensure thorough testing on your target Node.js version.","message":"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.","severity":"breaking","affected_versions":">=1.1.1 (all versions are effectively unmaintained)"},{"fix":"Always wrap calls to potentially failing functions in `try...catch` blocks: `try { const ip = ni.toIp('nonexistent'); } catch (e) { console.error(e.message); }`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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`).","error":"Error: No IP address found for interface 'eth0'"},{"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.","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.","error":"Error: No network interface name found for IP address '192.168.1.1'"},{"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.","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.","error":"TypeError: ni.toIp is not a function"}],"ecosystem":"npm"}