aiodns

library4.0.4pypypi✓ verified 25d ago

aiodns is a Python library that provides a simple way to perform asynchronous DNS resolutions using the `asyncio` framework and `pycares` as its backend. The current version is 4.0.0, and it generally follows an active release cadence with several updates throughout the year to improve performance, add features, and maintain compatibility with newer Python and `pycares` versions.

http-networking database

pip install aiodns

github ↗package ↗

INSTALL

IMPORT

SIG · AIODNS

aiodns

http-networkingpythonv4.0.4

Install

2.0s avg

Import

246ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.0.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.254s · 20MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.0s · import 0.238s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DNSResolver

✓ from aiodns import DNSResolver

DNSError

✓ from aiodns import error

DNSError is part of the 'error' submodule.

This quickstart demonstrates how to perform an asynchronous 'A' record DNS lookup using the `DNSResolver` class and its recommended `query_dns` method. It includes basic error handling and shows the crucial step of closing the resolver to release resources.

import asyncio from aiodns import DNSResolver async def resolve_a_record(hostname): resolver = DNSResolver() try: # query_dns returns native pycares 5.x DNSResult types result = await resolver.query_dns(hostname, 'A') for record in result.answer: print(f"Hostname: {hostname}, Type: A, Address: {record.data.addr}") except Exception as e: print(f"DNS resolution failed for {hostname}: {e}") finally: # It's important to close the resolver when no longer needed. # For long-lived resolvers, manual closing is often done at application shutdown. resolver.close() async def main(): await resolve_a_record('google.com') await resolve_a_record('nonexistent.example.com') # Example of a failed lookup if __name__ == '__main__': asyncio.run(main())

Debug

Known issues

breakingVersion 4.0.0 introduces a breaking change requiring `pycares >= 5.0.0`. Older `pycares` versions are incompatible and will cause issues.

fix

Ensure `pycares` is updated to version 5.0.0 or higher by running `pip install 'pycares>=5.0.0'`.

affects: 4.0.0 and later

deprecatedThe `query()` method is deprecated in favor of `query_dns()`. While `query()` still works for backward compatibility with `aiodns 3.x` result types, `query_dns()` returns native `pycares 5.x DNSResult` types which are preferred.

fix

Migrate your code to use `await resolver.query_dns(host, type)` instead of `await resolver.query(host, type)` to benefit from native `pycares` result types and future compatibility. Review `pycares` documentation for details on `DNSResult` structure.

affects: 4.0.0 and later

deprecatedThe `gethostbyname()` method is deprecated. Use `getaddrinfo()` instead for host and port resolution.

fix

Replace calls to `gethostbyname()` with `getaddrinfo()`. This aligns with modern socket API practices and offers better IPv6 support and flexibility.

affects: 4.0.0 and later

gotcha`DNSResolver` instances are designed to be long-lived and reused across many queries to avoid unnecessary overhead. Remember that `resolver.close()` is a coroutine and must be awaited for proper resource cleanup. While `DNSResolver` supports the async context manager (`async with DNSResolver()`), using it for frequent, short-lived instances is discouraged due to performance implications. It's best suited for testing or one-off scripts where automatic cleanup is critical.

fix

For most applications, create a single `DNSResolver` instance and reuse it. Ensure you `await resolver.close()` explicitly when the application is shutting down or the resolver is definitively no longer needed. Avoid creating and destroying `DNSResolver` objects in a tight loop.

affects: All versions

gotchaOn Windows, if you are using a custom build of `pycares` that links against a non-thread-safe `c-ares` library, `aiodns` might require `asyncio.SelectorEventLoop` or `winloop`. This is generally not an issue for users of official prebuilt `pycares` wheels (version 4.7.0 or later), as they include a thread-safe `c-ares`.

fix

Most users can safely ignore this warning when using official `pycares` wheels. If you encounter issues on Windows or are using a custom `pycares` build, consider explicitly setting the event loop to `SelectorEventLoop` or using `winloop`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'aiodns'

The 'aiodns' module is not installed in the Python environment.

fix

Install the 'aiodns' module using pip: 'pip install aiodns'.

ImportError: cannot import name 'DNSResolver' from 'aiodns'

The 'DNSResolver' class is not available in the 'aiodns' module, possibly due to version incompatibility or incorrect import.

fix

Ensure you are using the correct version of 'aiodns' and import 'DNSResolver' correctly: 'from aiodns import DNSResolver'.

AttributeError: module 'aiodns' has no attribute 'DNSResolver'

The 'DNSResolver' class is not found in the 'aiodns' module, likely due to an outdated version or incorrect installation.

fix

Update 'aiodns' to the latest version using pip: 'pip install --upgrade aiodns'.

RuntimeError: aiodns needs a SelectorEventLoop on Windows.

On Windows, 'aiodns' (or its underlying 'pycares' dependency, depending on its build) requires 'asyncio.SelectorEventLoop', but the default 'ProactorEventLoop' is active.

fix

Add 'if sys.platform == 'win32': asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())' at the very beginning of your application code before any asyncio operations.

AttributeError: module 'pycares' has no attribute 'QUERY_TYPE_CAA'

The installed version of 'pycares' is incompatible with the 'aiodns' version, missing an attribute that 'aiodns' expects (e.g., specific query types or result structures).

fix

Upgrade 'pycares' to a version compatible with your 'aiodns' installation, usually by running 'pip install --upgrade pycares'.

Upgrade

Version history

4.0.4latest on PyPI · released May 20, 2026

Audit

Dependencies

pycaresrequiredRequired backend for DNS resolution; aiodns is a wrapper around pycares.

Agent activity

63 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/aio-libs/aiodns.git ↗

packagehttps://pypi.org/project/aiodns/ ↗