NintendoClients: implementing the Switch, Wii U and 3DS network protocols in Python

The package is a protocol implementation, and it says so in the first line

NintendoClients is described as a Python package to communicate with Switch, Wii U and 3DS servers, and the setup metadata describes it more bluntly as a library that implements various network protocols made by Nintendo.

That framing matters for reading the code and the warnings. This is not a wrapper around an official API, because there is no official API. It is an implementation of the wire protocols, which means it contains the authentication handshakes, the request formats and the response parsing for several generations of console.

The project is written by Yannik Marchand, published on PyPI as nintendoclients, MIT licensed, and the setup metadata gives the version as 5.1.0 while the release list shows 5.0.0 on 2026-08-02, 4.4.0 on 2026-04-14 and 4.3.0 on 2026-01-15. The package uses semantic versioning, and it requires Python 3.12 or later.

The source layout shows the structure. There is a nintendo/ package, with a nintendo.nex subpackage for the 3DS family of services and a nintendo.switch subpackage for the Switch, plus files/config and files/cert directories shipped as package data. The cert directory is the part that explains the design, because console protocols authenticate with client certificates rather than with a username and password alone.

The package is also generated rather than entirely hand written. A generate_protocols.py script sits at the top level next to setup.py, which suggests the protocol descriptions are compiled from some source of truth into the Python classes, and there is a tests directory and a docs directory with a mkdocs configuration and a readthedocs configuration.

Only two runtime dependencies are declared: anynet at about 1.1 and pycryptodome. A protocol library with two dependencies is a sign that most of the work is in the package itself rather than in the framework around it.

The compatibility target is a firmware version, and it moves

The single most important operational fact in the README is one sentence: for Switch servers, the latest system version that is currently supported is 22.5.0.

That is a compatibility statement with an expiry date. A console talks to the servers with a protocol that varies by system software version, and the library implements a specific set of those versions. When a new firmware ships with protocol changes, the library has to be updated to match, and until it is, a client on the new firmware may be unable to authenticate or may be rejected.

This is a fundamentally different maintenance model from a normal library. A typical dependency is updated when its maintainer chooses to release. This one has to be updated when the remote side changes, and the maintainer has to know what changed, which means the protocol work does not stop at release time.

The two older console families are covered too. The description says the package implements a client for various 3DS, Wii U and Switch servers, and the documentation site carries the list of servers that are currently supported. The three generations use different service families, with the 3DS ones under the nex name, and the older generations are not simply dead protocols in the sense of being unused, since the example scripts still talk to them.

The research side of the project is supported by a wiki on Nintendo servers and protocols, a readthedocs site for the classes and functions in the package, a Discord server and a GitHub discussions board. The wiki being separate from the code repository is a sensible arrangement, since protocol documentation changes on a different cadence than the implementation.

The example scripts are reads, with one comment change

The examples directory is the fastest way to understand what the package can do, and the README describes each script.

For the Switch, smm2_level.py downloads a Super Mario Maker 2 level and its thumbnails and prints information about the level and its creator. smm2_ninji.py requests the list of ninji courses and downloads a replay file. animalcrossing.py searches for an island by dodo code and prints information about it. system_update.py downloads the latest system update and unpacks it into exefs and romfs.

That last one is the most revealing of the set, because unpacking a system update into exefs and romfs is the kind of operation that only makes sense for someone studying how the console works rather than someone using a service. The same is true of the others: they are read operations, and the output is printed information about the level, the creator, the island.

The Wii U scripts follow the same pattern. donkeykong.py downloads DKC Tropical Freeze rankings and the replay file of the world record. mariokart.py downloads Mario Kart 8 rankings and the replay of whoever is in 500th place. miis.py requests all kinds of information about the primary mii associated with an account identifier. friends.py requests your friend list, incoming and outgoing friend requests and the blacklist.

The 3DS folder has one script, friends.py, and it changes your comment to Hello World. That is the only example in the set that writes to the account, and it is a comment on your own profile.

The custom folder is the one that shows the package is not only about Nintendo servers. server.py shows how to create a simple game server with both an authentication server and a secure server, and server_login.py logs in on a game server and disconnects immediately, which the README says can be used to test custom servers. That is the general-purpose value of the library: the authentication and session machinery is reusable for a server you run yourself, not just for Nintendo's own services.

The ban warning is the first thing in the README

The README opens with a warning rather than with a feature list, and it should be quoted rather than paraphrased, because it defines the terms on which the rest of the project is offered.

It says to keep in mind that Nintendo bans Switch devices that show suspicious behaviour. The package tries to mimic the behaviour of a real Switch as closely as possible, but using it is at your own risk, and you should make sure you know what you are doing.

There is a specific technical reason the risk exists. These protocols are designed to be spoken by a console with particular hardware identifiers, particular firmware and particular network behaviour. A client that gets the version wrong, that sends a request pattern no console would send, or that is missing something the real device always sends, looks like a device behaving oddly, and the server side can act on that.

The mitigation the project offers is fidelity, that is, making the client as close to a real Switch as possible, and the honest observation is that fidelity reduces the risk without removing it. The ban is described in terms of devices showing suspicious behaviour, which is a detection heuristic, not a specific signature, and heuristics can be triggered by a client that is faithful in almost every respect but differs in one.

For anyone planning to test this against a real account, the practical takeaway is that the safe order is to start with read-only operations, on a throwaway account, and to treat the version support statement as a hard boundary rather than a rough indication. A library that is a faithful protocol implementation and a library that is a working credential mechanism are not the same thing to risk.

Sponsorship is the funding model, and support is prioritised by tier

The project asks for sponsorship on GitHub, and the README is direct about what the money buys. Becoming a sponsor lets the maintainer spend more time on the project, which leads to faster updates, and sponsors get priority for personal support and feature suggestions.

That is a real trade-off to be aware of, and it is stated plainly rather than hidden. The support queue is prioritised by sponsorship tier, which means the community Discord and the GitHub discussions board are where non-sponsors get their answers, and where the questions are asked and answered in public where everyone can find them.

The schedule of the releases fits the story of a maintainer doing this on the side. 4.3.0 in January 2026, 4.4.0 in April, 5.0.0 in August, with the last push on 2026-10-03, means roughly quarterly releases with a major version bump when something breaks compatibility. The repository is not archived and the topics attached to it are the console names, so it is a focused project rather than a broad one.

Two things are worth noting for anyone building on the package. The MIT licence with the terms in the LICENSE file is the permissive case, so there is no obligation to publish a derivative. And the package version in the setup metadata, 5.1.0, differs from the newest tagged release of 5.0.0, which means the development version on the main branch is already ahead of the last published release and the difference between them is not described in the visible documentation.

Editorial conclusion

NintendoClients is worth reading if you are doing protocol research on Nintendo console services, because it is a working implementation of several generations of console protocols with the authentication flows already solved, which is far more useful than starting from packet captures. It is the wrong tool if you want a supported client, because the package has no contract with Nintendo and the compatibility target moves with every firmware update. Before you use it against a real account, verify three things yourself: that the Switch firmware version the package supports is still the one your console runs, since the README names 22.5.0 as the latest supported and nothing beyond that, that you accept the ban risk the README states plainly, and that the credentials you supply are throwaway, because the example scripts log in with an account and a mismatch in the protocol version is exactly the kind of thing that looks like suspicious behaviour to the server side.

Frequently asked questions

Official sources

1. Issues
2. kinnay/NintendoClients on GitHub
3. License: MIT
4. README
5. Releases