anylinuxfs

Full read-write access to ext4, btrfs, or any other Linux-supported filesystem on a Mac. Based on the libkrun microVM hypervisor and NFS — no kernel extensions, no lowering system security.

Installation

brew tap nohajc/anylinuxfs
brew trust nohajc/anylinuxfs
brew install anylinuxfs

Features

• mounts any filesystem supported by Linux (ext4, btrfs, xfs, … but also NTFS and exFAT)
• full read-write support — whatever Linux natively supports, anylinuxfs supports too
• mount any number of drives at the same time
• supports LUKS-encrypted drives
• supports BitLocker-encrypted drives – NTFS or FAT32 (using your recovery key as passphrase)
• supports LVM (even volume groups spanning multiple drives)
• supports LVM on LUKS (i.e. encrypted LVM)
• supports Linux RAID (mdadm) and multi-disk btrfs
• supports ZFS (including native ZFS encryption)
• works with both external and internal drives
• works with disk images (currently supported: raw, qcow2)
• supports disks with GPT, MBR or no partition table (single filesystem or LVM/LUKS container)
• NFS share by default only reachable from localhost but can be shared across network too
• define your own custom actions (e.g. mount borg backup located on a Linux drive)

Limitations

• Only Apple Silicon Macs are supported (libkrun limitation)
• A new virtual machine is needed for each mounted volume. You can configure RAM limit (512 MB by default), typical usage is around 256 MB per VM.
• Multi-mount relies on file locks (to prevent data corruption) and we can only lock entire physical partitions. That means you can only mount multiple logical volumes from the same partition if you mount all of them read-only.
• By design, any mounted volume is seen by macOS as a network drive shared by our virtual machine.
• Microsoft Word cannot edit files directly on a mounted drive. This is a known issue with Word and network filesystems.

Known issues

• Some disks with non-ASCII labels might fail to mount unless a custom mount point with “safe” characters is used (this is a macOS bug)
• When copying large number of files over an extended period of time, NTFS drives can throw I/O errors (retry usually fixes it). This only happens with the default ntfs-3g driver which misbehaves in combination with NFS (used for exposing the files to macOS). Instead, you can use ntfs3 driver which doesn’t have this issue. If you’re wondering why that one is not the default, it’s explained in NTFS notes below. There’s hope the situation might improve once yet another new NTFS driver lands in Linux kernel.

Demo

https://github.com/user-attachments/assets/6ec6ce46-ce08-45b9-9fa4-e3d6d078d811

Introduction

Mounting 3rd-party filesystems on macOS has always been tricky. There’s official support for reading NTFS but otherwise we’ve mainly used solutions based on macFUSE. We’ve got NTFS-3g which is a pretty mature driver but for Linux filesystems there’s only a couple of experimental solutions like fuse-ext2 or ext4fuse.

If you want a reliable solution with full write access, you need to run a Linux virtual machine with physical disk access and take care of exposing the mounted filesystem to the host. This is exactly what anylinuxfs does and it streamlines it so that it’s as easy as running one command in terminal.

You pick a drive, mount it with anylinuxfs and it appears as a NFS share on localhost. This spins up a microVM in the background which uses the real linux drivers, so you can access anything from ext* to btrfs. Any mount options on the command-line will be forwarded to the linux mount command, so you can mount read-only, read-write, pick btrfs subvolumes, etc. Then you simply eject the drive in Finder or use anylinuxfs unmount in terminal and the virtual machine will be turned off.

This all sounds like a lot of work but it’s actually very fast. Not like a traditional virtual machine which takes a while to boot. This one is just a stripped down version of Linux, there’s not even a UEFI firmware. Practically, it takes only a couple of seconds before the drive is mounted and ready to use.

Basic usage

Most often, you will probably use the following commands:

• anylinuxfs mount - mount a filesystem; this is the default command, so the mount keyword can be omitted
• anylinuxfs unmount - safe unmount, useful in case of multiple mounts (typically ZFS datasets) which need to be ejected in a particular order
• anylinuxfs list - show available filesystems (-m/-l shows Microsoft/Linux partitions only)
• anylinuxfs status - show what is currently mounted
• anylinuxfs log - show details about the current (or last) run, useful for troubleshooting
• anylinuxfs vm - open a shell or run a command inside the VM used for an active filesystem mount

Mounting filesystems

From anylinuxfs mount --help:

Usage: anylinuxfs [mount] [OPTIONS] [DISK_IDENT] [MOUNT_POINT]

Arguments:
  [DISK_IDENT]   File path(s), LVM identifier or RAID identifier, e.g.:
                 /dev/diskXsY[:/dev/diskYsZ:...]
                 path/to/disk.img@s1[:path/to/image.qcow2@s2:...]
                 lvm:<vg-name>:diskXsY[:diskYsZ:...]:<lv-name>
                 lvm:<vg-name>:path/to/disk.img@s1[:path/to/image.qcow2@s2:...]:<lv-name>
                 raid:diskXsY[:diskYsZ:...]
                 raid:path/to/disk.img@s1[:path/to/image.qcow2@s2:...]
                 (see `list` command output for available volumes)
  [MOUNT_POINT]  Custom mount path to override the default under /Volumes

• The only argument you usually have to provide is the disk identifier (unless you use a “diskless” custom action).
• It must always refer to one or more partitions or logical volumes (not whole disks).
• Basic syntax of an identifier is /dev/diskXsY - based on how anylinuxfs list or diskutil list identifies your drives.
• If your filesystem is on a logical volume, you will usually need a special prefixed identifier starting with lvm or raid (for mdadm Linux RAID). These can be deduced from anylinuxfs list output where any logical volumes will be shown as synthesized disks (similar to how diskutil does it for APFS containers)
• In case of btrfs filesystems spanning multiple disks (like RAID1 or JBOD), these will not be grouped in the anylinuxfs list output.
• In order to mount a filesystem like this, you use the /dev/diskXsY:/dev/diskYsZ syntax. Basically, you must specify all partitions that need to be attached to our microVM so that they can be scanned for any multi-disk btrfs filesystems.
• Besides physical disks, you can also work with disk images, simply by specifying their path and partition index (e.g. file.img@s1 or image.qcow2@s1).

Documentation

• Examples — command examples for common use cases
• Accessing a running VM — interactive and scripted access to the VM used for an active filesystem mount
• Custom actions — scripting hooks that run inside the VM
• Important notes — VM initialization, permissions, LUKS memory, NTFS drivers
• Troubleshooting — common issues and fixes
• Build from source — how to build anylinuxfs yourself

Acknowledgements

Logo designed by Junaid Iqbal.

This project was made possible by

• libkrun the microVM hypervisor for Linux and Mac
• libkrunfw - Linux kernel bundled for libkrun as a dynamic library
• vmnet-helper - utility for using macOS vmnet Framework (provides IP addresses to VMs)
• gvproxy - user space networking for VMs (vmnet-helper alternative)
• docker-nfs-server - launcher for NFS server in a container

Thank you all for your great work!