How to mount macOS APFS disk volumes in Linux

In 2017, Apple changed the default filesystem on their macOS (High Sierra and above) to APFS, he Apple File System. It replaced HFS+.

It works on a principle of using containers, rather than partitions. It has good cloning efficiencies, better encrytion, snapshot support as well as a few other benefits.

Proprietary prattle

As all things recent in the Apple world, they do not like to share things. Even when this could negatively impact their business. Take FaceTime, for example. If they had made that platform agnostic, meaning that people on Windows, Android and maybe even Linux/Web platforms could use it, then it is arguable that FaceTime would have taken much of the market share from the likes of Skype. APFS is no different. Apple haven’t shared the API, so it relies on people to do an extent of guesswork, detailed research and some reverse engineering. All of which is never a good thing when you are working on the systems that look after the integrity of your files!

For those of you that use Linux on a mac and still have a need to access your files on the Mac partition of your hard drive on occasion then you may find it a challenge. If you have any version of macOS prior ot 10.3 (High Sierra), then your mac will be using HFS+. Check out our comprehensive guide on using Linux on a mac on how to mount your HFS+ partition as read/write.

How do I get it working?

For the newer APFS users, fortunately, you can now use a driver called apfs-fuse to access your mac’s APFS disk. Note that this driver is not part of your Linux distribution and you will have to build it from source code. This short guide will show you how.

Bummer, Read only….

Unfortunately, at least for now, you are limited to read-only access. The upshot of this is that no data can be damaged by any bugs that may exist in this experimental software. The driver’s associated mount tool will also not perform transparent LZFSE decompression. I have been using this tool for a number of weeks on my ‘Mojave’ macOS computer and it works well.

Get tooled up

Firstly, I’d like to say that this is an entirely newbie friendly tutorial, however on this occasion, it’s all work at the Terminal. Don’t worry too much if you’re not used to working at the command line, you are safe to copy and paste the instructions.

Firstly, we need to have the appropriate tools in order to build the APFS-Fuse driver. Open your Terminal app and enter these commands:

sudo apt update
sudo apt install libicu-dev bzip2 cmake libz-dev libbz2-dev fuse3 libfuse3-3 libfuse3-dev clang git libattr1-dev

On older versions of Ubuntu, you may need to use the following: sudo apt install fuse libfuse-dev libicu-dev bzip2 cmake libz-dev libbz2-dev clang git libattr1-dev

Now we can download (clone) the driver source code with git:

git clone https://github.com/sgan81/apfs-fuse.git
cd apfs-fuse
git submodule init
git submodule update

After that’s done, it’s time to compile the downloaded source code:

mkdir build
cd build
cmake ..
make

After compilation, the binaries are located in the build directory. I recommend copying the apfs* tools into a directory that can be accessed in the path, for example /usr/local/bin. To copy them simply do this:

sudo cp apfs-* /usr/local/bin

Now we need to find out which disk partition macOS is on. By using the fdisk -l command you’ll be able to see the layout of the disk.

$sudo fdisk -l
--- 8>--snipped the loop volumes--<8 ---
Disk /dev/sda: 465.9 GiB, 500277790720 bytes, 977105060 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 4096 bytes
I/O size (minimum/optimal): 4096 bytes / 4096 bytes
Disklabel type: gpt
Disk identifier: 6153AD88-FE14-4E88-8D9A-60E8AA465516

Device         Start       End   Sectors   Size Type
/dev/sda1         40    409639    409600   200M EFI System
/dev/sda2     409640 764593231 764183592 364.4G unknown
/dev/sda3  764594176 781570047  16975872   8.1G Microsoft basic data
/dev/sda4  781832192 976842751 195010560    93G Microsoft basic data
--- 8>--snipped the loop volumes--<8 ---

You can see in my example above that there is a 364.4GB unknown partition. I know that this is my macOS partition because I know that the size of my macOS partition is 365GB. This means that the device identifier is /dev/sda2, so that’s what we will mount.

Let’s check it out and see if it works….

sudo mkdir -p /media/$USERNAME/macos
sudo ./apfs-fuse -o allow_other /dev/sda2 /media/<your userame>/macos

Hopefully, all going well, you won’t have received any error messages at this point. If you have, then perhaps the README file can provide some enlightenment.

Making it stick

If you want to have your macos partition automatically mount every time you start up you computer, then you’ll need to edit into your filesystem table (fstab). To do this, we will need to make a symlink to the apfs mount tool, and then edit the fstab (if you don’t have nano, use vim):

sudo ln -s /usr/local/bin/apfs-fuse /usr/sbin/mount.apfs
sudo nano /etc/fstab

Add a line at the bottom of the file (all on one line) that says this:

mount.apfs#/dev/sda2    /media/<your username>/macos/    fuse    user,allow_other        0       0

If you want to see if that works immediately just unmount the disk (see the cleaning up section below). Then type sudo mount -a to mount the disk from the fstab.

Getting to know your partition

When the partition is mounted, you will see two directories, private-dir and root. The directory root is the one you want. Inside there is the root filesystem of your mac. You’ll find your stuff in the ‘Users’ folder.

Cleaning up (Unmounting)

To unmount the macos directory properly, you should use the fusermount command:

fusermount -u /media/<your username>/macos

I hope this has helped you get access to your mac’s files. Please share this article and let me know how you get on in the comments section below.