Translation(s): English - Français - Castellano - Italiano

This page describes how to connect an iOS device (e.g. iPhone, iPod Touch, iPad, Apple TV) to a Debian Squeeze (DebianSqueeze) or Wheezy (DebianWheezy) system, using libimobiledevice. This enables the transfer of music and other files between an iPhone and a Debian computer, as well as some other functionality (see "What is Covered and Not Covered by This Document", below).

The terms "iPod" and "iPhone" are used interchangeably in this document, and "iPad" and "Apple TV" may also be appropriate surrogates.

Contents

  1. What is Covered and Not Covered by This Document
    1. Older iPods
    2. Debian OS on my iPhone?
    3. Tethering?
    4. Details of libimobiledevice
    5. Updates Needed?
  2. Getting Started - Backup your data
  3. Configure the iPhone, part 1
  4. Connect the iPhone
  5. Configure the iPhone, part 2
  6. Using Rhythmbox
  7. mount-iphone.sh script
  8. Mount Troubleshooting
  9. backporting libimobiledevice 1.1.1 to Squeeze
    1. backporting caveats
    2. step-by-step instructions for the backport
  10. List of Programs
  11. List of Tools

What is Covered and Not Covered by This Document

Older iPods

Older model iPods that do not run iOS are well-supported by a simple installation of gtkpod -- you need not go through all this hassle to connect an older-model iPod and transfer music.

Debian OS on my iPhone?

* Nope. Not here. This page is for connecting an iPhone running Apple's iOS to a Debian computer.

Tethering?

* Tethering is not covered here; however if you want to tether via USB, setting up libimobiledevice may be required, and thus some of these instructions may be useful for you. For bluetooth tethering, libimobiledevice is not helpful, and thus neither is this document.

* The Arch Linux Wiki has a great article on iPhone Tethering. It would be great to debianize and integrate those instructions onto this page, or perhaps split this page into several pages dedicated to Debian and iPhone/iOS.

Details of libimobiledevice

* From the libimobiledevice webpage:

* The author(s) of this document mostly just wanted to copy music between an iPhone and Debian computer. Though libimobiledevice enables much more functionality than that, such functionality is not covered in this document. However, this document can help you get libimobiledevice working and talking to your iPhone.

Updates Needed?

2018-11-06

Tested on (iPhone-#-MODEL):

Instructions (see https://www.dedoimedo.com/computers/linux-iphone-6s-ios-11.html)

* This document had its last major update in Feb 2012, for libimobiledevice 1.1.1-3 and iOS 5. It has been some time since then, and that version of libimobiledevice may or may not work for more recent versions of iOS. However, these instructions may still be useful for installing later versions of libimobiledevice and other software. (In fact, the backporting instructions may be useful as a reference point for configuring completely unrelated software)

* Update: December 2017

Getting Started - Backup your data

* These instructions explain how to set up your iPhone so that you can sync (copy music) from Debian Squeeze or Wheezy using a program such as gtkpod, Rhythmbox, amarok or banshee. Doing so should not disrupt your iTunes sync-- even after adding music, you should still be able to access the device using iTunes. That said, keep in mind: 1. this is free software; 2. it comes with no guarantee, and 3. it is possible that a bug could exist that could delete your music and other files. Most of us haven't had such issues, but we advise that you back up your data before starting.

Configure the iPhone, part 1

* Once configured, your iPhone should work on any GNU/Linux machine, without needing to rerun this configuration. (Provided the GNU/Linux machine has the necessary packages installed.)

* If the iphone already has music on it, you may skip to the next step

  1. Create an initial audio database, if one does not exist already.
    1. Plug the iPhone into an MS Windows or Mac OS X computer
    2. Fire up iTunes
    3. Add at least one song or free podcast to the iPhone.

* This initializes a database on the iPhone which is needed for the rest of the instructions to work.

[There may be a way to copy an initial database file using only Debian; if you know how, please edit this wiki page.
The libimobiledevice homepage mentions a project called ideviceactivate.]

Connect the iPhone

* If your iPhone has a recent version of iOS (5 or later? Maybe 4.3? 4.2.1?) then you will need libimobiledevice 1.1.1 or later, available in Wheezy. Squeeze has libimobiledevice 1.0.2, which will not work with recent versions of iOS. There is a rather involved backport, described below. It's probably a good idea to first proceed with the normal installation, before attempting the backport. If the normal installation doesn't work (nowadays usually due to an "unhandled lockdown error") then you can try the backport.

  1. Install several packages:

    • aptitude install libimobiledevice-utils gvfs-backends gvfs-bin gvfs-fuse

  2. As root, edit the file /etc/fuse.conf:
    Uncomment (remove the # symbol from) #user_allow_other at the end of the file.
    If you can't find the line then simply make a new line at the end of the file that reads user_allow_other.
    Save the file! If you are not root then you will not be able to save it, and you will have to do it again, as root.

  3. (Update: as of Debian 8 (Jessie) a fuse group is not needed anymore, so you can skip this step!) Ensure that your user is a member of the fuse group: as normal user, type groups and look for "fuse". If not, then:

    1. Add your user to the fuse group. I'll use "sheila" as an example; replace sheila with your username.

      usermod -aG fuse sheila
      [You should do this for each user on your system that should be able to connect iPhones to the computer]
      [Alternately you can use a GUI tool like Gnome's System → Administration → Users and Groups]

    2. After adding your user to the fuse group, log out and log back in. If your GNOME session (or other desktop session) was started before your account was added to the "fuse" group, then your environment does not yet include the fuse group; thus you will not be able to run programs that require group "fuse" permissions.

  4. Pray. :-) If the next step does not work then there may be some significant challenges ahead.

  5. Connect the iPhone.

  6. Hit Cancel if you are asked to open it as a camera to import pictures;

  7. Alternately, if you get an option to do an AFC or music mount, then you can do that.
  8. If you are lucky, the iPhone will appear on the desktop, with its name (e.g. "Sheila's iPhone" or "iPhone of Sheila").

  9. By default, it is mounted in ~/.gvfs (e.g. for sheila, /home/sheila/.gvfs/iPhone of Sheila)

  10. If you are not so lucky -- that is, you don't see anything on the desktop, and ~/.gvfs/iPhone does not exist -- then you should do a little troubleshooting.
    It may be that you are simply not running an automount daemon, or the problem may be more difficult. Go to the Mount Troubleshooting section.
    Tip: if you prefer to mount via the command line rather than with auto-mount daemons, see the mount script.

Configure the iPhone, part 2

* If you are running Wheezy or later, the following happens automatically, and you can skip to the next section.

* Start up a terminal: this section will be performed on the command line. You should be a normal user-- not root or sudo

  1. First download and set up the mount script and then come back here.

  2. Assign the serial number of your iPhone to a variable called $serial. Note serial= is correct, $serial= will not work

    serial=$(./mount-iphone.sh echo_serial)

  3. Verify that the variable was properly assigned

    echo $serial
    If this doesn't show the serial number, go back up-- the next steps will not work.

  4. cd to your home folder. (if you type cd by itself, it will bring you to your home folder)

    cd

  5. cd into the iphone's mount point folder

    cd .gvfs
    cd "iPhone of Sheila"
    note: the double-quotes are important, if the name has spaces or apostrophes or other special characters in it
    Tip: tab-completion is a handy terminal tool. Type cd iP and then press the TAB key.

  6. moving along...

    cd iTunes_Control
    ls

  7. Does the ls above show a directory called Device?

    1. If not, then

      mkdir Device

  8. Return to the parent directory (e.g. "~/.gvfs/iPhone of Sheila")

    cd ..

  9. Make sure you're in the base directory of the iPhone

    pwd
    The above should output, for example:
    /home/sheila/.gvfs/iPhone of Sheila
    If not, then get into that directory. The next step depends on it.

  10. Use the following command (from libgpod-common) to create iTunes_Control/Device/SysInfoExtended:
    ipod-read-sysinfo-extended $serial $PWD

  11. Check for the new file

    ls -l iTunes_Control/Device/SysInfoExtended

* Your iPhone is now ready to interface with libgpod and all the tools that use it, like gtkpod, rhythmbox, amarok, banshee, etc.! You can use these tools on any modern linux computer to add and delete music from your iPhone, in addition to your iTunes sync computer, without destroying the playlist.

Using Rhythmbox

  1. First, install it:

    aptitude install rhythmbox rhythmbox-plugins

  2. Log out and log back in again.

    (It's not clear why this is necessary, but may fix the problem if you get an error when attempting to mount the along the lines of:
    "Error: DBus error org.freedesktop.DBus.Error.ServiceUnknown: The name :1.41 was not provided by any .service files".    )

  3. Launch Rhythmbox:

    Applications → Sound and Video → Rhythmbox

  4. Find the iPhone on the left panel
  5. Click on the iPhone to see what music is on it
  6. You can now Drag-and-Drop files between the iPhone and your rhythmbox music collection, similar to the way you would in iTunes and other programs.

* NOTE: Older versions of rhythmbox may have a difficult time syncing the iPhone properly. Some of us have had real difficulties with music we put on the device not ever showing up. Gtkpod seems to sync more reliably.

* The following may help:

  1. Use rhythmbox's rightclick menu to eject the iPhone, and wait for some time while it syncs
  2. Connect the iPhone to your iTunes computer and cancel the "cancel sync" operation
  3. Install gstreamer1.0-plugins-* (all of them... this seems to help some people)
  4. ??? not sure what else

mount-iphone.sh script

* If you have a Debian-based installation which auto-magically mounts your iPhone and presents one or more graphical interfaces for accessing your iPhone's data, this script will be of little use. (As of iOS 11.3.1, this script seems to be unnecessary for access to "DCIM" files.)

* Some people do not have an automount daemon in their DE; some others simply prefer to mount things manually.

* This script is also very useful for the section, "configure the iPhone, part 2"

  1. Script is here: mount-iphone.sh
    (clicking the link takes you to an "Attachment page" where you can "Download" the script)

  2. Open a terminal
  3. Navigate to the directory where you saved the script
  4. Set the execute bit:

    chmod +x mount-iphone.sh

* For those who prefer to simply copy a few commands, the script basically does this:

* Now it is time to try running the script.

  1. First run it with no parameters, to see if it detects the iPhone

    ./mount-iphone.sh
    If you see something like,

    • fb9961044533cd317cb6f2bce3424c2771ae16d6 is mounted
      or
      fb9961044533cd317cb6f2bce3424c2771ae16d6 is not mounted
      ...then that's good!

  2. If it is not yet mounted, you can mount it like so:

    ./mount-iphone.sh mount

  3. If all is well, you will see a message like this:

    mounted iphone with serial fb9961044533cd317cb6f2bce3424c2771ae16d6
    (note, your serial number will be different)

  4. Alternately, you might see an unwelcome error message such as the following:

    Unhandled lockdown error (-5)
    If you get an error, go to the Mount Troubleshooting section.

* If it worked correctly, you may want to go back to Configure the iPhone, part 2.

Here is the script inline, for reference convenience: (skip to the Next Section) 

   1 #!/bin/sh
   2 #
   3 # mount-iphone.sh
   4 # This script attempts to mount or unmount the first connected ipod/iphone.
   5 # Usage: ./mount-iphone.sh [mount | umount | echo_serial]
   6 # It should be dash-friendly
   7 #
   8 # Written by Mohamed Ahmed, Dec 2010
   9 #
  10 # Refactored and extended by David Emerson, Feb 2012
  11 #
  12 # 2017-04-04   DaveSp   In case more than one Apple device is attached via USB,
  13 #                       "awk '/iSerial" now only matches when a serial number is
  14 #                       present.
  15 #
  16 # You can configure send_msg to use either a console echo, or notify-send.
  17 # notify-send is part of the debian package, libnotify-bin
  18 # The apple pictures in /usr/share/pixmaps are part of the gnome-desktop-data package
  19 #
  20 # uncomment the following if you want to see the mount command used:
  21 # show_mount_cmd=1
  22 
  23 # you can uncomment this line to see all the commands sh executes:
  24 # set -x
  25 
  26 show_msg ()
  27 {
  28   # notify-send -t 4000 -u normal "mount-iphone" "$1" -i "/usr/share/pixmaps/apple-$2.png"
  29   echo "$1" >&2
  30 }
  31 
  32 get_device_ids ()
  33 {
  34   # get the Apple vendor id (idVendor) from lsusb
  35   idVendor=$(lsusb -v 2>/dev/null | awk '/idVendor.*Apple/{print $2; exit}')
  36   [ -z "$idVendor" ] && { show_msg "Cannot find any Apple device" "red"; exit 1; }
  37   # get the device serial number (iSerial)
  38   iSerial=$(lsusb -v -d $idVendor: 2>/dev/null | awk '/iSerial\s+\S+\s+\S/{print $3; exit}')
  39   [ -z "$iSerial" ] && { show_msg "Cannot find serial number of Apple device $idVendor" "red"; exit 1; }
  40 }
  41 
  42 is_mounted ()
  43 {
  44   gvfs-mount -l | grep -i "mount.*$1" >/dev/null
  45 }
  46 
  47 mount_iphone ()
  48 {
  49   [ -z $show_mount_cmd ] || echo gvfs-mount afc://$1/ >&2
  50   if gvfs-mount afc://$1/; then
  51     show_msg "mounted iphone with serial $1" "green"
  52   else
  53     show_msg "iphone mount failed" "red"
  54     exit 1
  55   fi
  56 }
  57 
  58 unmount_iphone ()
  59 {
  60   ## now gvfs unmount the device
  61   [ -z $show_mount_cmd ] || echo gvfs-mount -u afc://$1/ >&2
  62   if gvfs-mount -u afc://$1/; then
  63     show_msg "unmounted iphone with serial $1" "red"
  64   else
  65     show_msg "iphone umount failed" "red"
  66     exit 1
  67   fi
  68 }
  69 
  70 case $1 in
  71   mount)
  72     get_device_ids
  73     is_mounted && { show_msg "$iSerial is already mounted" 'green'; exit; }
  74     mount_iphone $iSerial
  75     ;;
  76   umount|unmount)
  77     get_device_ids
  78     is_mounted || { show_msg "$iSerial is not mounted" 'red'; exit; }
  79     unmount_iphone $iSerial
  80     ;;
  81   echo_serial)
  82     get_device_ids
  83     echo $iSerial
  84     ;;
  85   '')
  86     get_device_ids
  87     is_mounted && show_msg "$iSerial is mounted" 'green' || show_msg "$iSerial is not mounted" 'red'
  88     ;;
  89   *)
  90     echo "Usage: $0 [mount | umount | echo_serial]"
  91     exit 1
  92     ;;
  93 esac
  94 
  95 exit 0

Mount Troubleshooting

* If you are here, then chances are you had trouble mounting the device. If not, then you need not be here...

  1. The first troubleshooting action to take is to set up the Mount Script, above. Do that!

  2. Try and mount

    ./mount-iphone.sh mount

* If you get an Unhandled lockdown error, the cause for this error can be varied:

* If you get Cannot find serial number of Apple device 0x05ac check that the device is paired.

* Other errors... please help expand the wiki!

backporting libimobiledevice 1.1.1 to Squeeze

backporting caveats

* As of 2014-Mar there is no official backport. It would be great if there was! You should check for one before doing this. Really. http://backports.debian.org/Packages/ - search for libimobiledevice in squeeze-backports and squeeze-backports-sloppy

* If someone has backported libimobiledevice 1.1.1, then please make mention of it here.

* Don't delete this section, though, as it may very well be useful to someone in the future, for reasons unknown and unexpected to you now.

* Unfortunately, after performing this backport, Squeeze's rhythmbox is still a little buggy, and is not very reliable about putting music on the iPod. Note the issues mentioned in the rhythmbox section. You can definitely use it to get music FROM the iPod, though!

* Squeeze's gtkpod doesn't seem to work at all. However, it is relatively easy to compile gtkpod 2.0.2 from snapshot.debian.org, and that seems to work pretty well with iOS 5!

* In order to proceed with building this backport, you must be comfortable with the following:

  1. manipulating /etc/sources.list - making multiple changes
  2. modifying source files
  3. building debian packages using dpkg-buildpackage
  4. installing debs
  5. patiently following all the steps in order

* NOTE: this works with libimobiledevice 1.1.1-3, available 2012-Feb-16. If, by the time you try this, wheezy has moved to a later version of libimobiledevice, and it does not work, then your best bet may be to get libimobiledevice 1.1.1 from http://snapshot.debian.org - refer to the gtkpod 2.0.2 instructions, below.

* Alright, if you're still with me, let's get started...

step-by-step instructions for the backport

* As you can see, this backport is not for the faint of heart. Good luck!

List of Programs

List of Tools

Tools and programs useful to iPhone users in debian

Orphan:

CategoryPhone