Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

DNS Lookup Cache

license Go Report Card Build Status Coverage godoc

The dnscache package provides a DNS cache layer to Go's net.Resolver.


Install using the "go get" command:

go get -u


Create a new instance and use it in place of net.Resolver. New names will be cached. Call the Refresh method at regular interval to update cached entries and cleanup unused ones.

resolver := &dnscache.Resolver{}

// First call will cache the result
addrs, err := resolver.LookupHost(context.Background(), "")

// Subsequent calls will use the cached result
addrs, err = resolver.LookupHost(context.Background(), "")

// Call to refresh will refresh names in cache. If you pass true, it will also
// remove cached names not looked up since the last call to Refresh. It is a good idea
// to call this method on a regular interval.
go func() {
    t := time.NewTicker(5 * time.Minute)
    defer t.Stop()
    for range t.C {

If you are using an http.Transport, you can use this cache by specifying a DialContext function:

r := &dnscache.Resolver{}
t := &http.Transport{
    DialContext: func(ctx context.Context, network string, addr string) (conn net.Conn, err error) {
        host, port, err := net.SplitHostPort(addr)
        if err != nil {
            return nil, err
        ips, err := r.LookupHost(ctx, host)
        if err != nil {
            return nil, err
        for _, ip := range ips {
            var dialer net.Dialer
            conn, err = dialer.DialContext(ctx, network, net.JoinHostPort(ip, port))
            if err == nil {

In addition to the Refresh method, you can RefreshWithOptions. This method adds an option to persist resource records on failed lookups

r := &Resolver{}
options := dnscache.ResolverRefreshOptions{}
options.ClearUnused = true
options.PersistOnFailure = false