{"library":"python-engineio","title":"Python Engine.IO","description":"Python-Engine.IO is a lightweight transport protocol implementation that facilitates real-time, bidirectional, event-based communication between clients and a server. It provides Python implementations for both the Engine.IO server and client, offering standard (threaded) and asyncio variants. The library is actively maintained, with frequent releases, and is currently at version 4.13.1. It forms the low-level transport layer for Socket.IO.","status":"active","version":"4.13.1","language":"en","source_language":"en","source_url":"https://github.com/miguelgrinberg/python-engineio","tags":["websocket","realtime","async","engine.io","client","server","networking","protocol"],"install":[{"cmd":"pip install python-engineio","lang":"bash","label":"Basic Installation"},{"cmd":"pip install \"python-engineio[client]\"","lang":"bash","label":"Client-side with standard Python"},{"cmd":"pip install \"python-engineio[asyncio_client]\"","lang":"bash","label":"Client-side with asyncio"},{"cmd":"pip install \"python-engineio[asyncio]\" uvicorn","lang":"bash","label":"Server-side with asyncio (e.g., Uvicorn)"},{"cmd":"pip install \"python-engineio[eventlet]\" eventlet","lang":"bash","label":"Server-side with Eventlet"}],"dependencies":[{"reason":"Core dependency for any Python library.","package":"python","optional":false},{"reason":"Used for HTTP communication in clients and polling transport.","package":"requests","optional":false},{"reason":"Default WebSocket client implementation.","package":"simple-websocket","optional":false},{"reason":"Alternative WebSocket client implementation.","package":"websocket-client","optional":false},{"reason":"Optional, for integrating with aiohttp applications (asyncio driver).","package":"aiohttp","optional":true},{"reason":"Optional, for integrating with Eventlet WSGI applications.","package":"eventlet","optional":true},{"reason":"Optional, for integrating with Gevent WSGI applications.","package":"gevent","optional":true},{"reason":"Optional, for WebSocket support with Gevent.","package":"gevent-websocket","optional":true},{"reason":"Optional, for integrating with Tornado applications (asyncio driver).","package":"tornado","optional":true},{"reason":"Common ASGI server for deploying asyncio Engine.IO applications.","package":"uvicorn","optional":true},{"reason":"Common WSGI server for deploying standard Engine.IO applications (e.g., with Eventlet/Gevent workers).","package":"gunicorn","optional":true}],"imports":[{"note":"For a standard (threaded) Engine.IO server.","symbol":"Server","correct":"import engineio\neio_server = engineio.Server()"},{"note":"For an asyncio-based Engine.IO server.","symbol":"AsyncServer","correct":"import engineio\neio_server = engineio.AsyncServer()"},{"note":"For a standard (threaded) Engine.IO client.","symbol":"Client","correct":"import engineio\neio_client = engineio.Client()"},{"note":"For an asyncio-based Engine.IO client.","symbol":"AsyncClient","correct":"import engineio\neio_client = engineio.AsyncClient()"},{"note":"To wrap an Engine.IO server instance for WSGI compatibility.","symbol":"WSGIApp","correct":"from engineio import WSGIApp"},{"note":"To wrap an Engine.IO server instance for ASGI compatibility.","symbol":"ASGIApp","correct":"from engineio import ASGIApp"}],"quickstart":{"code":"import engineio\nimport uvicorn\n\neio = engineio.AsyncServer(async_mode='asgi')\napp = engineio.ASGIApp(eio)\n\n@eio.on('connect')\nasync def connect(sid, environ):\n    print('connect ', sid)\n\n@eio.on('message')\nasync def message(sid, data):\n    print('message ', data)\n    await eio.send(sid, 'reply from server')\n\n@eio.on('disconnect')\nasync def disconnect(sid):\n    print('disconnect ', sid)\n\n# To run the server (requires uvicorn):\n# if __name__ == '__main__':\n#     uvicorn.run(app, host='127.0.0.1', port=5000)\n\n# --- Client Example (run in a separate process/script) ---\n# import engineio\n# import asyncio\n\n# eio_client = engineio.AsyncClient()\n\n# @eio_client.on('connect')\n# async def on_connect():\n#     print('client connected')\n#     await eio_client.send('Hello from client!')\n\n# @eio_client.on('message')\n# async def on_message(data):\n#     print('client received: ', data)\n\n# @eio_client.on('disconnect')\n# async def on_disconnect():\n#     print('client disconnected')\n\n# async def start_client():\n#     await eio_client.connect('http://localhost:5000')\n#     await eio_client.wait()\n\n# # To run the client:\n# # if __name__ == '__main__':\n# #    asyncio.run(start_client())\n","lang":"python","description":"This quickstart demonstrates a basic Engine.IO server using the `AsyncServer` with ASGI mode, integrated with `uvicorn`. It defines event handlers for connect, message, and disconnect. A corresponding `AsyncClient` example is commented out, showing how to connect to the server and send/receive messages. Remember to install `uvicorn` and run the server and client in separate processes."},"warnings":[{"fix":"Ensure all clients and servers are upgraded to be compatible with the same Engine.IO protocol version. Review `maxHttpBufferSize` if large payloads are expected.","message":"Engine.IO v4 introduced major breaking changes, including a reversal of the heartbeat (ping/pong) mechanism (server now pings, client responds), a new packet encoding format, and a reduced default `maxHttpBufferSize` (from 100MB to 1MB). Clients running on Engine.IO v3 will NOT be compatible with servers running on v4, and vice-versa.","severity":"breaking","affected_versions":"4.x.x (from 4.0.0 onwards)"},{"fix":"Always integrate the `engineio.Server` or `engineio.AsyncServer` instance with a compatible WSGIApp/ASGIApp and run it using an appropriate web server (e.g., `uvicorn`, `gunicorn` with `eventlet`/`gevent` workers). Refer to documentation for framework-specific integration examples.","message":"The Engine.IO server library is a protocol implementation and requires an underlying asynchronous framework or WSGI/ASGI web server (e.g., `eventlet`, `gevent`, `aiohttp`, `uvicorn`, `tornado`) to function as a complete web application. It does not provide its own standalone web server.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Initialize mutable default arguments inside the function body if no argument is provided, typically using `None` as the default in the signature: `def my_handler(sid, data, my_list=None): my_list = my_list or []`.","message":"When defining event handlers (e.g., with `@eio.on('message')`), avoid using mutable objects (like lists or dictionaries) as default arguments in the handler function signature. These defaults are created once when the function is defined and shared across all calls/sessions, leading to unexpected behavior.","severity":"gotcha","affected_versions":"All Python versions"},{"fix":"If custom JSON serialization is needed, configure it globally for your Engine.IO `Server` or `Client` instance once. Avoid overriding it in multiple places or with different modules within the same process.","message":"The library internally supports a single custom JSON module per process. Attempting to configure multiple custom JSON encoder/decoder modules might lead to unexpected behavior or errors, as documented in recent changes.","severity":"gotcha","affected_versions":"All versions (documented explicitly in 4.11.x and newer)"},{"fix":"It is recommended to use `python-engineio` with Python 3.10 or newer for full compatibility and ongoing support. Upgrade your Python environment if possible.","message":"Older Python versions (e.g., 3.7, 3.8, 3.9) are being dropped from continuous integration (CI) builds, indicating that while they might still work, active testing and support focus on newer Python versions (3.10+). The `requires_python` specifier is `>=3.8`.","severity":"deprecated","affected_versions":"<4.12.0 (CI dropping support started around this time)"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}