Ninfs 3DS

Ninfs
Ninfs
General
Author	ihaveamac
Type	File Operation
Version	2.0
License	MIT License
Last Updated	2024/02/25
Links
	Download
	Website
	Source
	Support Author

ninfs (formerly fuse-3ds) is a FUSE program to extract data from Nintendo game consoles. It works by presenting a virtual filesystem with the contents of your games, NAND, or SD card contents, and you can browse and copy out just the files that you need.

Requires Python 3.8.0+. Supports Windows (recommended 10 or later), macOS, and Linux.

Features

Mount a NAND backup and browse CTRNAND, TWLNAND, and others, and write back to them without having to extract and decrypt them first.
Browse decrypted SD card contents. Dump installed games and saves, or copy contents between two system's SD contents.
Extract a game's files out of a CIA, CCI (".3ds"), NCCH, RomFS, raw CDN contents, just by mounting them and browsing its files. Or use the virtual decrypted file and start playing the game in Citra right away.

Installation

Initial setup

For 3DS types, the ARM9 bootROM is required. You can dump it using boot9strap (hold Start+Select+X on boot), which can be set up by 3DS Hacks Guide. It is checked in order of:

--boot9 argument (if set)
BOOT9_PATH environment variable (if set)
%APPDATA%\3ds\boot9.bin (Windows-specific)
~/Library/Application Support/3ds/boot9.bin (macOS-specific)
~/.3ds/boot9.bin
~/3ds/boot9.bin

Notes:

boot9_prot.bin can also be used in all of these locations.
"~" means the user's home directory.
"~/3ds" would mean /Users/username/3ds on macOS and C:\Users\username\3ds on Windows.

CDN, CIA, and NCCH mounting may need SeedDB for mounting NCCH containers of newer games (2015+) that use seeds. SeedDB is checked in order of:

--seeddb argument (if set)
SEEDDB_PATH environment variable (if set)
%APPDATA%\3ds\seeddb.bin (Windows-specific)
~/Library/Application Support/3ds/seeddb.bin (macOS-specific)
~/.3ds/seeddb.bin
~/3ds/seeddb.bin

How to install

User guide

Supported file types

Nintendo 3DS:

CTR Cart Image - .3ds, .cci.
CDN contents - cetk, tmd, and contents.
CTR Importable Archive - .cia.
Executable Filesystem - .exefs, exefs.bin.
Nintendo 3DS NAND backup - nand.bin.
NCCH - .cxi, .cfa, .ncch, .app.
Read-only Filesystem - .romfs, romfs.bin.
SD Card Contents - Nintendo 3DS from SD.
Installed SD Title Contents - *.tmd and *.app files.
3DSX Homebrew - .3dsx.

Nintendo DS/DSi:

Nintendo DSi NAND backup - nand_dsi.bin.
Nintendo DS ROM image - .nds, .srl.

iQue Player:

iQue Player NAND backup (read-only) - nand.bin.

Nintendo Switch:

Nintendo Switch NAND backup - rawnand.bin.

Graphical user interface

A GUI can be used by specifying the type to be gui. It controls mounting and unmounting. Examples:

Windows - py -3 -mninfs gui
*nix - python3 -mninfs gui.

Command line

Mounting:

Run a mount script by using "mount_<type>" (e.g. mount_cci game.3ds mountpoint).
Use -h to view arguments for a script.
If it doesn't work, the other way is to use <python-cmd> -mninfs <type>. Examples:
- Windows - py -3 -mninfs cci game.3ds mountpoint
- *nix - python3 -mninfs cci game.3ds mountpoint
Windows users can use a drive letter like F: as a mountpoint. Or use * and a drive letter will be automatically chosen.
Developer-unit contents are encrypted with different keys, which can be used with --dev with CCI, CDN, CIA, NANDCTR, NCCH, and SD.

Unmounting:

Windows - Press Ctrl+C in the command prompt/PowerShell window.
Linux - Run from terminal fusermount -u /path/to/mount
macOS (two methods):
- Right-click on the mount and choose "Eject "drive name"".
- Run from terminal diskutil unmount /path/to/mount

Examples

# 3DS game card dump.
mount_cci game.3ds mountpoint

# Contents downloaded from CDN.
mount_cdn cdn_directory mountpoint

# CDN contents with a specific decrypted titlekey.
mount_cdn --dec-key 3E3E6769742E696F2F76416A65423C3C cdn_directory mountpoint
 
# CIA.
mount_cia game.cia mountpoint

# ExeFS.
mount_exefs exefs.bin mountpoint

# 3DS NAND backup with essential.exefs embedded.
mount_nandctr nand.bin mountpoint

# 3DS NAND backup with an OTP file (Counter is automatically generated).
mount_nandctr --otp otp.bin nand.bin mountpoint

# 3DS NAND backup with OTP and CID files.
mount_nandctr --otp otp.bin --cid nand_cid.bin nand.bin mountpoint

# 3DS NAND backup with OTP file and a CID hexstring.
mount_nandctr --otp otp.bin --cid 7468616E6B7334636865636B696E6721 nand.bin mountpoint

# DSi NAND backup (Counter is automatically generated).
mount_nandtwl --console-id 5345445543454D45 nand_dsi.bin mountpoint

# DSi NAND backup with a Console ID hexstring and specified CID hexstring.
mount_nandtwl --console-id 5345445543454D45 --cid 576879446F657344536945786973743F nand_dsi.bin mountpoint

# DSi NAND backup with a Console ID file and specified CID file.
mount_nandtwl --console-id ConsoleID.bin --cid CID.bin nand_dsi.bin mountpoint

# iQue Player NAND backup.
mount_nandbb nand.bin mountpoint

# Switch NAND backup.
mount_nandhac --keys prod.keys rawnand.bin mountpoint

# Switch NAND backup in multiple parts.
mount_nandhac --keys prod.keys -S rawnand.bin.00 mountpoint

# Switch NAND encrypted partition dump.
mount_nandhac --keys prod.keys --partition SYSTEM SYSTEM.bin mountpoint

# NCCH container (.app, .cxi, .cfa, .ncch).
mount_ncch content.cxi mountpoint

# RomFS.
mount_romfs romfs.bin mountpoint

# Nintendo 3DS directory from an SD card.
mount_sd --movable movable.sed "/path/to/Nintendo 3DS" mountpoint

# Nintendo 3DS directory from an SD card with an SD key hexstring.
mount_sd --sd-key 504C415900000000504F4B454D4F4E21 "/path/to/Nintendo 3DS" mountpoint

# Nintendo DS ROM image (NDS/SRL, mount_nds also works).
mount_srl game.nds mountpoint
 
# 3DSX homebrew application.
mount_threedsx boot.3dsx mountpoint

Useful tools

wwylele's 3ds-save-tool can be used to extract game saves and extra data (DISA and DIFF, respectively).
wwylele's save3ds is a tool to interact with 3DS save files and extdata. Extracting and importing works on all platforms. The FUSE part only works on macOS and Linux.
OSFMount for Windows can mount FAT12/FAT16/FAT32 partitions in NAND backups.

Related tools

roothorick's BUSEHAC is a Linux driver for encrypted Nintendo Switch NANDs.
Maschell's fuse-wiiu can be used to mount Wii U contents.
koolkdev's wfslib has wfs-fuse to mount the Wii U mlc dumps and usb devices.

Screenshots

Media

fuse-3ds demonstration with Pokémon Ultra Moon (ihaveamac)

Changelog

v2.0

Fix corruption with New 3DS CTRNAND.
- This mainly affected standalone builds. Other installation methods that didn't use pyctr 0.7.3 were not affected.

v2.0a11

Accept non-ASCII game titles for SRL/NDS (some homebrew applications do this).
Windows Installer: update pre-included WinFsp.
- The installer does not update WinFsp for you, if you want to update it, you must do it separately.
Linux: creating desktop entry now includes the full path to the python3 executable.
Python 3.8 or later is required, this does not affect standalone builds.
Update pyctr requirement to 0.7.x (standalone builds use 0.7.3).
- RomFS performance is improved, especially for titles that contain a large amount of files or directories.
- Fix setting TWLNAND keys for devunit NANDs.
- For other changes related to pyctr 0.7.x: https://github.com/ihaveamac/pyctr/blob/0.7/CHANGELOG.md
Other various internal changes.

v2.0a10

Windows/GUI: Fix tkinter failing to find tcl/tk when installed in paths that contain non-Latin characters.
nandhac: Fix problems loading multipart images on Linux when the mount process is not in the foreground.
macOS: Try to load fuse-t if macFUSE can't be found (#103).
fuse-t is an alternative to macFUSE that doesn't depend on a kernel extension, making it easier to install on modern macOS. It should work just as well but please file issues.
macOS: Only display filename in volume name and not the containing directory for mounts that do this.

v2.0a9

Mac application is now signed and notarized by Apple.
Fix not showing all drive letters in the Windows GUI mount, only A and B.
Always set write bit in mounts (except SD).
This makes it easier to deal with files that have been copied out of the mount, since chmod won't be required to set the write bit.
Include Internet Access Policy for Little Snitch.
Fix DMG build not properly copying the application.
Update WinFSP url.

Credits

ninfs is under the MIT license. fuse.py is under the ISC license (taken from setup.py).

Special thanks to @Jhynjhiruu for adding support for iQue Player NAND backups.

Special thanks to @Stary2001 for help with NAND crypto (especially TWL), and @d0k3 for SD crypto.

OTP code is from Stary2001/3ds_tools, and is under the MIT license.

External links