🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →

ip-address

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

ip-address

A library for parsing IPv4 and IPv6 IP addresses in node and the browser.

Source

npm

Version: 10.2.2

Version published: 20 hours ago

Weekly downloads: 82M

Maintainers: 1

Weekly downloads

Created: 5 years ago

Source

ip-address

ip-address is a library for validating and manipulating IPv4 and IPv6 addresses in JavaScript and TypeScript.

Install

npm install ip-address

Examples

import { Address4, Address6 } from 'ip-address';

// Validation
Address4.isValid('192.168.1.1');           // true
Address6.isValid('2001:db8::1');           // true
Address6.isValid('not an address');        // false

// Parsing (throws AddressError on invalid input)
const v4 = new Address4('192.168.1.1/24');
const v6 = new Address6('2001:db8::1/64');

// Subnet membership
const host = new Address4('192.168.1.42');
const network = new Address4('192.168.1.0/24');
host.isInSubnet(network);                  // true

// Subnet range
network.startAddress().correctForm();      // '192.168.1.0'
network.endAddress().correctForm();        // '192.168.1.255'

// Strict network-address check (host bits must be zero).
// isValid() accepts CIDRs with host bits set — '192.168.1.5/24' is a valid
// host-with-subnet, but it isn't a network address.
const cidr = new Address4('192.168.1.5/24');
Address4.isValid('192.168.1.5/24');                                // true
cidr.correctForm() === cidr.startAddress().correctForm();          // false

// Address properties
const link = new Address6('fe80::1');
link.isLinkLocal();                        // true
link.isMulticast();                        // false
link.isLoopback();                         // false

new Address4('192.168.1.1').isPrivate();   // true (RFC 1918)
new Address6('fc00::1').isULA();           // true (RFC 4193)

// Numeric and byte representations
v4.bigInt();                               // 3232235777n
v4.toArray();                              // [192, 168, 1, 1]
v6.canonicalForm();                        // '2001:0db8:0000:0000:0000:0000:0000:0001'

// Embedded IPv4 + Teredo
const teredo = new Address6('2001:0:ce49:7601:e866:efff:62c3:fffe');
teredo.inspectTeredo().client4;            // '157.60.0.1'

// Parse host + port from a URL
Address6.fromURL('http://[2001:db8::1]:8080/').port;  // 8080

Features

Written in TypeScript with full type definitions; usable from CommonJS and ESM
Zero runtime dependencies
Parses all standard IPv4 and IPv6 notations, including subnets and zones
Parses IPv6 hosts (and ports) from URLs via Address6.fromURL(url)
Subnet membership checks (isInSubnet) and range queries (startAddress / endAddress)
Special-property checks: private (RFC 1918) / ULA (RFC 4193), loopback, link-local, multicast, broadcast, unspecified, CGNAT, documentation, Teredo, 6to4, v4-in-v6
Decodes Teredo and 6to4 tunneling information
Conversions: canonical/correct form, hex, binary, decimal, byte arrays, BigInt, in-addr.arpa / ip6.arpa
Runs in Node.js and the browser
Thousands of test cases

Terminology

A few terms used throughout the API can be confusing if you haven't worked deeply with IPv6 before:

Correct form — the shortest valid representation, per RFC 5952: leading zeros stripped, the longest run of zero groups collapsed to ::, and hex digits lowercased (e.g. 2001:db8::1). This is what most software displays.
Canonical form — the fully expanded representation: all 8 groups, each padded to 4 hex digits, no :: collapsing (e.g. 2001:0db8:0000:0000:0000:0000:0000:0001). Useful for sorting and byte-exact comparison.
Subnet — the network portion of an address expressed as a CIDR prefix length (e.g. /24 for IPv4, /64 for IPv6). startAddress() / endAddress() return the bounds of the subnet's range.
Zone — the IPv6 scope identifier appended after %, used to disambiguate link-local addresses across interfaces (e.g. fe80::1%eth0).
v4-in-v6 — mixed notation that embeds an IPv4 address as the last 32 bits of an IPv6 address, e.g. ::ffff:192.168.0.1. Used for IPv4-mapped IPv6 addresses.
Teredo — a tunneling protocol that encodes an IPv4 endpoint, port, and flags inside a 2001::/32 IPv6 address. inspectTeredo() decodes those fields.
6to4 — a tunneling protocol that embeds an IPv4 address as the second 16 bits of a 2002::/16 IPv6 address. inspect6to4() decodes the embedded v4 address.

API

AddressError

Constructor

new AddressError(message: string, parseMessage?: string): AddressError

Properties

parseMessage: string — src

Address4

Represents an IPv4 address

Constructor

new Address4(address: string): Address4

Static methods

static isValid(address: string): boolean — Returns true if the given string is a valid IPv4 address (with optional CIDR subnet), false otherwise. Host bits in the subnet portion are allowed (e.g. 192.168.1.5/24 is valid); for strict network-address validation compare correctForm() to startAddress().correctForm(), or use networkForm(). src
static fromAddressAndMask(address: string, mask: string): Address4 — Construct an Address4 from an address and a dotted-decimal subnet mask given as separate strings (e.g. as returned by Node's os.networkInterfaces()). Throws AddressError if the mask is non-contiguous (e.g. 255.0.255.0). src
static fromAddressAndWildcardMask(address: string, wildcardMask: string): Address4 — Construct an Address4 from an address and a Cisco-style wildcard mask given as separate strings (e.g. 0.0.0.255 for a /24). The wildcard mask is the bitwise inverse of the subnet mask. Throws AddressError if the mask is non-contiguous (e.g. 0.255.0.255). src
static fromWildcard(input: string): Address4 — Construct an Address4 from a wildcard pattern with trailing * octets. The number of trailing wildcards determines the prefix length: each * represents 8 bits. Only trailing whole-octet wildcards are supported. Partial-octet wildcards (e.g. 192.168.0.1*) and interior wildcards (e.g. 192.*.0.1) throw AddressError. src
static fromHex(hex: string): Address4 — Converts a hex string to an IPv4 address object. Accepts 8 hex digits with optional : separators (e.g. '7f000001' or '7f:00:00:01'). Throws AddressError for any other length or for non-hex characters. src
static fromInteger(integer: number): Address4 — Converts an integer into a IPv4 address object. The integer must be a non-negative safe integer in the range [0, 2**32 - 1]; otherwise AddressError is thrown. src
static fromArpa(arpaFormAddress: string): Address4 — Return an address from in-addr.arpa form src
static fromBigInt(bigInt: bigint): Address4 — Converts a BigInt to a v4 address object. The value must be in the range [0, 2**32 - 1]; otherwise AddressError is thrown. src
static fromByteArray(bytes: number[]): Address4 — Convert a byte array to an Address4 object. To convert from a Node.js Buffer, spread it: Address4.fromByteArray([...buf]). src
static fromUnsignedByteArray(bytes: number[]): Address4 — Convert an unsigned byte array to an Address4 object src

Instance methods

parse(address: string): string[] — Parses an IPv4 address string into its four octet groups and stores the result on this.parsedAddress. Called automatically by the constructor; you typically don't need to call it directly. Throws AddressError if the input is not a valid IPv4 address. src
correctForm(): string — Returns the address in correct form: octets joined with . and any leading zeros stripped (e.g. 192.168.1.1). For IPv4 this matches the canonical dotted-decimal representation. src
toHex(): string — Converts an IPv4 address object to a hex string src
toArray(): number[] — Converts an IPv4 address object to an array of bytes. To get a Node.js Buffer, wrap the result: Buffer.from(address.toArray()). src
toGroup6(): string — Converts an IPv4 address object to an IPv6 address group src
bigInt(): bigint — Returns the address as a bigint src
startAddress(): Address4 — The first address in the range given by this address' subnet. Often referred to as the Network Address. src
startAddressExclusive(): Address4 — The first host address in the range given by this address's subnet ie the first address after the Network Address src
endAddress(): Address4 — The last address in the range given by this address' subnet Often referred to as the Broadcast src
endAddressExclusive(): Address4 — The last host address in the range given by this address's subnet ie the last address prior to the Broadcast Address src
subnetMaskAddress(): Address4 — The dotted-decimal form of the subnet mask, e.g. 255.255.240.0 for a /20. Returns an Address4; call .correctForm() for the string. src
wildcardMask(): Address4 — The Cisco-style wildcard mask, e.g. 0.0.0.255 for a /24. This is the bitwise inverse of subnetMaskAddress(). Returns an Address4; call .correctForm() for the string. src
networkForm(): string — The network address in CIDR string form, e.g. 192.168.1.0/24 for 192.168.1.5/24. For an address with no explicit subnet the prefix is /32, e.g. networkForm() on 192.168.1.5 returns 192.168.1.5/32. src
mask(mask?: number): string — Returns the first n bits of the address, defaulting to the subnet mask src
getBitsBase2(start: number, end: number): string — Returns the bits in the given range as a base-2 string src
reverseForm(options?: ReverseFormOptions): string — Return the reversed ip6.arpa form of the address src
isMulticast(): boolean — Returns true if the given address is a multicast address src
isPrivate(): boolean — Returns true if the address is in one of the RFC 1918 private address ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16). src
isLoopback(): boolean — Returns true if the address is in the loopback range 127.0.0.0/8 (RFC 1122). src
isLinkLocal(): boolean — Returns true if the address is in the link-local range 169.254.0.0/16 (RFC 3927). src
isUnspecified(): boolean — Returns true if the address is the unspecified address 0.0.0.0. src
isBroadcast(): boolean — Returns true if the address is the limited broadcast address 255.255.255.255 (RFC 919). src
isCGNAT(): boolean — Returns true if the address is in the carrier-grade NAT range 100.64.0.0/10 (RFC 6598). src
binaryZeroPad(): string — Returns a zero-padded base-2 string representation of the address src
groupForV6(): string — Groups an IPv4 address for inclusion at the end of an IPv6 address src

Properties

address: string — src
addressMinusSuffix: string — src
groups: number — src
parsedAddress: string[] — src
parsedSubnet: string — src
subnet: string — src
subnetMask: number — src
v4: boolean — src
isCorrect: (this: Address4 | Address6) => boolean — Returns true if the address is correct, false otherwise src
isInSubnet: (this: Address4 | Address6, address: Address4 | Address6) => boolean — Returns true if the given address is in the subnet of the current address src
isHostInSubnet: (this: Address4 | Address6, address: Address4 | Address6) => boolean — Returns true if this address's host bits fall inside the given subnet, ignoring this address's own subnet mask. See common.isHostInSubnet. src

Address6

Represents an IPv6 address

Constructor

new Address6(address: string, optionalGroups?: number): Address6

Static methods

static isValid(address: string): boolean — Returns true if the given string is a valid IPv6 address (with optional CIDR subnet and zone identifier), false otherwise. Host bits in the subnet portion are allowed (e.g. 2001:db8::1/32 is valid); for strict network-address validation compare correctForm() to startAddress().correctForm(), or use networkForm(). src
static fromBigInt(bigInt: bigint): Address6 — Convert a BigInt to a v6 address object. The value must be in the range [0, 2**128 - 1]; otherwise AddressError is thrown. src
static fromURL(url: string): { error: string; address: null; port: null } | { error?: undefined; address: Address6; port: number | null } — Parse a URL (with optional bracketed host and port) into an address and port. Returns either { address, port } on success or { error, address: null, port: null } if the URL could not be parsed. Ports are returned as numbers (or null if absent or out of range). src
static fromAddressAndMask(address: string, mask: string): Address6 — Construct an Address6 from an address and a hex subnet mask given as separate strings (e.g. as returned by Node's os.networkInterfaces()). Throws AddressError if the mask is non-contiguous (e.g. ffff::ffff). src
static fromAddressAndWildcardMask(address: string, wildcardMask: string): Address6 — Construct an Address6 from an address and a Cisco-style wildcard mask given as separate strings (e.g. ::ffff:ffff:ffff:ffff for a /64). The wildcard mask is the bitwise inverse of the subnet mask. Throws AddressError if the mask is non-contiguous. src
static fromWildcard(input: string): Address6 — Construct an Address6 from a wildcard pattern with trailing * groups. The number of trailing wildcards determines the prefix length: each * represents 16 bits. :: is expanded to zero groups (not wildcards) before evaluating trailing wildcards. Only trailing whole-group wildcards are supported. Partial-group wildcards (e.g. 2001:db8::0*) and interior wildcards (e.g. *::1) throw AddressError. src
static fromAddress4(address: string): Address6 — Create an IPv6-mapped address given an IPv4 address src
static fromArpa(arpaFormAddress: string): Address6 — Return an address from ip6.arpa form src
static fromAddress4Nat64(address: string, prefix: string): Address6 — Embed an IPv4 address into a NAT64 IPv6 address using the encoding defined by RFC 6052. The default prefix is the well-known prefix 64:ff9b::/96. The prefix length must be one of 32, 40, 48, 56, 64, or 96; for prefixes shorter than /64 the IPv4 octets are split around the reserved bits 64–71. src
static fromByteArray(bytes: any[]): Address6 — Convert a byte array to an Address6 object. To convert from a Node.js Buffer, spread it: Address6.fromByteArray([...buf]). src
static fromUnsignedByteArray(bytes: any[]): Address6 — Convert an unsigned byte array to an Address6 object. To convert from a Node.js Buffer, spread it: Address6.fromUnsignedByteArray([...buf]). src

Instance methods

microsoftTranscription(): string — Return the Microsoft UNC transcription of the address src
mask(mask?: number): string — Return the first n bits of the address, defaulting to the subnet mask src
possibleSubnets(subnetSize?: number): string — Return the number of possible subnets of a given size in the address src
startAddress(): Address6 — The first address in the range given by this address' subnet Often referred to as the Network Address. src
startAddressExclusive(): Address6 — The first host address in the range given by this address's subnet ie the first address after the Network Address src
endAddress(): Address6 — The last address in the range given by this address' subnet Often referred to as the Broadcast src
endAddressExclusive(): Address6 — The last host address in the range given by this address's subnet ie the last address prior to the Broadcast Address src
subnetMaskAddress(): Address6 — The hex form of the subnet mask, e.g. ffff:ffff:ffff:ffff:: for a /64. Returns an Address6; call .correctForm() for the string. src
wildcardMask(): Address6 — The Cisco-style wildcard mask, e.g. ::ffff:ffff:ffff:ffff for a /64. This is the bitwise inverse of subnetMaskAddress(). Returns an Address6; call .correctForm() for the string. src
networkForm(): string — The network address in CIDR string form, e.g. 2001:db8::/32 for 2001:db8::1/32. For an address with no explicit subnet the prefix is /128, e.g. networkForm() on 2001:db8::1 returns 2001:db8::1/128. src
getScope(): string — Return the scope of the address. The 4-bit scope field (RFC 4291 §2.7) is only defined for multicast addresses; for unicast addresses the scope is derived from the address type per RFC 4007 §6. src
getType(): string — Return the type of the address src
getBits(start: number, end: number): bigint — Return the bits in the given range as a BigInt src
getBitsBase2(start: number, end: number): string — Return the bits in the given range as a base-2 string src
getBitsBase16(start: number, end: number): string — Return the bits in the given range as a base-16 string src
getBitsPastSubnet(): string — Return the bits that are set past the subnet mask length src
reverseForm(options?: ReverseFormOptions): string — Return the reversed ip6.arpa form of the address src
correctForm(): string — Returns the address in correct form, per RFC 5952: leading zeros stripped, the longest run of zero groups collapsed to ::, and hex digits lowercased (e.g. 2001:db8::1). This is the recommended form for display. src
binaryZeroPad(): string — Return a zero-padded base-2 string representation of the address src
parse4in6(address: string): string — Parses a v4-in-v6 string (e.g. ::ffff:192.168.0.1) by extracting the trailing IPv4 address into this.address4 / this.parsedAddress4 and returning the address with the v4 portion converted to two v6 groups. Used internally by parse(). src
parse(address: string): string[] — Parses an IPv6 address string into its 8 hexadecimal groups (expanding any :: elision and any trailing v4-in-v6 portion) and stores the result on this.parsedAddress. Called automatically by the constructor; you typically don't need to call it directly. Throws AddressError if the input is malformed. src
canonicalForm(): string — Returns the canonical (fully expanded) form of the address: all 8 groups, each padded to 4 hex digits, with no :: collapsing (e.g. 2001:0db8:0000:0000:0000:0000:0000:0001). Useful for sorting and byte-exact comparison. src
decimal(): string — Return the decimal form of the address src
bigInt(): bigint — Return the address as a BigInt src
to4(): Address4 — Return the last two groups of this address as an IPv4 address string. If this address carries a CIDR prefix that covers the trailing 32 bits (i.e. subnetMask >= 96), the resulting Address4 inherits the corresponding v4 prefix (subnetMask - 96); otherwise it defaults to /32. src
to4in6(): string — Return the v4-in-v6 form of the address src
inspectTeredo(): TeredoProperties — Decodes the Teredo tunneling fields embedded in this address. Returns the Teredo prefix, server IPv4, client IPv4, raw flag bits, cone-NAT flag, UDP port, and Microsoft-format flag breakdown (reserved, universal/local, group/individual, nonce). Only meaningful for addresses in 2001::/32. src
inspect6to4(): SixToFourProperties — Decodes the 6to4 tunneling fields embedded in this address. Returns the 6to4 prefix and the embedded IPv4 gateway address. Only meaningful for addresses in 2002::/16. src
to6to4(): Address6 | null — Return a v6 6to4 address from a v6 v4inv6 address src
toAddress4Nat64(prefix: string): Address4 | null — Extract the embedded IPv4 address from a NAT64 IPv6 address using the encoding defined by RFC 6052. The default prefix is the well-known prefix 64:ff9b::/96. Returns null if this address is not contained within the given prefix. src
toByteArray(): number[] — Return a byte array. To get a Node.js Buffer, wrap the result: Buffer.from(address.toByteArray()). src
toUnsignedByteArray(): number[] — Return an unsigned byte array. To get a Node.js Buffer, wrap the result: Buffer.from(address.toUnsignedByteArray()). src
isCanonical(): boolean — Returns true if the address is in the canonical form, false otherwise src
isLinkLocal(): boolean — Returns true if the address is a link local address, false otherwise src
isMulticast(): boolean — Returns true if the address is a multicast address, false otherwise src
is4(): boolean — Returns true if the address was written in v4-in-v6 dotted-quad notation (e.g. ::ffff:127.0.0.1), false otherwise. This is a notation-level flag and does not reflect whether the address bits lie in the IPv4-mapped (::ffff:0:0/96) subnet — for that, see isMapped4. src
isMapped4(): boolean — Returns true if the address is an IPv4-mapped IPv6 address in ::ffff:0:0/96 (RFC 4291 §2.5.5.2), false otherwise. Unlike is4, this checks the underlying address bits rather than the textual notation, so ::ffff:127.0.0.1 and ::ffff:7f00:1 both return true. src
embeddedIPv4(): Address4 | null — If this address embeds a routable IPv4 address — i.e. it is IPv4-mapped (::ffff:0:0/96) or sits in the NAT64 well-known prefix (64:ff9b::/96, RFC 6052) — return that embedded address as an Address4; otherwise return null. The special-property checks (isLoopback, isLinkLocal, isMulticast, isUnspecified, isPrivate, isCGNAT, isBroadcast) call this first and delegate to the embedded Address4 when present, so a literal such as ::ffff:127.0.0.1 is classified by what it actually reaches (loopback) rather than by its IPv6 wrapper (which getType() reports as IPv4-mapped). This matters wherever the checks back a trust-boundary decision (e.g. an SSRF allow/deny filter): without normalization, ::ffff:10.0.0.1, ::ffff:169.254.169.254, 64:ff9b::7f00:1, etc. would all read as non-internal. src
isTeredo(): boolean — Returns true if the address is a Teredo address, false otherwise src
is6to4(): boolean — Returns true if the address is a 6to4 address, false otherwise src
isLoopback(): boolean — Returns true if the address is a loopback address, false otherwise src
isULA(): boolean — Returns true if the address is a Unique Local Address in fc00::/7 (RFC 4193). ULAs are the IPv6 equivalent of IPv4 RFC 1918 private addresses. src
isPrivate(): boolean — Returns true if the address is private, i.e. a Unique Local Address in fc00::/7 (RFC 4193) or an IPv4-mapped / NAT64 address whose embedded IPv4 address is in one of the RFC 1918 private ranges (e.g. ::ffff:10.0.0.1). This is the IPv6 counterpart to Address4.isPrivate; use it instead of isULA when you need to catch mapped RFC 1918 addresses as well as native ULAs. src
isCGNAT(): boolean — Returns true if the address is an IPv4-mapped / NAT64 address whose embedded IPv4 address is in the carrier-grade NAT range 100.64.0.0/10 (RFC 6598), false otherwise. There is no native IPv6 CGNAT range, so this only ever returns true for an embedded IPv4 address (e.g. ::ffff:100.64.0.1). src
isBroadcast(): boolean — Returns true if the address is an IPv4-mapped / NAT64 address whose embedded IPv4 address is the limited broadcast address 255.255.255.255 (RFC 919), false otherwise. There is no IPv6 broadcast, so this only ever returns true for an embedded IPv4 address (e.g. ::ffff:255.255.255.255). src
isUnspecified(): boolean — Returns true if the address is the unspecified address ::. src
isDocumentation(): boolean — Returns true if the address is in the documentation prefix 2001:db8::/32 (RFC 3849). src
href(optionalPort?: string | number): string — Returns the address as an HTTP URL with the host bracketed, e.g. http://[2001:db8::1]/. If optionalPort is provided it is appended, e.g. http://[2001:db8::1]:8080/. src
link(options?: { className?: string; prefix?: string; v4?: boolean }): string — Returns an HTML <a> element whose href encodes the address in a URL hash fragment (default prefix /#address=). Useful for linking between pages of an address-inspector UI. src
group(): string — Groups an address src
regularExpressionString(this: Address6, substringSearch: boolean): string — Generate a regular expression string that can be used to find or validate all variations of this address src
regularExpression(this: Address6, substringSearch: boolean): RegExp — Generate a regular expression that can be used to find or validate all variations of this address. src

Properties

address4: Address4 — src
address: string — src
addressMinusSuffix: string — src
elidedGroups: number — src
elisionBegin: number — src
elisionEnd: number — src
groups: number — src
parsedAddress4: string — src
parsedAddress: string[] — src
parsedSubnet: string — src
subnet: string — src
subnetMask: number — src
v4: boolean — src
zone: string — src
isInSubnet: (this: Address4 | Address6, address: Address4 | Address6) => boolean — Returns true if the given address is in the subnet of the current address src
isHostInSubnet: (this: Address4 | Address6, address: Address4 | Address6) => boolean — Returns true if this address's host bits fall inside the given subnet, ignoring this address's own subnet mask. See common.isHostInSubnet. src
isCorrect: (this: Address4 | Address6) => boolean — Returns true if the address is correct, false otherwise src

Used by

ip-address is downloaded ~66 million times per week, mostly via the Node proxy/agent ecosystem. The dependency chain runs through a handful of widely-used packages:

socks (~53M weekly) — SOCKS4/5 client for Node; depends on ip-address directly. The single biggest source of downloads.
socks-proxy-agent (~57M weekly) — http.Agent for SOCKS proxies; depends on socks. Bundled by virtually every CLI that respects HTTPS_PROXY.
npm and pnpm — both bundle socks-proxy-agent through their HTTP fetch stack (make-fetch-happen → @npmcli/agent), so every Node install on the planet pulls in ip-address as a transitive dependency.
Puppeteer — @puppeteer/browsers uses proxy-agent for browser-binary downloads, which routes through socks-proxy-agent → socks → ip-address.
proxy-agent (~28M weekly) and pac-proxy-agent (~27M weekly) — auto-detecting proxy agents (HTTP/HTTPS/SOCKS/PAC) used widely in scraping, headless-browser, and CI tooling.
cacache (~44M weekly) — npm's content-addressable cache; pulls in the same fetch stack.

Beyond the proxy chain, ip-address has been used by Juniper Networks' Contrail, Ably's proxy-protocol implementation, Rackspace's serialization framework, IPFS, and the SwitchyOmega Chrome extension, among many others.

Keywords

FAQs

What is ip-address?

Is ip-address popular?

Is ip-address well maintained?

Package last updated on 25 Jul 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

ip-address