aiohappyeyeballs

2.6.1 verified Tue May 12 auth: no python install: stale quickstart: stale

Happy Eyeballs for asyncio, currently at version 2.6.1. The library is actively maintained and facilitates easy connection establishment with fallback strategies using asyncio.

pip install aiohappyeyeballs

Common errors

error ModuleNotFoundError: No module named 'aiohappyeyeballs' ↓

cause The 'aiohappyeyeballs' package is not installed in the current Python environment.

fix

Install the package using pip: 'pip install aiohappyeyeballs'.

error ImportError: cannot import name 'start_connection' from 'aiohappyeyeballs' ↓

cause The function 'start_connection' is not found in the 'aiohappyeyeballs' module, possibly due to an incorrect import statement.

fix

Ensure the correct import statement: 'from aiohappyeyeballs import start_connection'.

error TypeError: start_connection() missing 1 required positional argument: 'addr_infos' ↓

cause The 'start_connection' function was called without the necessary 'addr_infos' argument.

fix

Provide the required argument when calling the function: 'socket = await start_connection(addr_infos)'.

error IndexError: tuple index out of range (in start_connection method) ↓

cause This specific IndexError occurs in the `start_connection` method when socket creation fails with an exception other than an `OSError`, which was a known bug in older versions, particularly when `uvloop` was in use.

fix

Update aiohappyeyeballs to the latest version to get the fix: pip install --upgrade aiohappyeyeballs

error OSError: [Errno 113] Connect call failed ('<IP_ADDRESS>', <PORT>) ↓

cause The `aiohappyeyeballs` library failed to establish a connection to the specified host and port because the target machine was unreachable or actively refused the connection (e.g., firewall, incorrect IP/port, server not running).

fix

Verify the target host's IP address and port are correct, ensure the server is running and accessible, and check for any firewall rules blocking the connection.

Warnings

breaking Import paths have changed in v2.5.0. Ensure you import using the new structure. ↓

fix Update import statements to use 'from aiohappyeyeballs import HappyEyeballs'.

gotcha Python versions below 3.9.2 may lead to a TypeError during import. ↓

fix Upgrade Python to 3.9.2 or higher.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

HappyEyeballs
```
from aiohappyeyeballs import HappyEyeballs
```
Avoid using direct import from the old module structure.

Quickstart stale last tested: 2026-04-23

Basic usage of HappyEyeballs to resolve an address asynchronously.

import asyncio
from aiohappyeyeballs import HappyEyeballs

async def main():
    resolver = HappyEyeballs()
    addr = await resolver.resolve('example.com')
    print(addr)

asyncio.run(main())