Skip to content


Subversion checkout URL

You can clone with
Download ZIP
IP address manipulation library
Branch: master


ruby-ip library

This is a library for manipulating IP addresses.



gem install ruby-ip


git clone git://


Feature overview

  • Create from string and to string

    require 'ip'
    ip ="")
    ip.to_s       # ""
    ip.to_i       # 3221226037
    ip.to_b       # 11000000000000000000001000110101
    ip.to_hex     # "c0000235"
    ip.to_addr    # ""
    ip.to_arpa    # ""
    ip.pfxlen     # 24
  • Qualify IP address with “routing context” (VRF)

    ip ="")
    ip.to_s       # ""
    ip.to_addrlen # ""
    ip.ctx        # "cust1"
  • Clean implementation of IP::V4 and IP::V6 as subclasses of IP

    ip1 ="")       #<IP::V4>
    ip2 ="2001:db8:be00::/48")  #<IP::V6 2001:db8:be00::/48>
    ip1.is_a?(IP::V4)                   # true
  • Create directly from integers or hex

    ip =, 24, "cust1")
    ip ="c0000235", 24, "cust1")
  • Netmask manipulation

    ip ="")         #<IP::V4>      #<IP::V4>
    ip.broadcast       #<IP::V4>
    ip.broadcast(-1)   #<IP::V4>
    ip.mask            # 255
    ip.size            # 256
    ip.netmask.to_s    # ""
    ip.wildmask.to_s   # ""
  • Address masking

    ip ="")
    ip.offset?         # true
    ip.offset          # 53
    ip.to_s            # ""
    ip.offset?         # false
  • Simple IP arithmetic

    ip ="")
    ip + 4             #<IP::V4>
    ip | 7             #<IP::V4>
    ip ^ 7             #<IP::V4>
    ~ip                #<IP::V4>
  • Advanced Subnet Operations

    sn ='')
    ip ='')
    sn.split                    [#<IP::V4>, 
                                #<IP::V4>] (2 evenly divided subnets)
    sn.divide_by_subnets(3)     [#<IP::V4>, 
                                #<IP::V4>] (4 evenly divided subnets)
    #keep in mind this always takes into account a network and broadcast address
    sn.divide_by_hosts(100)     [#<IP::V4>, 
                                #<IP::V4>] (128 hosts each)
    ip ='')
    => true
  • Convert to and from a compact Array representation

    ip1 ="")
    ip1.to_a     # ["v4", 3221226037, 24, "cust1"]
    ip2 =["v4", 3221226037, 24, "cust1"])
    ip1 == ip2   # true
  • Hex array representation, useful when talking to languages which don't have Bignum support

    ip1 ="2001:db8:be00::/48@cust1")
    ip1.to_ah    # ["v6", "20010db8be0000000000000000000000", 48, "cust1"]
    ip2 =["v6", "20010db8be0000000000000000000000", 48, "cust1"])
    ip1 == ip2   # true
  • Addresses are Comparable, sortable, and can be used as Hash keys

Why not IPAddr?

Ruby bundles an IPAddr class (ipaddr.rb). However there are a number of serious problems with this library.

  1. Given an IP address with a netmask or prefix (e.g. it's very hard to get access to the netmask part. It involves digging around instance variables.

  2. It's impossible to deal with an off-base address with prefix, because IPAddr forcibly masks it to the base. e.g. is stored as

  3. IPAddr uses calls to the socket library to validate IP addresses, and this can trigger spurious DNS lookups when given an invalid IP address. ruby-ip does not depend on the socket library at all, unless you require 'ip/socket' to have access to the Socket::AF_INET and Socket::AF_INET6 constants.


You may use, distribute and modify this software under the same terms as ruby itself (see LICENSE.txt and COPYING.txt)

Something went wrong with that request. Please try again.