{"id":8815,"library":"aiohttp-asyncmdnsresolver","title":"aiohttp-asyncmdnsresolver: mDNS Resolver for aiohttp","description":"aiohttp-asyncmdnsresolver is an asynchronous resolver for aiohttp that extends its capabilities to include mDNS (multicast DNS) resolution. It leverages the zeroconf library to resolve '.local' domain names. The library is actively maintained by the aio-libs organization, with its current version being 0.1.1, and typically sees releases aligned with updates to aiohttp or zeroconf, or as new features and fixes are introduced.","status":"active","version":"0.1.1","language":"en","source_language":"en","source_url":"https://github.com/aio-libs/aiohttp-asyncmdnsresolver","tags":["aiohttp","asyncio","dns","mdns","zeroconf","networking"],"install":[{"cmd":"pip install aiohttp-asyncmdnsresolver","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency as this library provides a custom resolver for aiohttp.ClientSession.","package":"aiohttp","optional":false},{"reason":"Used internally for mDNS resolution capabilities.","package":"zeroconf","optional":false}],"imports":[{"symbol":"AsyncDualMDNSResolver","correct":"from aiohttp_asyncmdnsresolver.api import AsyncDualMDNSResolver"},{"note":"Use AsyncDualMDNSResolver if you need both mDNS and regular DNS fallback.","symbol":"AsyncMDNSResolver","correct":"from aiohttp_asyncmdnsresolver.api import AsyncMDNSResolver"}],"quickstart":{"code":"import asyncio\nimport aiohttp\nfrom aiohttp_asyncmdnsresolver.api import AsyncDualMDNSResolver\n\nasync def main():\n    # Use AsyncDualMDNSResolver for both mDNS (.local) and standard DNS resolution\n    resolver = AsyncDualMDNSResolver()\n    # Create a TCPConnector with the custom resolver\n    connector = aiohttp.TCPConnector(resolver=resolver, ssl=False)\n\n    async with aiohttp.ClientSession(connector=connector) as session:\n        # Example: Resolving a standard domain\n        try:\n            async with session.get('http://example.com') as response:\n                print(f\"Example.com Status: {response.status}\")\n        except Exception as e:\n            print(f\"Could not connect to example.com: {e}\")\n\n        # Example: Resolving an mDNS (.local) domain (replace with a real mDNS host if available)\n        try:\n            async with session.get('http://mydevice.local.') as response:\n                print(f\"Mydevice.local Status: {response.status}\")\n        except Exception as e:\n            print(f\"Could not connect to mydevice.local: {e}\")\n\n    await resolver.close()\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates how to integrate `aiohttp-asyncmdnsresolver` with `aiohttp.ClientSession` to enable both mDNS (`.local` hostnames) and standard DNS resolution. It uses `AsyncDualMDNSResolver` which attempts mDNS first and falls back to regular DNS, providing comprehensive hostname resolution. Remember to replace `mydevice.local.` with an actual mDNS-resolvable host on your network for testing mDNS."},"warnings":[{"fix":"Use `aiohttp_asyncmdnsresolver.api.AsyncMDNSResolver` or `AsyncDualMDNSResolver` with `aiohttp.TCPConnector`.","message":"aiohttp's default resolver (and optionally aiodns) does not support mDNS names. Attempting to resolve '.local' domains without this library will result in resolution failures.","severity":"gotcha","affected_versions":"<0.1.0 (without AsyncDualMDNSResolver)"},{"fix":"For comprehensive resolution, import and use `aiohttp_asyncmdnsresolver.api.AsyncDualMDNSResolver`.","message":"The `AsyncMDNSResolver` class only resolves mDNS names for '.local' domains and does not automatically fall back to standard DNS for other hostnames. For environments requiring both, `AsyncDualMDNSResolver` is recommended.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your environment's `setuptools` is updated to version 77+ before upgrading to `aiohttp-asyncmdnsresolver` v0.1.2 or later.","message":"Future versions (starting from `v0.1.2`, currently unreleased draft) will increase the minimum required `setuptools` version to `v77` or higher due to packaging metadata changes (PEP 639).","severity":"breaking","affected_versions":">=0.1.2 (unreleased)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Configure `aiohttp.TCPConnector` to use a resolver from `aiohttp-asyncmdnsresolver`, such as `AsyncDualMDNSResolver`, when creating your `aiohttp.ClientSession`.","cause":"aiohttp's default DNS resolver does not support mDNS resolution for '.local' domains, leading to an inability to connect to such hosts.","error":"aiohttp.client_exceptions.ClientConnectorDNSError: Cannot connect to host some_mdns_hostname.local:80 ssl:default [Domain name not found]"},{"fix":"Explicitly override the `aiohttp.TCPConnector`'s resolver with `aiohttp_asyncmdnsresolver.api.AsyncMDNSResolver` or `AsyncDualMDNSResolver` to ensure mDNS capabilities.","cause":"When the optional `aiodns` library is installed, `aiohttp` may use it as the default resolver. `aiodns` (based on `c-ares`) lacks native mDNS support, causing resolution failures for '.local' names.","error":"mDNS hostnames do not resolve when aiodns is installed."},{"fix":"For environments where you need to resolve both mDNS (`.local`) and standard DNS hostnames reliably, use `aiohttp_asyncmdnsresolver.api.AsyncDualMDNSResolver`.","cause":"Using `AsyncMDNSResolver` which prioritizes mDNS for '.local' names but does not fallback to regular DNS for all other names, or conversely, not using any custom resolver for mDNS names.","error":"Expected both '.local' and regular hostnames to resolve, but only mDNS names work (or only regular DNS names work)."}]}