Linux and macOS

SimpleXisoDrive mounts Xbox ISO/XISO/CISO/CHD images and ZArchive files as read-only directories on Linux and macOS using FUSE 3 through the LibFuseSharp mount library.

Prerequisites

Platform	Requirement
Both	.NET 10.0 Runtime (the base runtime).
Linux	FUSE 3: the `libfuse3` library and the `fuse3` tools (`fusermount3`).
macOS	macFUSE. macOS 15.4+ can use its FSKit backend, which needs no kernel extension.

Install FUSE 3 with your distribution’s package manager:

# Debian / Ubuntu
sudo apt install libfuse3-3 fuse3

# Fedora
sudo dnf install fuse3 fuse3-libs

# Arch
sudo pacman -S fuse3

Verify that the kernel device exists:

ls -l /dev/fuse

If it is missing, load the module with sudo modprobe fuse.

The application searches for the FUSE library in the standard locations. Set LIBFUSESHARP_LIBRARY to an explicit path if it lives somewhere else (the old SIMPLEXISODRIVE_FUSE_LIBRARY name is still accepted).

Usage

SimpleXisoDrive <image-file> [mount-path] [options]

<image-file> — path to the .iso, .xiso, .cso, .chd or .zar file. A directory containing exactly one image, or a path without an extension, is also resolved.
<mount-path> — an existing empty directory. When omitted, the application creates a temporary directory, prints it after mounting, and removes it again on unmount.
-l, --launch — open the file manager (xdg-open or open) at the mount point.
-d, --debug — show verbose FUSE debug output.
-i, --image-iso — also expose the raw Xbox image as image.iso at the mount root.
-h, --help — print the usage text and exit with code 0 without a network call.

Example:

mkdir -p ~/mnt/halo
SimpleXisoDrive ~/Games/Halo.iso ~/mnt/halo
ls ~/mnt/halo

To mount an Xbox ISO stored as CHD and expose the decompressed disc image for an emulator:

SimpleXisoDrive ~/Games/Halo.chd ~/mnt/halo --image-iso
# The emulator can open ~/mnt/halo/image.iso

To mount a ZArchive and expose the synthesized disc image for an emulator:

SimpleXisoDrive ~/Games/Halo.zar ~/mnt/halo --image-iso
# The emulator can open ~/mnt/halo/image.iso

Unmounting

Use any of the following:

Press Ctrl+C in the terminal running SimpleXisoDrive.
Run fusermount3 -u <mount-path> on Linux.
Run umount <mount-path> on macOS.

SIGTERM and SIGHUP also trigger a clean unmount.

Platform notes

The volume is mounted read-only. open rejects write access and macOS setattr returns EROFS.
Files are exposed with read permissions for everyone (0444 for files, 0555 for directories). Timestamps are taken from the image descriptor; ZArchive trees use the .zar file’s last-write time.
The volume label is exposed through the mount options: fsname on Linux and volname on macOS (the label is sanitized automatically, falling back to the application name when the volume has none).
Linux mounts are performed through fusermount3, so unprivileged users can mount without sudo.
macOS may quarantine a downloaded binary. If it refuses to start, remove the attribute:
```
xattr -d com.apple.quarantine SimpleXisoDrive
```

Troubleshooting

Symptom	Cause / fix
`libfuse3 was not found`	Install the FUSE 3 package for your distribution (see above).
`/dev/fuse was not found`	Load the FUSE kernel module: `sudo modprobe fuse`.
`fusermount3 was not found on PATH`	Install the `fuse3` tools package.
`macFUSE (libfuse3) was not found`	Install macFUSE from https://macfuse.io and allow the system extension.
Mount succeeds but the directory is empty	The image may be invalid; check the console/log output.
`fuse: mountpoint is not empty`	Use an empty directory as the mount point.