ninfs

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.

<p align="center"><img src="https://github.com/ihaveamac/ninfs/raw/2.0/resources/cia-mount-mac.png" width="1032"></p>

Supported 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")

Example uses

• 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 a 3DS emulator right away.

Setup

For 3DS types, The ARM9 BootROM is required. You can dump it using boot9strap, which can be set up by 3DS Hacks Guide. To dump Boot9, follow the steps on wiki.hacks.guide.

Boot9 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

For historical reasons, 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

Python 3.12 or later is required.

Windows

Windows 10 or 11 is recommended. Windows 8.1 is the minimum but untested. Windows 7 or earlier are unsupported.

Installer

An installer is provided in releases. It includes both ninfs and WinFsp, which is installed if required.

Standalone release

A standalone zip is also provided in releases. WinFsp must be installed separately.

Install with existing Python

• Install a version of Python 3.12 or later. The x86-64 version is preferred on 64-bit Windows.
  • Python from the Microsoft Store is not recommended due to sandboxing restrictioons.
• Install the latest version of WinFsp.
• Install ninfs with py -3 -m pip install --upgrade https://github.com/ihaveamac/ninfs/archive/2.0.zip

Windows on ARM

Official support for Windows on ARM will come eventually. In the meantime, running the x86 version has been tested and seems to work properly. Make sure to install the latest WinFSP version with ARM64 support.

macOS

Versions of macOS supported by Apple are highly recommended. macOS 12 Monterey is the oldest version that should work. macFUSE or fuse-t is required.

Standalone application

A standalone build is provided in releases. macFUSE or fuse-t must still be installed separately. Releases are built for Intel and Apple Silicon, signed and notarized by Apple.

Install with existing Python

• Install a version of Python 3.12 or later. Various methods to use Python:
  • Installers from python.org.
  • Xcode or Command Line Tools (note: has a broken GUI)
  • Homebrew
  • MacPorts
  • Nix
• Install the latest version of macFUSE or fuse-t.
• Install ninfs with python3 -m pip install --upgrade https://github.com/ihaveamac/ninfs/archive/2.0.zip

Linux

Arch Linux

ninfs is available in the AUR: normal, with gui, git, git with gui

Other distributions

• Recent distributions (e.g. Ubuntu 24.04 and later) should have Python 3.12 or later pre-installed, or included in its repositories. Refer to your distribution's documentation for details.
• Most distributions should have libfuse enabled/installed by default. Use your package manager if it isn't.
• Install ninfs with python3 -m pip install --upgrade --user https://github.com/ihaveamac/ninfs/archive/2.0.zip
  • --user is not needed if you are using a virtual environment.
• You can add a desktop entry with python3 -m ninfs --install-desktop-entry. If you want to install to a location other than the default ($XDG_DATA_HOME), you can add another argument with a path like /usr/local/share.
• To use the GUI, tkinter needs to be installed. On Debian-/Ubuntu-based systems this is python3-tk. On Fedora this is python3-tkinter.

Nix/NixOS

A nix derivation is provided, tested on NixOS, other Linux distributions, and macOS.

On macOS, macFUSE or fuse-t must be installed separately, as nixpkgs doesn't (and probably can't) package either.

With flakes to run the latest commit on main:

• Use GUI: nix run github:ihaveamac/ninfs
• Directly use mount (example with cia): nix run github:ihaveamac/ninfs -- cia game.cia mountpoint

Other operating systems

Anything else is untested and may not work properly. Bug reports and/or patches for support are welcome. (If you can, please check if the issue is with ninfs or mfusepy.)

ninfs is known not to work on FreeBSD: https://github.com/ihaveamac/ninfs/issues/107

Usage

Graphical user interface

A GUI can be used by specifying the type to be gui (e.g. Windows: py -3 -mninfs gui, Linux/macOS: python3 -mninfs gui). The GUI controls mounting and unmounting.

Command line

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> (e.g. Windows: py -3 -mninfs cci game.3ds mountpoint, Linux/macOS: 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. These are less tested and may have bugs due to unknown differences between retail and dev files.

Unmounting

• Windows: Press <kbd>Ctrl</kbd> + <kbd>C</kbd> in the command prompt/PowerShell window.
• macOS: Two methods:
  • Right-click on the mount and choose "Eject “drive name”".
  • Run from terminal: diskutil unmount /path/to/mount
• Linux: Run from terminal: fusermount -u /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