Asynchronous DNS lookups for Tornado
Clone or download
Latest commit a2a1a04 Mar 31, 2015
Type Name Latest commit message Commit time
Failed to load latest commit information.
tornado_dns add some basic unit tests May 17, 2010
.dir-locals.el initial commit May 16, 2010
.gitignore initial commit May 16, 2010 colorize the README file Mar 31, 2015 initial commit May 16, 2010
runtests add some basic unit tests May 17, 2010


This lets you do asynchronous DNS lookups using Tornado. Look at for an example of a very simple program that does a DNS lookup.

Only a basic subset of operations is supported. Right now, the following things work:

  • Resolving A records
  • Resolving CNAME records

This is approximately the functionality implemented by gethostbyname(3). There are plans to implement support for at least the following, in short order:

  • Resolving PTR records (a.k.a. "reverse DNS")
  • Resolving MX records
  • Resolving TXT records

There are no immediate plans for implementing other, exotic features of DNS. DNS is surprisingly complex, and the author feels that too many implementors of DNS libraries go overboard creating comprehensive, but complex and hard-to-use software. This library keeps it simple; if you want something that implements the absolutely everything, including all of the exotic, rarely used parts of the DNS specs, you may consider using dns-python with your own resolver.

Basic Usage:

The most basic possible usage:

def success(addresses):
    print 'the address is %s' % (addresses[''],)

# timeout after 5000 milliseconds
tornado_dns.lookup("", success, timeout=5000)

You'll need to do the lookup in the context of a tornado IOLoop that's running. Look at for a very slightly more example.

More Nonsense


This software depends on tornado, and that's it. There's one more non-standard module you'll need if you're interested in running the unit tests (see below), but other than that everything you need is right here.


There's no support for fallback to TCP. This is something I'd like to fix.

There's no support for non-recursive queries. In particular, you must have a nameserver in your /etc/resolv.conf that's capable of performing recursive DNS lookups. This should be OK for 99.9% of people, but it's something I'd like to fix anyway.

If you find other bugs, have patches, etc. please contact the author via private message on github (username eklitzke) or via email,


This code comes with unit tests that test against a domain that the author owns/controls. They should pass. To run them, you'll need the qa module in your PYTHONPATH. Just run ./runtests and you should see some text showing that everything is OK.


This code is licensed under the terms of the Apache License, Version 2.0. This is the same license used by the main Tornado project.