Access the iOS file system from Terminal or Finder with iFuse

Back in the day the original iPod could be plugged into a computer and used as an external hard disk. Alas iOS doesn't provide this feature, but it's still possible for those determined enough to find a way.

Access the iOS file system from Terminal or Finder with iFuse

Back in the day the original iPod could be plugged into a computer and used as an external hard disk. Alas iOS doesn't provide this feature, but it's still possible for those determined enough to find a way.

Have you ever wanted to copy files from your iPhone (or iPad) to your Mac, and wonder how to do it?  Here are some steps to do that without needing to purchase or subscribe to third-party software. In other words--this is the free option.

Who this technique is for

As with many free techniques, this one isn't for the faint of heart. It requires installing software and tools familiar to developers (Homebrew and iFuse), but probably not familiar to end users.

If you need access to the data this technique provides--then it's worth the effort to setup.  If you're not sure that you need to do this--you probably don't.  Most of the files you can access using iFuse are accessible via Finder or iTunes, so make sure you can't just use those apps before proceeding.

This type of setup may be most useful for scripts or investigating low level file layouts on an iOS device.

Also, fair warning: the techniques in this post involve installing software, development tools, and making security changes to your Mac. If you're not knowledgable and confident about doing these things, please don't implement any of these changes.

What data can I (and can't I) access from my iPhone if I do this?

This technique uses iFuse (an open source software package) to access iOS data over lightning.

  • iFuse will provide access to files and data on iPhone or iPad devices for app's that have intentionally made them available to an end-user.
  • iFuse will not provide access to files and data within an app sandbox, where the data is intended to be privately accessed by the app itself.

For example, iFuse will get you to this type of data from your Mac:

  • A general overview of the file system layout, and various system data files
  • Photos stored on your iOS device
  • The device's downloads folder
  • Various asset folders used by iTunes
  • Files intentionally made available by 3rd-party apps via iTunes Sharing that have included the UIFileSharingEnabled flag in their .plist configuration.

What you will not get using this technique:

  • Data stored within a 3rd-party app's private sandbox
  • SQLite/Core Data database files created and used by 3rd-party apps

Preparation

Once iFuse is installed and configured, you'll need your device UUID in order to mount the file system from your Mac.  So take a minute and fetch that.

This can be found either in Xcode (if you're a developer) or in Finder (if you're anyone with a Mac who doesn't use Xcode).

Xcode

Find the device UUID in Xcode's Devices and Simulators window. It's labeled "Identifier". Right click and copy it to the clipboard, saving it for later.

Finder

In macOS (recent versions), the UUID is exposed in Finder.  The UUID is easy to find--but only if you know the trick 😁. Here's the trick:

  1. Open finder, and click your iOS device (it must be paired so it trusts your macOS device. I assume you've done that).

2. Under the device name, note the label that has the marketing model, storage and battery status.  Click on that label.

3. The Serial Number, UUID and manufacturing model number will appear.

4. Right-click on that label, and choose Copy UUID.  Save this UUID somewhere for later.

Installation

This tutorial assumes you have Homebrew installed on your system. For developers, this is likely a good assumption. For others, probably it is not.

Need to instal Homebrew first?

If you need HomeBrew, head over to HomeBrew and get the latest instructions, then come back here.

Install osxFuse

iFuse is built on top of osxFuse, so use homebrew to install it first.

brew install osxfuse

Study the output of osxFuse carefully. It may require a kernel extension to be enabled on your system before use (if so it will provide instructions for doing so). Kernel extensions are and advanced configuration. If you're not comfortable doing this, please don't!

The osxFuse installation may also warn that Apple Command Line Tools are needed. If so, the installation output will provide an instruction for that:

xcode-select --install

Install iFuse

After osxFuse is installed, install iFuse.

brew install ifuse

Mount the iOS file system

With osxFuse and iFuse installed, you can safely mount the file system.

This is a two step process:

  1. Create a placeholder folder to serve as a mount point (iPhone in the example below)
  2. Mount the iOS root folder to that mount point, passing in the UUID of the device to mount (use the UUID you captured above).
mkdir ~/iPhone
ifuse ~/iPhone/ -u 00000000-0000000000000000

View the Files

Once mounted, you can browse files from the Terminal command line, for example:

To view files from Finder, use the ⇧⌘G Finder keyboard shortcut (or select Go/Go to folder... from the menu), and type in the mount point folder created above.

This will open a new Finder window to allow browsing the folder structure in the GUI

Unmounting the iOS volume

Use umount from Terminal to unmount the folder mounted above:

umount ~/iphone

Browsing an App's iTunes Sharing Files

If an app has provided read access to its documents via the info.plist UIFileSharingEnabled setting, you may be able to view its documents via iFuse. iOS 8.3 placed tight restrictions on this capability, so the developer of the app probably would need to go out of their way to enable this feature.  

If you are the developer of the app, then this could actually be the best reason to use iFuse!  You could access your app's Documents from your development workstation.

In my experience this particular feature doesn't work with any 3rd-party app I've tried it with; I assume few apps have opened this permission since iOS 8.3 shipped.  Your mileage may vary, so I include it here for completeness.

Fetch the Bundle ID for the app

Use iFuse to list apps installed on the device:

ifuse -u 00000000-0000000000000000 --list-apps

This list probably wont' be comprehensive, and it won't tell you whether it's possible to read Documents from any of the apps in the list. An example from the device I have connected is:

~ % ifuse -u 00000000-0000000000000000 --list-apps
"CFBundleIdentifier","CFBundleVersion","CFBundleDisplayName"
"com.readdle.Scanner","8.0.6.766","Scanner Pro"
"com.apple.Pages","7353.9.8","Pages"
"com.thetileapp.tile","4468","Tile"
"com.pleco.chinesesystem","3.2.59.0","Pleco"
"com.agilebits.onepassword-ios","70701005","1Password"
"com.ledvance.smart","60","SYLVANIA Smart Home"
"com.vitotechnology.StarWalk2","2.11.12.5","Star Walk 2"
~ %

Mounting Documents from using a bundle ID

The mount command to mount the folder for a single app is the same as before, with the addition of the app bundle id:

ifuse ~/iphone3 -u 00000000-0000000000000000 --container com.readdle.Scanner

For Apple and 3rd-party apps, I find this command generally just throws an error:

ERROR: InstallationLookupFailed
The App 'com.readdle.Scanner' is either not present on the device, or the 'UIFileSharingEnabled' key is not set in its Info.plist. Starting with iOS 8.3 this key is mandatory to allow access to an app's Documents folder.

Summary

That's it for the tutorial.  iOS is intended to be fairly opaque to prying eyes--and the limitations of what can actually be accessed via this type of connection are pretty significant--and has only been tightened over time. Still, for just that situation where it can be helpful to script some data from an iOS device, this technique can fit the bill.

Tags:

Rob Kerr

App development for iOS, creating applications for my own development studio (Cuvenx Inc.), and consulting with awesome clients to build their mobile applications.

More posts from this author