Mario Kart World (Nintendo Switch 2) recompiled to run natively on Linux and Windows.
Releases · Help wiki · Discord · Changelog · Contributing · Sources · Roadmap · Performance · Issues · Discussions · Archive
English · 简体中文 · Español · العربية · हिन्दी · Português (Brasil) · Português (Portugal) · Deutsch
Mario Kart World (Switch 2, versions 1.0.0 and 1.8.0) turned into a native program for Linux and Windows. You need your own copy of the game, dumped from your own console: nothing of the game is in this repository or its releases.
It is a recompilation, not an emulator. The game's AArch64 code is translated to C ahead of time and compiled for your CPU (x86-64, or AArch64 on Linux); there is no CPU interpreter or JIT. The GPU is not emulated either: NVN2, the Switch 2 graphics API, runs on top of Vulkan, and the game's shaders are translated to SPIR-V ahead of time.
Early, and moving fast (12/11/2026):
- It boots, plays the intro movies, goes through the menus and races, on Linux and Windows (x86-64) and on Linux AArch64 (its own AppImage, tested on an Adreno 740 handheld).
- The start screen sets the game up from your copy on your machine and holds every setting.
- Races run at 60 fps on high-end GPUs and at 30 on mid-range ones. Measured frame times per GPU: docs/project/performance.md.
- Known problems: a few menus (mode, character and vehicle select) need work, the kart's shadow misses a frame now and then, some audio cuts during movies, and on some AMD drivers the GPU can hang. There is no online play.
The open work, in order (details: docs/project/roadmap.md):
- 60 fps in races: recording the game's frame for Vulkan is on the critical path, so it needs less CPU.
- The picture as on the console: the last shader bugs and the kart's shadow.
- Every menu checked against the console.
- No GPU hangs, less GPU memory, loading without stutter, a Linux package for non-rolling distributions.
- 1.8.0 on par with 1.0.0: ultrawide, shadow map size, fixed seed (#19).
Stuck? Search the wiki first: installation, settings, controls, known errors by their log line and a FAQ.
- Dump Mario Kart World 1.0.0 or 1.8.0 from your Switch 2 (
exefs/andromfs/, decrypted; 1.8.0 with the update merged into the base RomFS), or the same dump packed as one.nupor.nxfile. - Download the launcher from Releases: the
.AppImageon Linux (-aarch64on ARM; glibc 2.31 or newer: Debian 11, Ubuntu 20.04, SteamOS and later) or the.zipon Windows, unpacked into a folder. About 30 GB free. - Run it (
chmod +xthe AppImage first), open Game files, optionally Choose game folder (default on Linux:~/.local/share/mkw-recomp), point it at your dump and press Set up. The first setup takes a while: it compiles the whole game and downloads NVIDIA'snvdisasmandptxas(84 MB on Linux, 126 MB on Windows). Then Play. - New releases are offered on the start screen (Update to vX); Settings → Menu → Check for updates turns that off.
Requirements: x86-64 CPU with AVX2 (or, on Linux, AArch64 with ARMv8.2: LSE, FP16, RCpc, DotProd, CRC32), a GPU with
Vulkan 1.3 (VK_EXT_mesh_shader recommended), 16 GB of RAM recommended. In a Docker or Podman container on Linux,
allow userfaultfd in the seccomp profile (Docker's default refuses it), or it runs several times slower.
To add your machine to the performance list, open a performance report.
Beyond the console, all optional and off (or at the console's value) by default:
- Display: any internal resolution, 21:9 / 32:9 / 48:9, AMD FSR 1 scaling, HDR, VSync, mailbox or immediate presentation.
- Frame generation: frames made between the game's (30 fps shown at 60, or 240). Smoother, not faster; fast motion and the minimap can smear.
- Frame rate: 20 and 15 fps besides 60 and 30; Automatic drops to them when frames take too long, so a slow GPU keeps the race at real speed. Low latency (on by default) starts each frame as late as the GPU allows.
- Graphics: texture filtering and quality, detail distance, shadow quality.
- Sound: 5.1 surround.
- Controls: every key and button rebindable, mouse camera, Nintendo, Xbox or PlayStation icons, motion steering,
vibration, local multiplayer with one controller each. Switch 2 controllers work over Bluetooth and, on Linux, USB
(Windows USB: see below). Gyro from a Cemuhook / DSU server (DS4Windows, BetterJoy) is supported. Racing wheels
work as a controller (steering and first buttons); for pedals, put a
gamecontrollerdb.txtin the game folder. - Hacks: turbo (F2), skip movies, unlock everything, fixed randomness, straight to time trial or free roam.
- Languages: menus in 20 languages; the game also in Catalan, Galician, Basque and Turkish.
- Tools: performance overlay and a one-click system info for bug reports.
They only start after a command sent to their second USB interface, which Windows leaves without a usable driver. Once per controller, with Zadig:
- Plug the controller in and open Zadig.
- Options → List All Devices, pick the controller's Interface 1 (USB ID
057Eand2069Pro Controller,2066/2067right/left Joy-Con,2073GameCube). Not Interface 0: replacing it hides the controller from other apps. - Driver WinUSB, then Replace Driver.
The same applies to a virtual controller with those IDs (Switch2Connect's USB/IP mode). To undo it, uninstall that interface's device in Device Manager with "delete the driver" ticked.
The start screen's Mods page has two tabs:
- Find on GameBanana: Mario Kart World's mods on GameBanana, with author, license, screenshots and description. Install downloads only when you ask.
- Installed: each mod with an on/off switch; Import zip / Import folder takes a mod you already have (
.zip,.raror.7zwithromfs/,exefs/and/orplugin/inside).
Mods that replace game files (romfs/) apply at the next start. Mods that patch the game's code (exefs/ .ips or
.pchtxt, such as 200cc or 30 FPS) rebuild the game before you play (a few minutes). Two mods that change the same
file: the page asks which one wins. It also warns about mods that replace graphics settings or shaders.
A mod with a plugin/ folder carries a native plugin (.dll or .so) that runs its own program on your computer:
turn it on only if you trust its source. For modders, the API is one header,
runtime/plugin/mkw_plugin.h, explained in the wiki's
Writing a plugin; more in the wiki's
Mods page.
Mods are made by others and not tested here: one can crash the game or damage your save. Keep a copy of your save, report a mod's problems to its author, and when you report a bug here say which mods were on (the log lists them).
Linux, with uv, clang, lld, ninja, SDL3, Opus, libvpx, zstd, xxHash, the Vulkan headers and VMA 3.4.0 (details in
tools/build/README.md). Put your dump in game/ (game/exefs, game/romfs) or set
MKW_GAME=<dir>, then from the repo root:
uv run python recomp/gen.py --exefs game/exefs --jobs 8 # --out/--patches default to the dump's version (1.8.0: build/generated-180)
uv run tools/shaders/extract.py && uv run tools/shaders/translate.py
uv run tools/build/build.py # build/mkw; --target windows builds mkw.exe with llvm-mingw (windeps.py)
build/mkwShortcuts: make build, make appimage (make help lists them all). On Windows itself, from a packed dump, or on
AArch64: see tools/build/README.md. Translating the shaders needs the SM86 encoding
specification, generated from NVIDIA's nvdisasm (not shipped): tools/shaders/README.md.
Everything generated goes to build/, never to git.
| Folder | Contents |
|---|---|
| recomp/ | The generator: AArch64 → C |
| runtime/ | What plays the console: kernel, memory, SDK replacements, NVN2 over Vulkan, audio, input, menus, launcher |
| sm86/ | The shader translator: SM86 SASS → GLSL → SPIR-V |
| i18n/ | Menu, start screen and setup texts in every language (gettext .po) |
| tools/ | Analysis, setup, build, game runs, diagnostics |
| tests/ | Tests without the game or a GPU, run in the CI on Linux and Windows |
| docs/ | Research, sources, performance |
.github/ |
CI, issue and pull request templates |
At the root: pyproject.toml and uv.lock (the tools' Python environment), .gitignore, .gitattributes
(merge=union for the lists every PR appends to), LICENSE, CONTRIBUTING.md, CHANGELOG.md, AGENTS.md (guide for
coding agents) and Makefile.
| Topic | Decision | Why |
|---|---|---|
| CPU | AArch64→C lifter based on totk-pc-recomp's (MIT), extended to ARMv8.1-8.3 (LSE atomics, CAS, LDAPR; PAC as identity, MTE tags as 0) | Same engine family, already scales to a large executable |
| System | The SDK's nn::* functions replaced by name, signatures from the mangled names of main's 1 289 imports |
No console services to emulate |
| Graphics | NVN2 over Vulkan: 529 of its 699 functions share their name with NVN1; 170 are new | Recompilation, not GPU emulation |
| Shaders | Our own SM86→SPIR-V translator, offline, with a decoder generated from the DocumentSASS / nvsass-disassembler specification | Covers mesh/task and what Maxwell lacks |
| Switch 2 extras | HDR automatic when the display is HDR (Settings > Screen > HDR); DLSS, ray tracing and touch off by default, their NVN2 functions exist but do nothing | Console hardware extras, not needed to play |
| Defaults | The console's look and resolution; lower settings are options | The player chooses |
Written with Claude (Anthropic's coding agent) doing most of the typing, under my direction, in about ten days of full-time work (489 commits from 30/10/2026), each reviewed, measured or tested before it went in.
- Method more than prompts. Performance changes are measured with an A/B inside the same run (two runs of the same build differ by up to 12 ms per frame); rendering fixes are checked against the console's own image; the shader translator is tested off the GPU on all 11 561 programs; frame captures replay the back end in seconds. Rules that came out of mistakes are written down and enforced by scripts.
- Earlier work. totk-pc-recomp and its Linux port, my earlier recomps (SavageWindRecomp, smo-recomp), and maintaining AnyPS5 (faithful shader translation, mesh shaders as compute).
- Community research. eden-nx2's Switch 2 notes, NVIDIA's SASS encoding as documented by DocumentSASS and nvsass-disassembler, Ryujinx and Mesa NAK for shader semantics, and the other Switch 2 ports in the sources.
MIT License. Code taken from other projects keeps its own license next to it (LICENSE.* files in
recomp/, runtime/, sm86/decode/ and
runtime/third_party/): totk-pc-recomp, nvsass-disassembler, Dear ImGui, bc7enc,
stb_image, AMD FidelityFX FSR 1 and Roboto. Every source, with its license and what was taken (code from MIT projects
only; from GPL projects, ideas only): docs/project/research.md.
Mario Kart World is © Nintendo. This project is not affiliated with or endorsed by Nintendo, contains no game code or assets, and does not help to obtain them.
Mods belong to their authors and their own licenses. This project is not affiliated with GameBanana or any mod's author, does not host, review or distribute mods, and is not responsible for what a mod does: the start screen only shows GameBanana's public listing and downloads a mod from there when you ask.
See CONTRIBUTING.md. Bugs and performance reports go to Issues, questions to Discussions.

