Ruby has a new WHOIS library

Today I'm announcing the availability of a new WHOIS library written in pure Ruby. The library is called (drum roll…) Whois and it exposes most of the features available in the excellent Linux WHOIS library written by Marco d'Itri (hey, an other Italian guy!). In fact, I must confess this library has been largely inspired by Marco's one.

Despite I spent weeks reading source code from the available WHOIS libraries, Ruby Whois has been built from scratch trying to focus on long-term maintainability and flexibility and cannot be considered a Ruby port of any of other existing Whois libraries.

Update: Ruby Whois 0.5.1 is now available. It includes a ruby-whois command line utility and a couple of other improvements.

Why does Ruby need an other WHOIS library?

Back in May I started looking for a Ruby WHOIS library for my RoboDomain project. I carefully reviewed all existing solutions but I didn't find what I was looking for.

What I wanted was a pure Ruby library that didn't rely on external libraries, allowed me to query both IP addresses and top level domain WHOIS servers. You might argue that these are very basic requirements, and in fact they are. Unfortunately, all available solutions missed at least one or both requirements. They were also really outdated, except for the promising Universal Whois library.

So I started to work on a new WHOIS library. It took about one month to get the right design, then I started coding the library. After a couple of weeks the library was ready.

Whois is the new whois gem

Thanks to Cyril Mougel, the author of the first whois gem, Whois is going to be the new whois gem. Cyril yields me the privilege to use the whois RubyForge project for my new WHOIS client so that there won't be an other WHOIS library in the Ruby ecosystem.

Current Whois 0.4.2 users can safely upgrade to the new whois gem. A compatibility adapter has been created in order to provide a seamlessly transition. Installing or upgrading to Whois 0.5.0 is just as easy as executing the following command in your command prompt.

$ gem install whois

You might need administrator privileges on your local machine.

If you are upgrading from a previous Whois version, be sure to check your application log for deprecation warnings.

Whois Features

The new Whois provides the following key features:

  • It's written in pure Ruby without any additional dependency and it has been successfully tested against multiple Ruby platforms and versions including Ruby, Ruby Enterprise Edition (for the happiness of Rails users) and MacRuby.
  • It provides a flexible and extensible interface. You can define custom servers on the fly.
  • It enables you to query registry data for IPv4, IPv6 and top level domains
  • It exposes an object oriented design
  • It's 100% compatible with the legacy Whois library

Example Usage

The most simple way to get WHOIS details is to use the all-in-one Whois.whois method.

require 'rubygems'
require 'whois'

puts Whois.whois("")

If you want more control, you can initialize a new WHOIS client and query the WHOIS server on request.

require 'rubygems'
require 'whois'

@client =

%w( do |domain|
  puts @client.query(domain)

By default, the client sets a timeout of 5 seconds. If the server doesn't respond within the timeout, the execution is stopped and the client raises a Timeout::Error exception.

5 seconds is a reasonable amount of time, but you might want to change it or to disable the timeout for a specific execution.

require 'rubygems'
require 'whois'

@client =

# sets timeout to 1 second
@client.timeout = 1
puts @client.query("")

# disable timeout
@client.timeout = nil
puts @client.query("")

For the full documentation visit the Ruby Whois project website.


This library has been made possible by many people and projects that inspired me either directly or indirectly. I would like to thank you Cyril Mougel, Marco d'Itri and its Debian Whois library, the Net::DRI PERL package, the PHPWhois package and all the existing Ruby WHOIS libraries.

Contributions and Discussions

If you want to contribute, feel free to fork the project on GitHub. Please, remember that patches and features are welcomed as long as they come with a suitable test suite.