Skip to content

README.md

Latest commit

 

History

History
180 lines (127 loc) · 8.39 KB

README.md

File metadata and controls

180 lines (127 loc) · 8.39 KB
Raw
fuse-ext2 — read ext2/ext3/ext4 drives on macOS

Latest release License: GPL-2.0 Platform: macOS (Apple Silicon | Intel) Install: Homebrew tap Sponsor

Mount ext2 / ext3 / ext4 filesystems on macOS (Apple Silicon and Intel), read-only, using macFUSE.

This is a maintained fork of alperakcan/fuse-ext2 with the fixes needed to build and mount on current macOS, where the original no longer compiles and the Homebrew formula has been removed.

Read-only is the intended, supported mode — ideal for pulling data off a Linux drive from a Mac.

Does it work for you?

Works for me Having issues

Both buttons take you to the community feedback issue, where you react 👍 or 👎 with your GitHub account — one of each per person, counted live above. If something's broken, react 👎 and file a bug report so it can actually get fixed; once a linked bug is closed, we'll ask you there to revisit and update your reaction if it's resolved.

Companion tools

  • fuse-watchdog — an optional, external recovery watchdog that auto-remounts a fuse-ext2 mount if the backing USB device drops off the bus (ENXIO / "Device not configured"). It re-verifies the ext4 UUID before remounting, so it can never attach the wrong disk. Built specifically as a workaround for a flaky USB dock; not needed with reliable hardware — the real fix for a dropping dock is a better enclosure (UASP/ASMedia or Thunderbolt).

Requirements

macFUSE provides FUSE on macOS:

brew install --cask macfuse

macFUSE is a kernel extension, so installing it is not enough — you have to enable it:

  1. Open System Settings → Privacy & Security, find the blocked "system software from developer Benjamin Fleischer" notice, and click Allow.
  2. Restart your Mac. The extension only loads after a reboot.

On Apple Silicon, loading any third-party kernel extension the first time also requires lowering the security policy:

  1. Shut down, then hold the power button until "Loading startup options" appears → Options → Continue (this is Recovery mode).
  2. Menu bar Utilities → Startup Security Utility, select your disk → Security Policy…
  3. Choose Reduced Security and tick "Allow user management of kernel extensions from identified developers."
  4. Restart, then do the Allow + reboot steps above.

See macFUSE's documentation if the extension still won't load.

Install

Homebrew (recommended)

brew install moonsoup/fuse-ext2/fuse-ext2

From source

# build dependencies
brew install autoconf automake libtool pkg-config e2fsprogs

git clone https://github.com/moonsoup/fuse-ext2
cd fuse-ext2
./autogen.sh

E2P="$(brew --prefix e2fsprogs)"
export LIBTOOLIZE=glibtoolize
export CPPFLAGS="-I/usr/local/include -I/usr/local/include/fuse -I${E2P}/include"
export LDFLAGS="-L/usr/local/lib -L${E2P}/lib -F/Library/Filesystems/macfuse.fs/Contents/Frameworks"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:${E2P}/lib/pkgconfig"
./configure

make -C fuse-ext2 fuse-ext2      # the driver binary
sudo cp fuse-ext2/fuse-ext2 /usr/local/bin/

Usage

The easy way — fuse-ext2-mount

Installing via Homebrew also gives you a fuse-ext2-mount helper that handles sudo, the right options, and the prerequisite checks for you:

fuse-ext2-mount                           # list ext partitions on attached drives
fuse-ext2-mount /dev/disk4s3              # mount read-only at /tmp/ext-disk4s3
fuse-ext2-mount /dev/disk4s3 --recovered  # drive from another machine (foreign UIDs)
sudo umount /tmp/ext-disk4s3              # unmount when done

Add --dry-run to any command to see exactly what it will run.

Manually

Find the ext partition (diskutil list — look for Linux Filesystem; macOS can't read ext, so it won't auto-mount, which is expected). Reading a raw device requires root, so use sudo:

mkdir -p /tmp/ext
sudo fuse-ext2 /dev/disk4s3 /tmp/ext -o ro,allow_other
# ... browse /tmp/ext ...
sudo umount /tmp/ext

allow_other lets your normal account see the files even though root mounted it. For a drive recovered from another machine, add no_default_permissions so files owned by a UID that doesn't exist here stay readable:

sudo fuse-ext2 /dev/disk4s3 /tmp/ext -o ro,allow_other,no_default_permissions

Mounting automatically at boot

The Full Disk Access requirement above only applies to running sudo fuse-ext2 … interactively from a terminal app — macOS's TCC attributes that raw-device open to the terminal app, not to sudo or the binary. A root LaunchDaemon started directly by launchd at boot never goes through that path at all: raw device access for a root process is governed by ordinary BSD device permissions, not TCC. So the way to get a password-free, no-Full-Disk-Access auto-mount at boot is a LaunchDaemon, not a Full Disk Access grant:

cp launchd/com.moonsoup.fuse-ext2.plist /tmp/   # edit the device/mount paths first if yours differ
sudo cp /tmp/com.moonsoup.fuse-ext2.plist /Library/LaunchDaemons/
sudo launchctl load /Library/LaunchDaemons/com.moonsoup.fuse-ext2.plist

This mounts once at boot (RunAtLoad) and deliberately does not restart itself if the device later drops off the bus (KeepAlive is off) — blindly restarting the plain mount command against a dropped device would just crash-loop uselessly. Recovering an actual drop — kill stale daemon, release, verify the ext4 UUID, remount — is fuse-watchdog's job specifically; install that too if your enclosure needs it.

Troubleshooting

  • "Operation not permitted" / can't open the device — grant your terminal Full Disk Access (System Settings → Privacy & Security → Full Disk Access), then try the sudo fuse-ext2 … command again. (Not needed for the boot-time LaunchDaemon above — see that section.)
  • "the file system is not available" / nothing mounts — macFUSE isn't loaded. Re-check the enablement steps under Requirements (approve the extension, reboot; on Apple Silicon, the Recovery-mode security policy).

What this fork changes

  • Builds on current macOS — adapts the getxattr operation to the Darwin signature (offered upstream as #154).
  • no_default_permissions option — read files owned by a foreign UID (recovered drives) without mounting as root (offered upstream as #155).
  • Read-only mount verified on ext2, ext3, and ext4.

Support

Keeping ext2/3/4 access working on macOS takes ongoing effort as each release changes the ground under it. If this saved you — or your data — please consider sponsoring the work. 💛

License

GPL-2.0, same as upstream. See COPYING.

Original work by Alper Akcan and contributors. This fork exists to keep it usable on modern macOS.