#language en
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: [[uk/mtp|Українська]]-~
----
[[WikiPedia:Media_Transfer_Protocol|Media Transfer Protocol (MTP)]] is used for transferring files between devices. Notably, between newer [[WikiPedia:Android_operating_system|Android]] or Microsoft smartphones and your Debian host.

Be aware that many smartphones will only enable MTP while the phone is unlocked! Recent Android versions will also require you to change the state of the USB connection from ''Charge this device'' to ''Transfer files''.

<<TableOfContents(2)>>

= Desktop support =
== GNOME ==
'''[[WikiPedia:GNOME|GNOME]]''' applications (like [[WikiPedia:GNOME_Files|GNOME_Files]] and [[WikiPedia:Archive_Manager|Archive_Manager]]) use [[WikiPedia:GIO_(software)|GIO]]-based [[WikiPedia:GVFS|GVFS]] (the GNOME virtual file system) to mount MTP volumes and access files on MTP devices:
 * launch on attaching your device (e.g., with USB cable)
 * interact with an attached device (e.g., by double-clicking the device's icon in the device list).
Install package [[DebianPkg:gvfs-backends|gvfs-backends]]

== KDE Plasma ==
'''[[WikiPedia:KDE|KDE]]''' uses the MTP [[WikiPedia:KIO|KIO]] Slave with a similar level of integration as GVfs. This requires the DebianPkg:kio-extras package to be installed. When a phone is connected and set to transfer files with MTP, KDE will open the ''Device Notifier'' and show an entry for it. From here, you can take actions such as opening it as a folder in Dolphin, or viewing the photos on your device through Gwenview.

== Others ==
A desktop-agnostic tool that allows you to simply mount and manage files on MTP-connected devices is [[http://gmtp.sourceforge.net/|gMTP]], which can be obtained by installing the DebianPkg:gmtp package.
----
= libmtp =

[[DebianPkg:libmtp|libmtp]] provides support for MTP devices. Its device support changes with each version of its code, thus you may need a particular version of libmtp (or greater) to support your particular device: e.g., the [[WikiPedia:Moto_G_%281st_generation%29|MotoG]] phone is not supported directly before `libmtp` version == 1.1.8 [[http://sourceforge.net/p/libmtp/feature-requests/126|per its maintainers]].
----
= Commandline =

Several tools provide a FUSE based file system for mounting MTP devices within the Unix filesystem hierarchy, making it accessible to any program that operates on files and directories. Examples include mtpfs, jMTPFS, go-mtpfs and simple-mtpfs, etc...

 1.#1 [[DebianPkg:mtp-tools|mtp-tools]]

    * install package name=`mtp-tools`

    * '''TODO:''' document usage, but see below.

 2.#2 [[DebianPkg:jmtpfs|jmtpfs]]

    Uses [[FileSystem#FUSE_Filesystem|FUSE]] to mount your device's MTP structure into a POSIX filesystem, and `fusermount` to unmount the device.

  * install package name=`jmtpfs`

  * create <directory> as your mount point: {{{$ mkdir -p <directory>}}}

  * make sure you have write access to <directory>: {{{$ sudo chown $USER:$USER <directory>}}}

  * to mount your device: {{{$ jmtpfs <directory/>}}}

   * On some MTP devices: your screen must be unlocked in order to mount. However, you might get a (spurious) `input/output error` even if the screen is unlocked.

  * to unmount your device: {{{$ fusermount -u <directory/>}}}

 3.#3 [[DebianPkg:mtpfs|mtpfs]]

    `mtpfs` has been orphaned since ''Squeeze'', anyway `mtpfs` is very similar to `jmtpfs`, except for the executable name, package name, and package status 

  * install package name=`mtpfs`

  * to mount your device: {{{$ mtpfs <directory/>}}}

  * to unmount your device: {{{$ fusermount -u <directory/>}}}


== testing and debugging device connection ==

Connect your target device (e.g., Android phone) to your Debian host (e.g., laptop) via USB cable, and unlock the target device. Relatively quickly, you should see the following:

 1.#1 Your Debian host's desktop should open a file browser (e.g., a `nautilus` window) showing the browsable contents of a location. If the location is mounted in your filespace, you should not need to read further from this article. Alternatively, the location will be shown with a URI beginning with `mtp://`, which will not be mounted, but can be manipulated via the usual means provided by your file browser (including copying and deleting files). If you wish to actually ''mount'' that location (i.e., your target device), read on.

 2.#2 The target device may also show some GUI, such as choosing the connection mode. If so, choose mode=MTP.

If neither of those occur, you should

 1.#1 Check your connection, e.g., the USB cable. If fixing that does not make your target device browseable as described above, then ...

 2.#2 Check which version of `libmtp` and associated packages you have installed on your Debian host: see following section=[[#device_statuses|device statuses]]. Install them if not already done. You will minimally need to have the executable `mtp-detect` in your path.

 3.#3 Run `mtp-detect` from your host with your target device attached.

If you see results like

{{{
$ sudo mtp-detect 
Unable to open ~/.mtpz-data for reading, MTPZ disabled.
libmtp version: 1.1.8

Listing raw device(s)
   No raw devices found.
}}}

... stop and seek help elsewhere. If you see results like

{{{
$ sudo mtp-detect 
Unable to open ~/.mtpz-data for reading, MTPZ disabled.
libmtp version: 1.1.8

Listing raw device(s)
Device 0 (VID=<something/> and PID=<something else/>) is UNKNOWN.
Please report this VID/PID and the device model to the libmtp development team
   Found 1 device(s):<remaining text omitted for this documentation/>
}}}

... your target device is not currently supported. As noted in the result, you should report it to the `libmtp` maintainers by making a [[https://sourceforge.net/p/libmtp/feature-requests/|feature request]] like [[https://sourceforge.net/p/libmtp/feature-requests/126/|this one]].

If you see results like

{{{
$ mtp-detect 
Unable to open ~/.mtpz-data for reading, MTPZ disabled.
libmtp version: 1.1.8

Listing raw device(s)
Device 0 <... remaining text omitted for this documentation, ending with/>
OK.
}}}

then you ''should'' be able to mount the target device onto your host's filespace as discussed in the following [[#Example:_laptop.2C_MotoG.2C_USB.2C_libmtp.2C_jmtpfs|example]].


== Example: laptop, MotoG, USB, libmtp, jmtpfs ==


=== device statuses ===

I have a (working) [[WikiPedia:Moto_G_%281st_generation%29|1st-generation Motorola MotoG]] running Android version=4.4.4 that I wish to mount on a Debian laptop. Latter has

{{{
$ cat /etc/debian_version
jessie/sid
$ uname -rv
3.11-2-amd64 #1 SMP Debian 3.11.8-1 (2013-11-13)
$ gcc --version | head -n 1
gcc (Debian 4.8.2-1) 4.8.2
}}}

Note that [[DebianPkg:libmtp|libmtp]] version >= 1.1.8 supports the MotoG [[http://sourceforge.net/p/libmtp/feature-requests/126|per its maintainers]]. After fiddling with APT and my repositories, I have

{{{
$ aptitude versions --disable-columns mtp | grep -e '^Package\|^i' | grep -vie 'dovecot\|mtpaint\|smtp'
Package gmtp:
Package gmtp:i386:
Package jmtpfs:
i  0.5-2  100
Package kio-mtp:
Package kio-mtp-dbg:
Package kio-mtp-dbg:i386:
Package kio-mtp:i386:
Package libmtp-common:
i  1.1.8-1  100
Package libmtp-dbg:
Package libmtp-dbg:i386:
Package libmtp-dev:
Package libmtp-dev:i386:
Package libmtp-doc:
i  1.1.8-1  100
Package libmtp-runtime:
i  1.1.8-1+b1  100
Package libmtp-runtime:i386:
Package libmtp9:
i  1.1.8-1+b1  100
Package libmtp9:i386:
i  1.01-3 testing 500
Package mtp-tools:
i  1.1.6-20-g1b9f164-1 testing 500
Package mtp-tools:i386:
Package python-pymtp:
Package uucp-lmtp:
}}}


=== setup/check Debian host ===

{{{
# make mount point ...
$ mkdir -p ~/Android_transfer/
# ... and unmount it
$ fusermount -u /home/me/Android_transfer
$ ls -al ~/Android_transfer/
total 8
drwxr-xr-x  2 me me 4096 Apr  5 20:08 .
drwxr-xr-x 50 me me 4096 Apr  5 21:09 ..
}}}

With no MTP devices connected to the laptop, I see (from the laptop)

{{{
$ date ; jmtpfs -l
Sun Apr  5 20:08:46 EDT 2015
Unable to open ~/.mtpz-data for reading, MTPZ disabled.
Available devices (busLocation, devNum, productId, vendorId, product, vendor):
}}}


=== successful jmtpfs mount ===

I then unlocked the MotoG's screen and connected it to the laptop with a USB cable.

Immediately upon connecting, a `nautilus` window opened on the laptop showing the browsable contents of location=`mtp://[usb:001,040]/` with device name=`XT1028`. I can also see (from the laptop)

{{{
$ date ; jmtpfs -l
Sun Apr  5 20:09:06 EDT 2015
Unable to open ~/.mtpz-data for reading, MTPZ disabled.
Device 0 (VID=22b8 and PID=2e82) is a Motorola Moto G (ID2).
Available devices (busLocation, devNum, productId, vendorId, product, vendor):
1, 41, 0x2e82, 0x22b8, Moto G (ID2), Motorola
}}}

I can then mount the MotoG's storage with

{{{
$ jmtpfs ~/Android_transfer/
Unable to open ~/.mtpz-data for reading, MTPZ disabled.
Device 0 (VID=22b8 and PID=2e82) is a Motorola Moto G (ID2).
Android device detected, assigning default bug flags
$ ls -al ~/Android_transfer/
total 4
drwxr-xr-x  3 me me    0 Dec 31  1969 .
drwxr-xr-x 50 me me 4096 Apr  5 21:09 ..
drwxr-xr-x 12 me me    0 Oct  2  4448648 Internal storage
$ ls -al ~/Android_transfer/Internal\ storage/
total 0
drwxr-xr-x 12 me me 0 Oct  2  4448648 .
drwxr-xr-x  3 me me 0 Dec 31  1969 ..
drwxr-xr-x  2 me me 0 Aug 31  2024 Alarms
drwxr-xr-x  3 me me 0 Aug 26  2014 Android
drwxr-xr-x  3 me me 0 Feb 13 19:50 DCIM
drwxr-xr-x  2 me me 0 Aug 31  2024 Download
drwxr-xr-x  2 me me 0 Aug 31  2024 Movies
drwxr-xr-x  2 me me 0 Aug 31  2024 Music
drwxr-xr-x  2 me me 0 Aug 31  2024 Notifications
drwxr-xr-x  2 me me 0 Aug 31  2024 Pictures
drwxr-xr-x  2 me me 0 Aug 31  2024 Podcasts
drwxr-xr-x  2 me me 0 Aug 31  2024 Ringtones
}}}

... and unmount the MotoG's storage with

{{{
$ fusermount -u /home/me/Android_transfer
$ ls -al ~/Android_transfer/Internal\ storage/
ls: cannot access /home/me/Android_transfer/Internal storage/: No such file or directory
}}}


=== failed jmtpfs mount ===

I initially tried to mount the MotoG using `sudo`. Don't do that! You'll get results like

{{{
$ sudo jmtpfs ~/Android_transfer/
Unable to open ~/.mtpz-data for reading, MTPZ disabled.
Device 0 (VID=22b8 and PID=2e82) is a Motorola Moto G (ID2).
ignoring libusb_claim_interface() = -6PTP_ERROR_IO: failed to open session, trying again after resetting USB interface
LIBMTP libusb: Attempt to reset device
Android device detected, assigning default bug flags
$ ls -al ~/Android_transfer/
ls: cannot access /home/me/Android_transfer/: Permission denied
$ sudo ls -al ~/Android_transfer/
ls: cannot access /home/me/Android_transfer/: Permission denied
$ sudo fusermount -u /home/me/Android_transfer
}}}

Remember: MTP filesystems are implemented as [[WikiPedia:Filesystem_in_Userspace|FUSE]], which means `Filesystem in` ''your'' `Userspace`.


=== copy files off your smarphone with mtp-getfile ===

First install the mtp-tools package:

{{{
$ sudo apt-get install mtp-tools
}}}

Then get the list of available files:

{{{
$ mtp-files > file_list.txt
}}}

file_list.txt will now contain entries like this:

{{{
File ID: 81
   Filename: WP_20161029_16_26_49_Pro.jpg
   File size 936160 (0x00000000000E48E0) bytes
   Parent ID: 12
   Storage ID: 0x00010001
   Filetype: JPEG file
}}}

where "Parent ID" is something like the folder where the file resides on the smartphone. So you'll want to do something like this to get that particular file:

{{{
mkdir "12"
mtp-getfile "81" "12/WP_20161029_16_26_49_Pro.jpg"
}}}

Yes, the `mkdir "12"` and the `12` from the ''Parent ID'' in the local file is '''important'''.