FUSE filesystem Python scripts for Nintendo console files
Project description
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.
Windows, macOS, and Linux are supported.
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)
- 3DSX Homebrew (".3dsx")
- Nintendo DS / DSi
- Nintendo DSi NAND backup ("nand_dsi.bin")
- Nintendo DS ROM image (".nds", ".srl")
- 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 Citra 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 the bootROM, hold START+SELECT+X when you boot up your 3DS. 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
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.6.1+ and pycryptodomex are required. PySide2 is required for the GUI.
Windows
Windows 7 or later is required.
(GUI in progress of being re-created.) Python does not have to be installed, but WinFsp is still required.
Install with existing Python
- Install the latest version of Python 3. The x86-64 version is preferred on 64-bit Windows.
- Alternatively, use Python 3.7 from the Microsoft Store. Note that
python
orpython3
must be used, notpy -3
.
- Alternatively, use Python 3.7 from the Microsoft Store. Note that
- Install the latest version of WinFsp.
- Install ninfs with
py -3 -m pip install --upgrade https://github.com/ihaveamac/ninfs/archive/2.0.zip
.- With GUI support:
py -3 -m pip install --upgrade https://github.com/ihaveamac/ninfs/archive/2.0.zip#egg=ninfs[gui]
- With GUI support:
macOS
(GUI in progress of being re-created.) Python does not have to be installed, but FUSE for macOS is still required.
Install with existing Python
Versions of macOS supported by Apple are highly recommended. OS X Mavericks is the oldest version that should work.
- Install the latest version of Python 3. The recommended way is Homebrew. You can also use an installer from python.org or a tool like pyenv.
- Install the latest version of FUSE for macOS.
- Install ninfs with
python3 -m pip install --upgrade https://github.com/ihaveamac/ninfs/archive/2.0.zip
.- With GUI support:
python3 -m pip install --upgrade https://github.com/ihaveamac/ninfs/archive/2.0.zip#egg=ninfs[gui]
- With GUI support:
Linux
Arch Linux
ninfs is available in the AUR: normal, with gui, git, git with gui
Other distributions
- Recent distributions (e.g. Ubuntu 18.04 and later) should have Python 3.6.1 or later pre-installed, or included in its repositories. If not, you can use an extra repository (e.g. deadsnakes's PPA for Ubuntu), build from source, or use a tool like pyenv.
- Most distributions should have libfuse enabled/installed by default. Use your package manager if it isn't.
- Some dependencies may need to be installed to build and install ninfs.
- On Debian-based systems,
g++
andpython3-dev
are required for the C extensions. To build and install as a package,python3-setuptools
andpython3-wheel
are required.
- On Debian-based systems,
- 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.- With GUI support:
python3 -m pip install --upgrade --user https://github.com/ihaveamac/ninfs/archive/2.0.zip#egg=ninfs[gui]
- 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
.
Usage
Graphical user interface
A GUI can be used, if ninfs was installed with GUI support, by specifying the type to be gui
(e.g. Windows: py -3 -mninfs gui
, *nix: 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
, *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.
- 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 4E696E74656E646F nand_dsi.bin mountpoint
- DSi NAND backup with a Console ID hexstring and specified CID hexstring:
mount_nandtwl --console-id 4E696E74656E646F --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
- 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
- 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 FUSE mount for 3DS save files. Currently only supports macOS and Linux.
- OSFMount for Windows can mount FAT12/FAT16 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.
License/Credits
ninfs
is under the MIT license.fuse.py
is under the ISC license (taken fromsetup.py
).hac/aes.cpp
andhac/aes.hpp
are from @openluopworld's aes_128 commitb5b7f55
, and uses the MIT License.hac/_crypto.cpp
AES-XTS part by @luigoalma, based on @plutooo's crypto module; Python module implementation initially by me(@ihaveamac).
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for ninfs-2.0a1-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e1b17b8979f073c0d505758062299dd27e3941a356f9d48502f4ed08ebd18a9b |
|
MD5 | e29a6c4be2f71ef066fdf4dc20135a67 |
|
BLAKE2b-256 | 016fc6293ecd42f0cf187ab6e347c8ab8ccb35580d9467bdd67c52fafcabaaf8 |
Hashes for ninfs-2.0a1-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4ace9787c6fa63b3c1f37ffae5c1a018e3fd96427efdfb0ead265e5c0d1db48d |
|
MD5 | c359f4fc283974074b078df0c15c922d |
|
BLAKE2b-256 | 22141e7fd2b300c6582f2cb125f1896e3aef7e3c3c2b60367715c3b93e5fb7ce |
Hashes for ninfs-2.0a1-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1fc2a9ffe6fda70f0e676cda6cbefdd739b7fe52fb6fa078c2f51b9591fc4c81 |
|
MD5 | e0e0347ef7a7a83c3e966530b2493d7a |
|
BLAKE2b-256 | 056db3fdec5db36902a4507d598f9b7170594da901f4e7c0123629d0305f89a3 |
Hashes for ninfs-2.0a1-cp37-cp37m-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 20723e08993dcef1af11401596961b04060fbb2d3cdd59620f99c7c82a4de111 |
|
MD5 | b8ba1e3ff0066ce1ba2db30216d5f339 |
|
BLAKE2b-256 | 22ee138cb5f1773f4ef6d89165c2b8535fc407994ec85b8adff84cc5c9892431 |
Hashes for ninfs-2.0a1-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 94e22658d078b4e791db0495d4d9121d134a20927dfe95b59e3ca2387fb7d4bf |
|
MD5 | 0ffd78f4960140343f86835c8d05a55b |
|
BLAKE2b-256 | 6e5e632130d4e4a30054c933d47d874eef788b67350fe63377793593de76fc6e |
Hashes for ninfs-2.0a1-cp36-cp36m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 32cb388aced426b4562b57a626313250aca2c2e50bbd59889653aa08fac02cf8 |
|
MD5 | 23010a9674a1204b213883c682ca4d91 |
|
BLAKE2b-256 | 967f3cd0b71c77af06311a7c24e9d523c03b93a3a0da096b15a228db5b8fb3b5 |
Hashes for ninfs-2.0a1-cp36-cp36m-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2b88abadd8123833dec11c66e149ab00f80c74c83639e84724ca28d22f015a85 |
|
MD5 | 5603aa44de465da8257faa12e1b67ed0 |
|
BLAKE2b-256 | 7573dc0488f50c02072b892583a18d579d7ddce7494791c8b8e5eced59d0e701 |
Hashes for ninfs-2.0a1-cp36-cp36m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 34f0dc9ee4862e9e48948d0e968484216dd2fe85060acddce70222b9dd60108c |
|
MD5 | 494b1b1db047e1d52cd9c6244217c687 |
|
BLAKE2b-256 | 7977f221e8a2ac71630ff0551d7529115fef9343ecd6cc61504bc88942a6edcb |