ruby/ipaddr: the default gem that keeps an address and its netmask together

You probably already have it, at whatever version Ruby shipped

This library is part of the standard Ruby distribution as a default gem, synchronized periodically, which is the first thing to establish before adding a dependency. Being a default gem does not mean being fixed: the copy you get is the one your Ruby version bundles, and that copy is only as new as your Ruby is. The documented reason to depend on it explicitly is a version constraint, the case where you need a newer ipaddr than older Ruby versions bring along.

gem 'ipaddr', '~> 1.2'

With that line in the Gemfile, the install step is the usual one.

$ bundle

Or, without a Gemfile at all, the gem installs itself.

$ gem install ipaddr

So the decision is not whether to install ipaddr but whether to accept the bundled version or pin a range, and the recent tags in the 1.2 line are what a `~> 1.2` constraint is written against.

mask returns a new address and leaves the original alone

The usage example is short enough to read in full, and every line of it shows something about the design.

require 'ipaddr'

ipaddr1 = IPAddr.new "3ffe:505:2::1"

p ipaddr1                   #=> #<IPAddr: IPv6:3ffe:0505:0002:0000:0000:0000:0000:0001/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff>

p ipaddr1.to_s              #=> "3ffe:505:2::1"

ipaddr2 = ipaddr1.mask(48)  #=> #<IPAddr: IPv6:3ffe:0505:0002:0000:0000:0000:0000:0000:0000/ffff:ffff:ffff:0000:0000:0000:0000:0000>

p ipaddr2.to_s              #=> "3ffe:505:2::"

ipaddr3 = IPAddr.new "192.168.2.0/24"

p ipaddr3                   #=> #<IPAddr: IPv4:192.168.2.0/255.255.255.0>

`mask(48)` takes a prefix length and hands back a different IPAddr, with the mask applied and the host bits cleared. Nothing mutates in place, so `ipaddr1` still prints the full ffff mask after the call, which is the behaviour you want when you are walking a list of prefixes and need to keep the original around.

p expands every group while to_s keeps the compressed form

The same object prints two different ways, and the difference is not cosmetic. Inspecting `ipaddr1` shows every hextet expanded and padded, 3ffe:0505:0002:0000:0000:0000:0000:0001, followed by the prefix written as a mask of ffff values. `to_s` on the same object returns the compressed text you typed, 3ffe:505:2::1. After masking to 48, the compressed form collapses further to 3ffe:505:2:: because the remaining host bits are all zero, while the inspected form still shows the full eight groups plus a mask of ffff:ffff:ffff:0000 and four zero groups. Practical consequence: use `to_s` for anything a human or a log line will read, and expect the inspected form in debugging output to be much longer than the value you passed in.

A CIDR string arrives with its prefix already attached

Constructing from a slash notation keeps the prefix in the object, so there is no separate netmask argument to keep in sync. `IPAddr.new "192.168.2.0/24"` inspects as IPv4:192.168.2.0/255.255.255.0, which shows the dotted netmask form for IPv4 where the IPv6 example showed the colon-separated one. Both families are handled by the same class, and both keep address and prefix in a single value, so an address that came from configuration does not need its netmask reconstructed later. The library's stated scope is a set of methods to manipulate an IP address, with IPv4 and IPv6 supported, and the README does not walk through the wider method list, so the examples above are the documented surface rather than the whole of it. Anything beyond parsing, printing and masking, such as walking a range of addresses, has to be checked against the source in lib/ rather than assumed from the examples.

The alternative the README names is ipaddress, with a shim for ipaddr

One competitor is recommended by name, and the recommendation comes with a condition rather than a preference. The ipaddress gem is described as a popular, extensive library for manipulating IP addresses that carries a layer of compatibility with `ipaddr`, and the guidance is to try it if you need a richer set of features than ipaddr has. So the choice is a size trade: ipaddr is the smaller default gem that is already present and needs no declaration, while ipaddress is the larger library whose compatibility layer means existing ipaddr-shaped code can move across. What the README does not offer is a feature-by-feature comparison, so the practical test is whether the specific operation you need exists in ipaddr at all, since the escape hatch is only worth taking once you know what is missing.

Releasing is a version.rb edit and one rake task

The development workflow is spelled out for anyone working on the gem itself. After checking out the repository, `bundle install` installs dependencies and `rake test` runs the tests. To put the gem on a local machine, `bundle exec rake install` does it. Releasing is a two-step affair: update the version number in `version.rb`, then run `bundle exec rake release`, which creates a git tag for the version, pushes git commits and tags, and pushes the `.gem` file to rubygems.org. That last task does tagging, pushing and publishing in one command, so a release is a single invocation after the version bump and nothing else. The tree is correspondingly plain: a Rakefile, ipaddr.gemspec, Gemfile, lib/, test/, a CHANGELOG.md, LICENSE.txt and a .document file. Testing runs in GitHub Actions through a workflow file under .github/actions/workflows/test.yml, which is the badge the README links to, so a change to the library is exercised on every push rather than only on a maintainer's machine.

The tags show a long pause, then two releases two days apart

Version history is worth reading before you decide how much to trust the library. v1.2.7 was published on 2024-10-19, then nothing for the better part of a year and a half until v1.2.8 on 2026-04-23, with v1.2.9 following on 2026-04-25. So the recent pattern is two tags two days apart after a long quiet stretch, rather than a steady trickle of fixes. The last push to master is dated 2026-09-09, which is more recent than any tag. Licensing is the 2-Clause BSD License, and bug reports and pull requests are taken on GitHub at the repository, with no separate process described beyond that.

Editorial conclusion

Use ipaddr when a job is small and specific: parsing an address, keeping a prefix attached to it, or narrowing one with a mask, with no gem declaration needed because it already ships with Ruby. Do not reach for it when you need range iteration, richer address maths or broader protocol coverage, because the README points at the ipaddress gem for exactly that case and keeps a compatibility layer with ipaddr. Before you pin a version, check which one your Ruby ships, since the default gem is only synchronized periodically and the last releases landed on 2026-04-23 and 2026-04-25 after a long quiet stretch.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes