python-socketio is the Python port of Socket.IO, and the GitHub copy is a mirror

This repository is a mirror, and that changes where you file things

The GitHub description is the whole sentence: mirror of https://code.miguelgrinberg.com/miguelgrinberg/python-socketio. Everything else in the repository confirms it. The README's test badge points at `code.miguelgrinberg.com` workflows rather than GitHub Actions. `pyproject.toml` lists the homepage, the source code URL, the issue tracker and the changelog all under `code.miguelgrinberg.com`, with GitHub appearing only in the funding links. And the tree contains a `.forgejo/` directory, which is the Forgejo instance where the canonical repository runs.

This is a meaningful practical detail rather than trivia. If you open an issue on GitHub you are filing it at a mirror that reports zero open issues, which is not because the project has none but because the tracker lives elsewhere. Same for pull requests: the README's link definitions point at `github.com/miguelgrinberg/python-socketio` for issues and pulls, while the resources section points at `code.miguelgrinberg.com` for git and the changelog. The two coexist in the README, which means the author has not fully sorted the links.

The release notes show the same split. All three recent releases, v5.17.0 on 2026-09-14, v5.16.4 on 2026-08-06 and v5.16.3 on 2026-06-15, contain nothing but a line saying see `CHANGES.md` for release notes, with that link pointing back at GitHub. So the tags are mirrored but the changelog content is not in the tag body.

For a reader, the practical consequence is: read the code here, but take the version numbers, the changelog and any bug discussion from the author's own instance. The project was last pushed on 2026-09-14, is not archived, is MIT licensed, and reports 4,370 stars with zero open issues.

The compatibility table is the most useful thing in the README

The README describes python-socketio as a Python implementation of the Socket.IO realtime client and server, and then immediately warns that the Socket.IO protocol has been through a number of revisions, some of which introduced backward incompatible changes, which means the client and the server must use compatible versions for everything to work.

That warning is followed by a three-row table mapping JavaScript Socket.IO version to Socket.IO protocol revision to Engine.IO protocol revision to python-socketio version. The rows are: JavaScript 0.9.x with protocol revisions 1 and 2 and Engine.IO revisions 1 and 2 maps to not supported. JavaScript 1.x and 2.x with protocol revisions 3 and 4 and Engine.IO revision 3 maps to python-socketio 4.x. JavaScript 3.x and 4.x with protocol revision 5 and Engine.IO revision 4 maps to python-socketio 5.x.

So the rule is mechanical: find your JavaScript client's major version, then take the corresponding python-socketio major. The first row is the one people forget, and it is a hard stop rather than a degraded mode. A python-socketio client cannot talk to a JavaScript 0.9.x client at all.

The README also states the obvious mitigation for pure Python systems: if you are using the Python client and server together, the easiest way to ensure compatibility is to use the same version of this package for both. That advice is worth following even though the compatibility table suggests some room, because a mismatched minor version can behave differently under load in ways the table does not capture.

Two required dependencies, and a small set of optional ones

The dependency list is short enough to state precisely. `pyproject.toml` declares `requires-python >= 3.8` and two required dependencies: `bidict >= 0.21.0` and `python-engineio >= 4.13.2`. Version 5.17.0 is the current release, licensed MIT, described in the manifest as Socket.IO server and client for Python.

The division of labour is worth understanding because it explains the design. `python-engineio` is the transport layer, handling the actual connection protocols and their fallbacks, while python-socketio sits on top implementing the Socket.IO semantics: rooms, namespaces, events, acknowledgements. That is why the Engine.IO protocol revision appears as its own column in the compatibility table: it is a separate protocol with its own versioning, implemented by a separate package with its own release cycle, and it carries the lower version bound of 4.13.2.

The optional dependencies are grouped by role. The `client` extra pulls in `requests >= 2.21.0` and `websocket-client >= 0.54.0`, so the synchronous client does not drag a networking stack into an installation that only runs a server. The `asyncio_client` extra pulls in `aiohttp >= 3.4` for the asyncio client. There are also `dev` and `docs` extras holding tox and sphinx with furo respectively.

That split is a small sign of care. A server deployment can install python-socketio with engineio and skip the HTTP client libraries entirely, which matters for images where every dependency is something you have to audit.

The topic tags reinforce the picture of what this library is for: `asyncio`, `eventlet`, `gevent`, `long-polling`, `low-latency`, `socket-io`, `socketio`, `socketio-server`, `web-server` and `websocket`. The presence of eventlet and gevent alongside asyncio tells you that all three concurrency models are supported, and `long-polling` alongside `websocket` is the visible reminder of why you would use this library instead of a raw WebSocket client.

Where Socket.IO differs from a plain WebSocket library

The topic tag list is a compact statement of the value proposition. `long-polling` next to `websocket` is the answer to the question people ask when comparing this to raw WebSockets: Socket.IO negotiates its transport, falling back from WebSocket to HTTP long-polling when a proxy or a corporate network blocks the upgrade. A raw WebSocket client has no such fallback, and a mobile client on a flaky network feels the difference.

The second difference is protocol versioning and reconnection. The README's warning that the protocol has been through a number of revisions with backward incompatible changes is a reminder that Socket.IO is a specified protocol with negotiation, not just a channel. That machinery comes for free here.

The third is semantics above the socket: events with names, acknowledgements, rooms for server-side grouping, and namespaces for separating applications on one connection. None of that exists in the WebSocket protocol itself.

What this library does not do is teach you to use any of it. The README has no quickstart, no code sample and no API tour. It links documentation at python-socketio.readthedocs.io, a contributor's guide at `CONTRIBUTING.md` and a security policy at `SECURITY.md`. The repository does carry `examples/`, `docs/` and `tests/` directories, so runnable material exists in the tree even though the README does not point at it. For a library this central to Flask-SocketIO and similar integrations, most people end up in the author's framework tutorials rather than in this repository, which is worth knowing before you start.

Documentation tooling is visible in the packaging: the `docs` extra uses sphinx with the furo theme, and `.readthedocs.yaml` configures the hosted build.

Funding, history and what the release cadence tells you

The README has a Sponsor this project section that asks for contributions rather than describing them abstractly, and names five platforms: GitHub Sponsors, Patreon, Buy me a Coffee, thanks.dev and PayPal. It also links the sponsor page on GitHub, which is how a GitHub mirror ends up being where the money is handled.

The release cadence over the visible history is roughly every two months: v5.16.3 on 2026-06-15, v5.16.4 on 2026-08-06, v5.17.0 on 2026-09-14. The jump from a patch release to a minor release between 5.16.4 and 5.17.0 means the project treats feature additions as minor version bumps, which is what you would expect from a library that maintains protocol compatibility with a JavaScript reference implementation.

Version 5.x itself has been the line for a while, and since 5.x maps to JavaScript Socket.IO 3.x and 4.x, the compatibility pressure comes from that side rather than from this repository. When the JavaScript reference implementation makes a protocol revision, this library is what has to move to match.

The remaining tree files are the ordinary ones for a Python project with real infrastructure: `pyproject.toml` with setuptools and a src layout, `tox.ini` for test environments, `MANIFEST.in`, `.gitignore`, `CODE_OF_CONDUCT.md`, `CHANGES.md`, `LICENSE`, `src/` and `tests/`. Pytest is configured with `asyncio_mode = auto` and a session-scoped default fixture loop, which confirms asyncio is tested as a first-class path rather than as an afterthought.

Nothing here suggests abandonment. The mirror pattern, the consistent release tags, the maintained security policy and the multi-platform funding all point to a project that is stable, independent and quietly maintained by one author.

Editorial conclusion

python-socketio is the sensible default when a Python service has to speak to JavaScript clients that use Socket.IO, because implementing the protocol's fallback transports and reconnection semantics yourself is exactly the work the library already did. The one thing to get right is the version pairing: 5.x speaks Socket.IO protocol revision 5 with Engine.IO revision 4, which is what JavaScript Socket.IO 3.x and 4.x clients expect, and mixing across that line is the most common cause of a silent connection failure. Also note where you actually are: the repository you are reading is a mirror, the release notes live in `CHANGES.md`, and issue tracking and commits live on code.miguelgrinberg.com.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. miguelgrinberg/python-socketio on GitHub
4. README
5. Releases