Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Asynchronous DNS lookups for Tornado
Python Emacs Lisp Shell
Branch: master
Pull request Compare This branch is 2 commits ahead, 1 commit behind eklitzke:master.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


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.

Something went wrong with that request. Please try again.