How to mount macOS APFS disk volumes in Linux

APle FileSystem is the new filesystem for mac computers ad iOS devices since 2017.

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!

apfs documentation isn't coming any time soon.
Apple aren’t going to be documenting or open sourcing APFS any time soon by the looks of it.

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.

You can see that the macos partition is now mounted in the File browser.

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.

16 thoughts on “How to mount macOS APFS disk volumes in Linux”

  1. If this helps anyone, additional step running Ubuntu 18.04 Live USB user required otherwise shows similar error to “recipe for target ‘all’ failed apfs”
    Run this to modify the make file prior to doing the make command

    sed -i.bak ‘s/USE_FUSE3:BOOL=ON/USE_FUSE3:BOOL=OFF/’ CMakeCache.txt

  2. I also had to install these packages in order to make it:

    sudo apt-get install libz-dev fuse3 libfuse3-3 libfuse3-dev libbz2-dev

    and it would make sense for you to use $USER instead of $USERNAME and

    Otherwise it’s a short, sweet tutorial!
    cheers
    Klokie

  3. Thanks to the author and commentors. This helped me to boot a Mac with Ubuntu live and recover files that were lost behind a forgotten password.

    Here are the combined commands I used to make it work

    ### From a Terminal with Ubuntu Live USB ###

    sudo apt-get update -y
    sudo apt-get install -y libfuse-dev
    sudo apt install -y git

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

    mkdir build
    cd build
    sudo apt install -y cmake
    cmake ..
    sed -i.bak ‘s/USE_FUSE3:BOOL=ON/USE_FUSE3:BOOL=OFF/’ CMakeCache.txt
    sudo apt-get install -y libz-dev
    sudo apt-get install -y libbz2-dev
    make

    sudo cp apfs-* /usr/local/bin

    sudo mkdir -p /media/MacHD
    sudo ./apfs-fuse -o allow_other /dev/sda2 /media/MacHD

    #–Add the ability to mount an exFat USB to copy the data to (Natively compatible with Windows & Mac)

    sudo add-apt-repository universe
    sudo apt update
    sudo apt install exfat-fuse exfat-utils

    1. error on cmake .. any ideas? “CMake Error at CMakeLists.txt:5 (project): No CMAKE_CXX_COMPILER could be found.

      1. Sounds like you haven’t installed build-essential package. Apt install build-essential should get you the C compiler.

  4. Work perfectly with my MacBookPro running Mojave and the partition with Ubuntu 20.4
    I just modified the fstab file.. not tested yet if it mounts automatically. Thanks very much

  5. Thanks for the instructions!

    But I have a 2013 MBA and removed the SSD due to the MBA was broken.

    And now I tried to mount the SSD through Ubuntu and followed all the instructions above, when I tried to use:
    `sudo fdisk -l`
    I can’t see my disk still, but it shows in the disk tool on Ubuntu with only some basic info (seem just detect the disk but cannot recognize it), can someone help on this?

    Thank you so much

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.