NS-USBloader, a Java front end for Switch homebrew installation

Three tools in one application: installer, payload sender, file splitter

NS-USBloader does three separate jobs, and the README is clearer about them than the single-sentence repository description suggests.

The first is a PC-side installer for NSP packages. It speaks the command set of Huntereb's Awoo-Installer and of other compatible installers, over both USB and network, and it also handles the USB path for XorTroll's Goldleaf. The README positions it explicitly as an alternative to the default command-line tools: `usb_install_pc.py`, `remote_install_pc.py`, and GoldTree or Quark. That is the clearest statement of purpose in the project, because those scripts are the reference implementations everyone else is measured against.

The second is an RCM payload tool, which sends a payload to a console. This is a separate box in the interface with separate requirements, and it is where the platform support list matters most: Windows, macOS on both Intel and Apple Silicon, and Linux on x86, amd64 and Raspberry Pi ARM.

The third is a file tool. It creates split files and merges split files back into one, which is a utility rather than a Switch-specific feature, and it is the part of the application most likely to be used by someone who found it for a different reason.

The audience is therefore narrower than a Switch homebrew audience in general. This is not a firmware flasher, a homebrew launcher, or a game manager; it is a graphical front end for two specific workflows plus a file utility, and the value it offers over the scripts is entirely interface, cross-platform packaging and the bundled driver installation on Windows.

The Awoo command set, its Tinfoil ancestry, and what Goldleaf versions work

The protocol layer is worth understanding because it explains why several different front ends behave identically.

The README states that Awoo Installer uses the same command set, described in quotes as a protocol, as Adubbz's Tinfoil, and that a lot of other forks and applications use that same command set. It then explains a naming decision: to stop speculating about the name, it is now called Awoo, and it was called TinFoil before, and is not any more. So the tool that started this family is the one most users know by its older name, and the naming churn in this corner of the ecosystem is a documentation problem as much as a technical one.

The second compatibility axis is Goldleaf, and here the README carries an actual table rather than a claim. It maps Goldleaf versions to the NS-USBloader versions that work with them: Goldleaf v0.5 pairs with NS-USBloader v0.4 through v0.5.2 and with v0.8 and later, v0.6 has no entry, v0.6.1 pairs with v0.6, v0.7 through v0.7.3 pair with v0.7 and later, v0.8 and v0.9 pair with v1.0 and later, v0.10 through 1.0.0 pair with v6.0 and later, v1.1.0 and v1.1.1 have no entry, and v1.2.0 and later pair with v6.0 and later. Where the table says plus, it means any subsequent NS-USBloader version.

Read the current row against the newest release and you get a concrete answer. Version 7.3 satisfies every row that has an entry at all, so it covers Goldleaf v0.5, v0.7 and later, v0.8 and later, v0.10 and later, and v1.2.0 and later. Two Goldleaf lines are explicitly unsupported: v0.6 and v1.1.0 through v1.1.1. Those gaps are not explained, so if your Goldleaf is one of them the table tells you the combination will not work and nothing else.

The table is also historical rather than a maintained support matrix, since it spans NS-USBloader versions from v0.4 to v7.3. It is best used as a rule of thumb for older pairings and as a reason to test before you rely on a specific combination.

Running it on Linux: the jar, two udev rules, and a HiDPI flag

The Linux instructions are the most complete in the README, and they are worth following in order.

You need a JRE or JDK at 8u60 or higher. The README notes that openJDK is good and Oracle's is also good, and that JavaFX is not needed separately because it is embedded in the jar. Then you launch it:

java -jar /path/to/NS-USBloader.jar

Running that as root works, and the next two steps exist so that you do not have to. The first rule covers the device used for installation, identified by USB vendor 057e and product 3000, and the second covers the RCM side, vendor 0955 and product 7321:

root # vim /etc/udev/rules.d/99-NS.rules
SUBSYSTEM=="usb", ATTRS{idVendor}=="057e", ATTRS{idProduct}=="3000", MODE="0666"
root # udevadm control --reload-rules && udevadm trigger

The same pair of lines goes into a second file for the RCM rules, with the different vendor and product identifiers, followed by the same reload command.

Before you paste that in, read the mode. `MODE="0666"` makes the device node readable and writable by every user on the machine, not just the one you want to grant access to. It is the approach the README documents and it is the conventional way to avoid running a USB tool as root, but on a multi-user Linux desktop a group-owned rule with a narrower mode is the tighter option, and udev supports it. This is a real decision rather than a nitpick: on a shared machine, 0666 on a device that can install packages is access you are handing to every account on it.

The last Linux step is cosmetic. For HiDPI displays the README gives a scaling property rather than a settings dialog:

java -Dglass.gtk.uiScale=150% -jar application.jar

That it is a GTK-specific system property is a small clue about how the interface is built, and it is worth knowing before you expect the same flag to work on the macOS or Windows builds.

Per-platform builds: the -m1.jar, embedded JavaFX, and a JDK number that changes

The platform sections are where this README gets inconsistent, and anyone setting this up on a specific machine needs to know which sentence applies to them.

The stated system requirements say JDK 17 for macOS and Linux, and libusb if you have a Mac with Apple Silicon, installed with `brew install libusb`. The Linux usage section then says to install a JRE or JDK at 8u60 or higher. The macOS section says JDK 19 is recommended and that issues have already been reported from users on a Mac with JDK 14. Three different numbers, in three sections, for the same application. The most likely reading is that the requirements line was updated for current platforms while the per-platform sections were written for the versions current at the time, but the README does not say so, and picking a JDK from the wrong line is an easy way to waste an afternoon.

Apple Silicon has its own path. You download the build with the `-m1.jar` postfix rather than the plain jar, and you install libusb manually through Homebrew. That the ARM build needs a manual dependency while the others do not is consistent with the build files at the top of the repository, which include a `.make_aarch64` script alongside a `.make_legacy` one.

The Raspberry Pi instructions are the third case and they contradict the embedded JavaFX claim. On a Pi you install a JDK with `sudo apt install default-jdk`, and then, for the user interface, you install JavaFX separately with `sudo apt install openjfx`. The Pi section also tells you to reuse the udev steps from the Linux section. So on ARM Linux the self-contained jar is not self-contained, which is a packaging limitation rather than a documentation error, but it is the kind of thing that only surfaces when you are standing in front of the device.

Windows is the outlier in the other direction. There is no jar to launch by hand: you open the application, click the gear icon, choose Download and install drivers, and install them. Bundling driver installation inside the application is a genuine convenience, and it is also the reason this build behaves differently from the others at first launch.

git.redrise.ru is the source of truth, and GitHub is a mirror

The hosting arrangement is unusual enough to check before you depend on this project, and the README states it directly.

There are three destinations, each with a different role. An independent source code storage is at git.redrise.ru, which the README presents first. GitHub is described as the mirror, the issue tracker, and the place to send pull requests. And nightly builds are published at redrise.ru, with a build service whose status badge points at ci.redrise.ru.

Read together, that says the canonical repository is a self-hosted forge, GitHub is a convenience mirror that also happens to be where users report issues, and the build output comes from the maintainer's own infrastructure. The split has a practical consequence: the code you read on GitHub is a copy, so if you need to be certain about the current state, the redrise repository is the one to check, and if you are sending a pull request you are sending it to the mirror and relying on the maintainer to reconcile it.

The CI configuration supports that reading. The top level contains a `.drone.yml` for Drone, a `.woodpecker/` directory for Woodpecker, and a self-hosted CI status badge, which is consistent with builds running on the maintainer's own server rather than on a hosted service. `pom.xml` at the top level identifies the build tool as Maven, and `src/`, `misc/`, `screenshots/` and a `BUILD.md` round out a Java project layout. One oddity worth noting for anyone browsing: a directory called `JNI sources` with a space in the name sits at the top level, which will cause trouble in shell scripts and in any tooling that assumes path components are space-free.

The distribution story is broader than the jar. A Repology badge shows the project tracked as `tiny-repos/ns-usbloader`, so it is packaged by at least one Linux distribution, and the README credits Angelo Elias Dalzotto with maintaining packages in the AUR. If your distribution already ships it, that is a better upgrade path than a downloaded jar.

The permissions question, the mobile sibling, and the legal ground

Three things an adopter should weigh that the README treats lightly.

The first is the device permissions, covered above and repeated here because it is the part of the setup most likely to be applied without thought. The documented rule is world read and write on the device node. If your machine has other accounts, that is a wider grant than the task requires, and udev's group mechanism exists for exactly this case.

The second is scope. A file splitter is in this application, and there is a separate Android project, `ns-usbloader-mobile`, linked from the README, which is a different codebase with its own maintenance cycle. If you are evaluating the desktop tool for the file utility alone, note that the project you are installing is a Switch homebrew utility that also expects to talk to a console over USB, and the mobile variant may serve you better if you only want the network install path.

The third is not technical and the README does not raise it. This software exists to install packages to a modified Nintendo Switch. That console's firmware is designed to detect and refuse such modification, the modification voids the console's warranty, and using it is outside Nintendo's terms of service. Separately, the NSP format is used for both legitimately installed content and for game dumps obtained outside official channels, and the legality of the specific content you transfer is a question about that content rather than about this tool. Nothing here provides legal advice, and the practical point for an engineer evaluating the project is that the surrounding ecosystem carries obligations that the software licence does not address. The GPL-3.0 grant, or at your option any later version, covers the code and its use inside those boundaries.

GPL-3.0, a release every year or so, and an active repository behind it

The licence is the GNU General Public License version 3, or at your option any later version, which is the standard GPL-3.0-or-later grant with a copyright holder to identify. That permits redistribution and modification, including commercially, on the condition that derived work carries the same licence and source. This is a reading of the licence rather than legal advice.

The release history is slower than the commit history, and the two together tell the story. Version 7.1 was published on 2023-12-26, version 7.2 on 2024-10-30, and version 7.3 on 2025-12-31. That is roughly annual, with the most recent tag just under a year old at the point of this writing, and the integer major version has been at 7 for several years, so releases are being made deliberately rather than continuously.

The repository itself is more active than that cadence suggests. The last push was on 2026-09-19 and the project is not archived, so there is work landing between releases. For a desktop utility that talks to hardware, that is a healthy pattern: continuous maintenance with a release when something is ready, rather than a tag per commit. It does mean that the version you get from a download is not necessarily the version in the source tree, so if you are tracking a bug, check which commit a release corresponds to rather than assuming the newest code is what shipped.

The contributor list in the README is also a signal about the project's shape. It names translators for twenty languages including French, Italian, Korean, Portuguese, Spanish, Simplified and Traditional Chinese, German, Vietnamese, Czech, Arabic, Romanian, Swedish, Japanese, Ryukyuan, Turkish, Serbian and Catalan, and it credits specific technical contributions such as the split algorithms, which the README attributes to an unrelated patch creator project. A localisation effort that size means the interface is translated by people who use it, and it also means a translated string can lag behind an English change.

Editorial conclusion

Use NS-USBloader if you want a graphical installer and payload sender rather than the Python scripts it replaces, and pick the build that matches your platform: the -m1.jar on Apple Silicon, the plain jar elsewhere. Do not follow the README's udev example without reading it, because the rule it documents grants mode 0666 on the device node to every local user, which is broader than most desktops need. Verify first by checking the canonical repository at git.redrise.ru rather than the GitHub mirror, confirming your JDK against the platform section that applies to you, and reading the Goldleaf compatibility table, which lists specific Goldleaf versions as unsupported.

Frequently asked questions

Official sources

1. developersu/ns-usbloader on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases