Skip to content package
ipaddr.js v2.4.0 A library for manipulating IPv4 and IPv6 addresses in JavaScript.
node >= 10 0 deps cjs types open source
overview readme
license MIT
deps 0
unpacked 62.3 kB
files 6
node >= 10 $ npm install ipaddr.js@2.4.0n npmREADME GitHub-flavored package documentation.
downloads Across all versions.
Download trend unavailable.
compatibility Runtime metadata.
versions Latest published Aug 4, 2026
maintainers Registry package owners.
install size Estimated unpacked size across 1 packages.
62.9 kB
Includes dependencies.
contents ipaddr.js — an IPv4 and IPv6 address manipulation library
ipaddr.js is a library for manipulating IPv4 and IPv6 addresses in JavaScript. It runs in Node.js and in browsers.
It lets you parse and validate addresses, match them against CIDR ranges, classify them into named ranges (loopback, private, reserved, etc.), convert between IPv4 and IPv6 representations, and work with raw byte arrays.
Installation
npm install ipaddr.js copy
Node.js version support
ipaddr.js 2.x — Node.js 10+
ipaddr.js 1.x — Node.js < 10
Quick start
const ipaddr = require ( 'ipaddr.js'
);
ipaddr. isValid ( '192.168.1.1' ); // => true
ipaddr. isValid ( '2001:db8::1' ); // => true
ipaddr. isValid ( 'not an address' ); // => false
const addr = ipaddr. parse ( '2001:db8::1' );
addr. kind (); // => 'ipv6'
addr. toString (); // => '2001:db8::1'
const [network, prefix] = ipaddr. parseCIDR ( '10.0.0.0/8' );
network. toString (); // => '10.0.0.0'
prefix; // => 8
copy
Table of contents
Global API
IPv4 API
Static: isValid , isValidCIDR , isValidFourPartDecimal , isValidCIDRFourPartDecimal , isIPv4 , parse , parseCIDR , broadcastAddressFromCIDR , networkAddressFromCIDR , subnetMaskFromPrefixLength
Instance: octets , kind() , match() , range() , prefixLengthFromSubnetMask() , subnetMatch() , toByteArray() , toIPv4MappedAddress() , toNormalizedString() , toString()
IPv6 API
Static: isValid , isValidCIDR , isIPv6 , parse , parseCIDR , broadcastAddressFromCIDR , networkAddressFromCIDR , subnetMaskFromPrefixLength
Instance: parts , zoneId , kind() , isIPv4MappedAddress() , , , , , , , , , ,
Global API const ipaddr = require ( 'ipaddr.js' ); copy
ipaddr.isValid(string)Returns true if the string is a valid IPv4 or IPv6 address; false otherwise. Never throws.
ipaddr. isValid ( '192.168.1.1' ); // => true
ipaddr. isValid ( '2001:db8::1' ); // => true
ipaddr. isValid ( '999.0.0.1' ); // => false
ipaddr. isValid ( 'hello' ); // => false copy
ipaddr.isValidCIDR(string)Returns true if the string is a valid IPv4 or IPv6 address in CIDR notation; false otherwise. Never throws.
ipaddr. isValidCIDR ( '192.168.0.0/24' ); // => true
ipaddr. isValidCIDR ( '2001:db8::/32' ); // => true
ipaddr. isValidCIDR ( '192.168.0.1/33' ); // => false copy
ipaddr.parse(string)Parses the string and returns an IPv4 or IPv6 object. Throws if the string is not a valid address.
const v4 = ipaddr. parse ( '192.168.1.1' );
v4. kind (); // => 'ipv4'
v4. toString (); // => '192.168.1.1'
const v6 = ipaddr. parse ( '2001:db8::1' );
v6. kind (); // => 'ipv6'
v6. toString (); // => '2001:db8::1' copy
ipaddr.parseCIDR(string)Parses an IP address with a CIDR prefix length and returns a two-element array [address, prefixLength]. Throws if the input is not valid CIDR notation.
const [addr, prefix] = ipaddr. parseCIDR ( '192.168.1.0/24' );
addr. toString (); // => '192.168.1.0'
prefix; // => 24 copy The returned array can be passed directly to addr.match():
const addr = ipaddr. parse ( '192.168.1.42' );
addr. match (ipaddr. parseCIDR ( '192.168.1.0/24' )); // => true copy
ipaddr.process(string)Like ipaddr.parse(), but automatically converts IPv4-mapped IPv6 addresses (e.g. ::ffff:192.168.1.1) to their IPv4 equivalents. All other addresses are returned as-is.
This is useful when accepting connections on a dual-stack IPv6 socket, where IPv4 client addresses appear as IPv4-mapped IPv6 addresses.
ipaddr. process ( '::ffff:192.168.1.1' ). toString (); // => '192.168.1.1'
ipaddr. process ( '::ffff:192.168.1.1' ). kind (); // => 'ipv4'
ipaddr. process ( '2001:db8::1' ). kind (); // => 'ipv6'
ipaddr. process ( '192.168.1.1' ). kind (); // => 'ipv4' copy
ipaddr.subnetMatch(address, rangeList[, defaultName])Matches address against a map of named CIDR ranges and returns the name of the first matching range. Returns defaultName (default: 'unicast') if no range matches.
Each rangeList value is either a single [address, prefixLength] pair or an array of such pairs. The list may mix IPv4 and IPv6 entries; entries of the wrong address family are safely skipped.
const rangeList = {
private: [
[ipaddr. parse ( '10.0.0.0' ), 8 ],
[ipaddr. parse ( '172.16.0.0' ), 12 ],
[ipaddr. parse ( '192.168.0.0' ), 16 ],
],
loopback: [ ipaddr. parse ( '127.0.0.0' ), 8 ],
};
ipaddr. subnetMatch (ipaddr. parse ( '192.168.1.1' ), rangeList); // => 'private'
ipaddr. subnetMatch (ipaddr. parse ( '127.0.0.1' ), rangeList); // => 'loopback'
ipaddr. subnetMatch (ipaddr. parse ( '8.8.8.8' ), rangeList, 'public' ); // => 'public'
ipaddr. subnetMatch (ipaddr. parse ( '8.8.8.8' ), rangeList); // => 'unicast' copy
ipaddr.fromByteArray(bytes)Constructs an IPv4 or IPv6 address from a byte array in network byte order (MSB first). Accepts 4 bytes for IPv4, or 16 bytes for IPv6. Throws if the array length is not 4 or 16.
ipaddr. fromByteArray ([ 127 , 0 , 0 , 1 ]). toString (); // => '127.0.0.1'
ipaddr. fromByteArray ([
0x20 , 0x01 , 0x0d , 0xb8 ,
0x00 , 0x00 , 0x00 , 0x00 ,
0x00 , 0x00 , 0x00 , 0x00 ,
0x00 , 0x00 , 0x00 , 0x01 ,
]). toString (); // => '2001:db8::1' copy
IPv4 API
Static methods
ipaddr.IPv4.isValid(string)Returns true if the string is a valid IPv4 address; false otherwise. Never throws.
Accepts the same extended formats as ipaddr.IPv4.parse() (hex, octal, fewer-than-four parts). For strict four-part decimal validation, use isValidFourPartDecimal().
ipaddr.IPv4. isValid ( '192.168.1.1' ); // => true
ipaddr.IPv4. isValid ( '0xc0.168.1.1' ); // => true (hex octet)
ipaddr.IPv4. isValid ( '999.0.0.1' ); // => false copy
ipaddr.IPv4.isValidCIDR(string)Returns true if the string is a valid IPv4 CIDR address; false otherwise. Never throws.
ipaddr.IPv4. isValidCIDR ( '192.168.0.0/24' ); // => true
ipaddr.IPv4. isValidCIDR ( '192.168.0.0/33' ); // => false copy
ipaddr.IPv4.isValidFourPartDecimal(string)Like isValid(), but only accepts the standard four-part dotted-decimal format. Rejects hex, octal, and other non-standard notations accepted by inet_aton.
ipaddr.IPv4. isValidFourPartDecimal ( '192.168.1.1' ); // => true
ipaddr.IPv4. isValidFourPartDecimal ( '0xc0.168.1.1' ); // => false copy
ipaddr.IPv4.isValidCIDRFourPartDecimal(string)Like isValidCIDR(), but only accepts the standard four-part dotted-decimal format for the address portion.
ipaddr.IPv4. isValidCIDRFourPartDecimal ( '192.168.0.0/24' ); // => true
ipaddr.IPv4. isValidCIDRFourPartDecimal ( '0xc0.168.0.0/24' ); // => false copy
ipaddr.IPv4.isIPv4(string)Returns true if the string matches the IPv4 address pattern. This is a lightweight regex check — it does not validate that all octets are in range (0–255). Prefer isValid() for authoritative validation.
ipaddr.IPv4. isIPv4 ( '192.168.1.1' ); // => true
ipaddr.IPv4. isIPv4 ( '2001:db8::1' ); // => false copy
ipaddr.IPv4.parse(string)Parses the string and returns an IPv4 object. Throws if the string is not a valid IPv4 address.
In addition to standard dotted-decimal, the parser accepts formats recognised by the POSIX inet_aton function: hex octets (0xc0.0xa8.0x01.0x01), octal octets (0300.0250.01.01), three-part (192.168.257), two-part (192.11010049), and single-value (3232235777) notation.
ipaddr.IPv4. parse ( '192.168.1.1' ). toString (); // => '192.168.1.1'
ipaddr.IPv4. parse ( '0xc0.168.1.1' ). toString (); // => '192.168.1.1' copy
ipaddr.IPv4.parseCIDR(string)Parses an IPv4 CIDR address and returns [IPv4, prefixLength]. Throws if the input is invalid.
const [addr, prefix] = ipaddr.IPv4. parseCIDR ( '192.168.1.0/24' );
addr. toString (); // => '192.168.1.0'
prefix; // => 24 copy
ipaddr.IPv4.broadcastAddressFromCIDR(string)Returns the broadcast address for the given IPv4 CIDR block.
ipaddr.IPv4. broadcastAddressFromCIDR ( '192.168.1.0/24' ). toString (); // => '192.168.1.255'
ipaddr.IPv4. broadcastAddressFromCIDR ( '10.0.0.1/8' ). toString (); // => '10.255.255.255' copy
ipaddr.IPv4.networkAddressFromCIDR(string)Returns the network address for the given IPv4 CIDR block.
ipaddr.IPv4. networkAddressFromCIDR ( '192.168.1.42/24' ). toString (); // => '192.168.1.0'
ipaddr.IPv4. networkAddressFromCIDR ( '10.1.2.3/8' ). toString (); // => '10.0.0.0' copy
ipaddr.IPv4.subnetMaskFromPrefixLength(prefix)Returns the IPv4 subnet mask corresponding to the given CIDR prefix length.
ipaddr.IPv4. subnetMaskFromPrefixLength ( 24 ). toString (); // => '255.255.255.0'
ipaddr.IPv4. subnetMaskFromPrefixLength ( 16 ). toString (); // => '255.255.0.0' copy
Instance properties and methods
addr.octetsThe four octets of the address as an array of numbers.
ipaddr. parse ( '192.168.1.1' ).octets; // => [192, 168, 1, 1] copy
addr.kind()ipaddr. parse ( '192.168.1.1' ). kind (); // => 'ipv4' copy
addr.match(other, cidrBits) / addr.match([address, cidrBits])Returns true if the address falls within the given CIDR range.
const addr = ipaddr. parse ( '192.168.1.42' );
addr. match (ipaddr. parse ( '192.168.1.0' ), 24 ); // => true
addr. match (ipaddr. parse ( '10.0.0.0' ), 8 ); // => false
// Accepts the tuple returned by parseCIDR:
addr. match (ipaddr. parseCIDR ( '192.168.1.0/24' )); // => true copy
addr.range()Returns the name of the built-in range the address belongs to, or 'unicast' if it does not match any special range. Recognised names: 'unspecified', 'broadcast', 'multicast', 'linkLocal', 'loopback', 'carrierGradeNat', 'private', 'reserved', 'as112', 'amt'.
See the source for the full CIDR list associated with each name.
ipaddr. parse ( '127.0.0.1' ). range (); // => 'loopback'
ipaddr. parse ( '192.168.1.1' ). range (); // => 'private'
ipaddr. parse ( '169.254.1.1' ). range (); // => 'linkLocal'
ipaddr. parse ( '8.8.8.8' ). range (); // => 'unicast' copy
addr.prefixLengthFromSubnetMask()Returns the CIDR prefix length if this address is a valid contiguous subnet mask, or null otherwise.
ipaddr. parse ( '255.255.255.0' ). prefixLengthFromSubnetMask (); // => 24
ipaddr. parse ( '255.255.255.240' ). prefixLengthFromSubnetMask (); // => 28
ipaddr. parse ( '255.192.168.0' ). prefixLengthFromSubnetMask (); // => null copy
addr.subnetMatch(rangeList[, defaultName])Instance-method shorthand for ipaddr.subnetMatch(addr, rangeList, defaultName).
const addr = ipaddr. parse ( '192.168.1.1' );
addr. subnetMatch ({ private: [ipaddr. parse ( '192.168.0.0' ), 16 ] }); // => 'private' copy
addr.toByteArray()Returns the address as an array of four bytes in network byte order.
ipaddr. parse ( '192.168.1.1' ). toByteArray (); // => [192, 168, 1, 1]
ipaddr. parse ( '127.0.0.1' ). toByteArray (); // => [127, 0, 0, 1] copy
addr.toIPv4MappedAddress()Returns the IPv4-mapped IPv6 representation of this address (::ffff:x.x.x.x).
ipaddr. parse ( '192.168.1.1' ). toIPv4MappedAddress (). toString (); // => '::ffff:c0a8:101' copy
addr.toNormalizedString()Returns the address in standard four-part dotted-decimal notation. For IPv4, this is the same as toString().
ipaddr. parse ( '192.168.1.1' ). toNormalizedString (); // => '192.168.1.1' copy
addr.toString()Returns the address as a dotted-decimal string.
ipaddr. parse ( '192.168.001.001' ). toString (); // => '192.168.1.1' copy
IPv6 API
Static methods
ipaddr.IPv6.isValid(string)Returns true if the string is a valid IPv6 address; false otherwise. Never throws. Accepts addresses with a zone ID (e.g. fe80::1%eth0).
ipaddr.IPv6. isValid ( '2001:db8::1' ); // => true
ipaddr.IPv6. isValid ( '::1' ); // => true
ipaddr.IPv6. isValid ( 'fe80::1%eth0' ); // => true
ipaddr.IPv6. isValid ( '192.168.1.1' ); // => false copy
ipaddr.IPv6.isValidCIDR(string)Returns true if the string is a valid IPv6 CIDR address; false otherwise. Never throws.
ipaddr.IPv6. isValidCIDR ( '2001:db8::/32' ); // => true
ipaddr.IPv6. isValidCIDR ( '2001:db8::/129' ); // => false copy
ipaddr.IPv6.isIPv6(string)Returns true if the string matches the IPv6 address pattern. This is a lightweight regex check and does not fully validate all groups. Prefer isValid() for authoritative validation.
ipaddr.IPv6. isIPv6 ( '2001:db8::1' ); // => true
ipaddr.IPv6. isIPv6 ( '192.168.1.1' ); // => false copy
ipaddr.IPv6.parse(string)Parses the string and returns an IPv6 object. Throws if the string is not a valid IPv6 address.
ipaddr.IPv6. parse ( '2001:db8::1' ). toString (); // => '2001:db8::1'
ipaddr.IPv6. parse ( '::ffff:192.168.1.1' ). toString (); // => '::ffff:c0a8:101' copy
ipaddr.IPv6.parseCIDR(string)Parses an IPv6 CIDR address and returns [IPv6, prefixLength]. Throws if the input is invalid.
const [addr, prefix] = ipaddr.IPv6. parseCIDR ( '2001:db8::/32' );
addr. toString (); // => '2001:db8::'
prefix; // => 32 copy
ipaddr.IPv6.broadcastAddressFromCIDR(string)Returns the last address in the given IPv6 CIDR block (the IPv6 equivalent of the broadcast address).
ipaddr.IPv6. broadcastAddressFromCIDR ( '2001:db8::/120' ). toString (); // => '2001:db8::ff' copy
ipaddr.IPv6.networkAddressFromCIDR(string)Returns the network address for the given IPv6 CIDR block.
ipaddr.IPv6. networkAddressFromCIDR ( '2001:db8::42/32' ). toString (); // => '2001:db8::' copy
ipaddr.IPv6.subnetMaskFromPrefixLength(prefix)Returns the IPv6 subnet mask corresponding to the given CIDR prefix length.
ipaddr.IPv6. subnetMaskFromPrefixLength ( 64 ). toString (); // => 'ffff:ffff:ffff:ffff::'
ipaddr.IPv6. subnetMaskFromPrefixLength ( 48 ). toString (); // => 'ffff:ffff:ffff::' copy
Instance properties and methods
addr.partsThe eight 16-bit groups of the address as an array of numbers.
ipaddr. parse ( '2001:db8:10::1234:dead' ).parts;
// => [0x2001, 0x0db8, 0x0010, 0, 0, 0, 0x1234, 0xdead] copy
addr.zoneIdThe zone ID string for link-local addresses, or undefined if absent.
ipaddr. parse ( 'fe80::1%eth0' ).zoneId; // => 'eth0'
ipaddr. parse ( '2001:db8::1' ).zoneId; // => undefined copy
addr.kind()ipaddr. parse ( '2001:db8::1' ). kind (); // => 'ipv6' copy
addr.isIPv4MappedAddress()Returns true if this is an IPv4-mapped IPv6 address (i.e. in the ::ffff:0:0/96 range).
ipaddr. parse ( '::ffff:192.168.1.1' ). isIPv4MappedAddress (); // => true
ipaddr. parse ( '2001:db8::1' ). isIPv4MappedAddress (); // => false copy
addr.match(other, cidrBits) / addr.match([address, cidrBits])Returns true if the address falls within the given CIDR range.
const addr = ipaddr. parse ( '2001:db8:1234::1' );
addr. match (ipaddr. parse ( '2001:db8::' ), 32 ); // => true
addr. match (ipaddr. parseCIDR ( '2001:db8::/32' )); // => true
addr. match (ipaddr. parseCIDR ( '2001:db9::/32' )); // => false copy
addr.range()Returns the name of the built-in range the address belongs to, or 'unicast' if it does not match any. Recognised names include: 'unspecified', 'linkLocal', 'multicast', 'loopback', 'uniqueLocal', 'ipv4Mapped', 'reserved', and others.
See the source for the full list.
ipaddr. parse ( '::1' ). range (); // => 'loopback'
ipaddr. parse ( 'fe80::1' ). range (); // => 'linkLocal'
ipaddr. parse ( 'fc00::1' ). range (); // => 'uniqueLocal'
ipaddr. parse ( '2001:db8::1' ). range (); // => 'reserved'
ipaddr. parse ( '2607:f8b0::1' ). range (); // => 'unicast' copy
addr.prefixLengthFromSubnetMask()Returns the CIDR prefix length if this address is a valid contiguous subnet mask, or null otherwise.
ipaddr. parse ( 'ffff:ffff:ffff:ffff::' ). prefixLengthFromSubnetMask (); // => 64
ipaddr. parse ( 'ffff:ffff::' ). prefixLengthFromSubnetMask (); // => 32 copy
addr.subnetMatch(rangeList[, defaultName])Instance-method shorthand for ipaddr.subnetMatch(addr, rangeList, defaultName).
const addr = ipaddr. parse ( '2001:db8::1' );
const ranges = { documentation: [ipaddr. parse ( '2001:db8::' ), 32 ] };
addr. subnetMatch (ranges); // => 'documentation' copy
addr.toByteArray()Returns the address as an array of 16 bytes in network byte order.
ipaddr. parse ( '2001:db8::1' ). toByteArray ();
// => [0x20, 0x01, 0x0d, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1] copy
addr.toFixedLengthString()Returns the address with all eight groups fully expanded to four hex digits, separated by colons. No :: abbreviation is used.
ipaddr. parse ( '2001:db8::1' ). toFixedLengthString ();
// => '2001:0db8:0000:0000:0000:0000:0000:0001' copy
addr.toIPv4Address()Converts an IPv4-mapped IPv6 address to its IPv4 equivalent. Throws if the address is not IPv4-mapped.
ipaddr. parse ( '::ffff:192.168.1.1' ). toIPv4Address (). toString (); // => '192.168.1.1' copy
addr.toNormalizedString()Returns the address with all eight 16-bit groups written out in lowercase hex, separated by colons, without :: compression.
ipaddr. parse ( '2001:db8::1' ). toNormalizedString (); // => '2001:db8:0:0:0:0:0:1' copy
addr.toRFC5952String()Returns the address in the canonical format defined by RFC 5952 : lowercase hex, leading zeros omitted, and the longest run of consecutive all-zero groups replaced by ::.
ipaddr. parse ( '2001:0db8:0000:0000:0000:0000:0000:0001' ). toRFC5952String ();
// => '2001:db8::1' copy
addr.toString()Returns the compact string representation of the address, identical to toRFC5952String().
ipaddr. parse ( '2001:0db8::0001' ). toString (); // => '2001:db8::1' copy