Ubuntu logo

Developer

Installing Ubuntu for Devices

Install Ubuntu for devices on a supported phone or tablet

Here are instructions for installing Ubuntu for devices (phone and tablet).

Note: To install Ubuntu Desktop, see http://www.ubuntu.com/download/desktop

Supported Devices

Target devices under active development are here.

Community driven ports to a much wider set of devices (including installation instructions) are here. These ports are not officially supported.

Warning: data loss

Installing Ubuntu for devices deletes all data (including applications and data such as contacts, photos, and etc.) from the device.

An optional procedure is provided below that backs up the Android apps and data to a local file. There is no guarantee that a restore will succeed.

See Reinstalling Android.

Disclaimer

“Ubuntu for devices” is released for free non-commercial use. It is provided without warranty, even the implied warranty of merchantability, satisfaction or fitness for a particular use. See the licence included with each program for details.

Some licences may grant additional rights. This notice shall not limit your rights under each program’s licence. Licences for each program are available in the usr/share/doc directory. Source code for Ubuntu can be downloaded from archive.ubuntu.com. Ubuntu, the Ubuntu logo and Canonical are registered trademarks of Canonical Ltd. All other trademarks are the property of their respective owners.

“Ubuntu for devices” is released for limited use due to the inclusion of binary hardware support files. The original components and licenses can be found here.

Release notes

Ubuntu for devices is still under development. Installing an Ubuntu for devices image may make your device unusable. Important features may be missing or broken. New images may introduce new features and may break existing features as development continues. Ubuntu for devices does not yet provide a reliable replacement for your current handset, phone or tablet.

See Release Notes for details.

Prepare your Desktop

Here you learn how to prepare your Ubuntu Desktop system. After these steps are completed, you can connect your device to the Desktop and drive an installation from the Desktop.

Ensure you have the universe archive enabled

You need to install the ubuntu-device-flash package. This is published in the Ubuntu universe archive.

  1. Ensure the universe archive is enabled.

Add PPAs (pre Trusty only)

The Phablet Tools PPA provides additional tools needed to install Ubuntu for devices . Tools are provided for installation on Ubuntu Desktop starting with 12.04 Precise.

You do not need to add the PPAs for Ubuntu Desktop 14.04 Trusty because the tools are available in the standard Ubuntu Universe archive component.

  1. On your computer, press Ctrl+Alt+T to start a terminal.
  2. Add the Phablet Tools PPA as follows:
    $ sudo add-apt-repository ppa:phablet-team/tools
  3. On Ubuntu 12.04, you also must add the Ubuntu SDK Release PPA:
    $ sudo add-apt-repository ppa:ubuntu-sdk-team/ppa
  4. Update your system to use the latest packages:
    $ sudo apt-get update

Install the ubuntu-device-flash package

The ubuntu-device-flash package is your main tool for installing Ubuntu for devices.

  1. Install the ubuntu-device-flash package:
    $ sudo apt-get install ubuntu-device-flash

After installation, you can display the help page for the ubuntu-device-flash tool as follows:

$ man ubuntu-device-flash

Press ‘q’ to quit the help.

Install phablet-tools package

The phablet-tools package provides a Desktop tools useful when working with a USB-connected Ubuntu device. For example, click-buddy creates a click package and runs it on the device, phablet-screenshot takes a screenshot from the device and saves it in your current directory, phablet-bootchart creates a bootchart image, and more.

  1. Install phablet-tools:
    $ sudo apt-get install phablet-tools
  2. List its tools with:
    $ dpkg -L phablet-tools | grep bin
  3. Display a tool’s help with the -h argument, for example:
    $ phablet-config -h
    usage: phablet-config [-h] [-s SERIAL]  ...
    Set up different configuration options on a device
    [...]

About adb and fastboot

Installing ubuntu-device-flash also adds two important Android tools you frequently use: adb and fastboot.

  • adb: Provides a terminal connection to the device when it is fully booted. (You must install Ubuntu first or enable developer options in Android.)
  • fastboot: Provides a terminal connection over USB when the device is booted into the bootloader.

The instructions here are complete, but you may also want to view help for these tools. A convenient method is piping them into less, then using up and down arrows to scroll and ‘q’ to quit, as follows:

$ adb help 2>&1 | less
$ fastboot help 2>&1 | less

Saving Android data

Before you install Ubuntu, you should save some key data. This includes backing up your Android apps and user data and saving some data about your device to make it easier to reinstall Android later.

Saving Android data over USB from your Ubuntu Desktop requires first enabling Developer Mode and USB Debugging from the Android OS, as explained next.

Enable Android Developer Mode

Here, you enable Developer Mode on your device.

  1. Navigate to  Settings > About phone | About tablet | about. Select the option available on your device. Tip: Some earlier Android versions may not require this step.
  2. Tap Build number seven times.

A pop-up informs you that you have succeeded.

Enable USB Debugging

Here, you enable USB Debugging. This is required for a USB terminal connection from your Desktop to your device.

After enabling Developer Mode, the Developer options item is exposed in the Settings page.

  1. Navigate to Settings > Developer options
  2. Enable USB Debugging

When a device is connected, you are prompted in Android to authorize it.

  1. Physically connect your enabled device to your Ubuntu Desktop over USB.
  2. On Android, accept the prompt to Allow USB debugging for the specified computer.
  3. To verify the connection, use adb to display currently connected devices:
    $ adb devices
    List of devices attached
    025d138e2f521413 device

Tip: If the device does not display, try running adb kill-server first.

Now, the device is fully connected to your Ubuntu Desktop for development/installation operations.

Backup Android apps and data

Before installing Ubuntu for devices, you can optionally create a backup file on the Desktop that saves your Android applications and data. You can use this backup file later to restore your applications and data if you decide to reinstall native Android on the device.

Tip: To restore Android from the backup, see Reinstalling and Restoring Android.

  1. In a terminal on your Ubuntu Desktop, create the backup file as follows:
    $ adb backup -apk -shared -all
  2. In Android, authorize the backup as prompted.

A file containing your backup is created in your current working directory named: ./backup.ab. Save this file securely.

Record your device type and build ID

You may want to reinstall Android later. To do this, it is helpful to write down and save key data. This data helps you open the right Android web page to download the files needed to restore your device to Android.

You can obtain this information from the Android device’s /system/build.prop file.

  1. Return the image type:<
    $ adb shell grep ro.product.name system/build.prop
    ro.product.name=razor

    In this case, the image name is “razor”. This is useful for finding Android OS images here: https://developers.google.com/android/nexus/images

  2. Return the device type:
    $ adb shell grep ro.product.device /system/build.prop
    ro.product.device=flo

    This device is type “flo”. The device type is used (automatically) to select the correct image in an Ubuntu image channel. The device type is also used to differentiate images on http://cdimage.ubuntu.com/ubuntu-touch/daily-preinstalled/current/.

  3. Return the build ID:

  4. $ adb shell grep build.id /system/build.prop
    ro.build.id=KOT49H

    This build ID is “KOT49H”. This identifies the version of the installed Android OS. You can use this data to pick the right Android OS version if you want to reinstall Android.

Tip: For convenience, run this command and the data is written to a file named mydevicedata:

$ adb shell grep ro.product.name /system/build.prop > mydevicedata \
&& adb shell grep build.id /system/build.prop >> mydevicedata \
&& adb shell grep ro.product.device /system/build.prop >> mydevicedata 

Here’s how the generated file may look:

$ cat mydevicedata
ro.product.name=razor
ro.build.id=KOT49H
ro.product.device=flo

Unlock the Android device

To install Ubuntu, you must first “unlock” the Android device bootloader.

Warning: Unlocking deletes all data from the device, including apps and other data. You may want to create a backup first.

You must first have enabled USB Debugging in the Android OS.

  1. Boot the device into the Android bootloader:
    $ adb reboot bootloader

    Tip: When the device is booted into the bootloader the screen displays the green Android robot lying on its back with its front panel open and a highlighted Start menu item.

  2. Verify the device is connected to your Ubuntu Desktop as follows:
    $ fastboot devices
    025d138e2f521413 fastboot
  3. Unlock the device as follows:
    $ sudo fastboot oem unlock
  4. Accept the terms of unlocking displayed on the Android device.
  5. Reboot the device to Android as follows:
    $ fastboot reboot
  6. Complete the first use Android setup steps, entering minimal information: Android and its data is about to be deleted during the Ubuntu install.

For help locking your device, see Reinstalling Android

Install Ubuntu on device

Here you take the final steps that install Ubuntu.

Select your device image channel

When you install, you need to name the Ubuntu device image channel used to obtain the image.

In most cases, you can simply use the devel channel, which gets the latest released image on the version of Ubuntu that is currently under development.

You may want an image based on the most recent released Ubuntu. That’s what the stable channel gets you: the most recent released Ubuntu for devices image that is based on the most recent Ubuntu release.

There are other channels too. For more information, see Ubuntu Image Channels.

For information on Ubuntu releases, see https://wiki.ubuntu.com/Releases

Tip: After installing, you can always switch to another channel.

Install Ubuntu

    1. Power the device off with the Power button.
    2. Reboot into the bootloader by pressing the correct physical button combination for your device type as shown here: https://source.android.com/source/building-devices.html#booting-into-fastboot-mode
    3. Install Ubuntu using your selected channel, in this case we use the devel channel:
      $ ubuntu-device-flash --channel=devel --bootstrap
      2014/04/16 10:19:26 Device is |flo|
      2014/04/16 10:19:27 Flashing version 296 from devel channel and server https://system-image.ubuntu.com to device flo
      2014/04/16 10:19:27 ubuntu-touch/trusty is a channel alias to devel
      
      [...]

      Tip: The –bootstrap option is normally only used when installing Ubuntu the first time. It requires that the device is booted to the bootloader. After Ubuntu is installed, one uses the ubuntu-device-flash command (without the –bootstrap option) while the device is booted to Ubuntu.

      1. Wait until the reboot is done. In most cases no input from you is required.The process takes some time. First, an appropriate image is downloaded to ~/.cache/ubuntuimages.

        Tip: Occasionally delete the cache of downloaded images (in ~/.cache/ubuntuimages) to free up disk space with: ubuntu-device-flash –clean-cache.

        Then, the parts of the images are deployed to the device. Ubuntu is deployed to the devices as a “recovery” image. Then, the device boots from the recovery image and installs Ubuntu as the normal OS. Finally, the device boots into Ubuntu for devices.

Upgrading Ubuntu

Upgrading automatically

After installing Ubuntu, upgrades to newly released images and apps are automatically provided through Settings > Updates.

Tip: You can configure such updates to never install automatically in Settings > Updates.

Upgrading manually

Note: The default channel used when none is explicitly stated is stable. In the following examples, CHANNEL indicates the channel your Ubuntu was installed from. See Display image channel information.

If you have configured the system to never install updates automatically, you can check for available updates and optionally install from Settings > Updates.

You can display information about what image would be installed if you were to upgrade:

$ adb shell system-image-cli --dry-run

You can manually initiate an upgrade:

$ ubuntu-device-flash --channel=CHANNEL

You can reinstall Ubuntu after deleting all user data and apps:

$ ubuntu-device-flash --wipe --channel=CHANNEL

Other image and install options

Switching Ubuntu image channel

You can switch channels and install from the new channel by specifying the new channel. For example, this switches to trusty-customized:

$ ubuntu-device-flash --channel=trusty-proposed

Installing a specific Ubuntu image version

You can specify the version of the Ubuntu image to install:

$ ubuntu-device-flash --channel=trusty --revision=299

Display image and channel information

You can display the current channel and other information:

$ adb shell system-image-cli -i
current build number: 299
device name: flo
channel: devel
alias: ubuntu-touch/trusty
last update: 2014-04-16 17:57:30
version version: 299
version ubuntu: 20140416
version device: 20140411.3

This device is on channel devel, which is shown to be currently an alias for trusty. The version is 299.

Enabling read-write mode

By default the system is read-only. You can switch to read-write mode, although this disables Ubuntu system upgrades. The main purpose for this is developing the Ubuntu system directly. This is not required for developing apps or using the system normally. Recovering from read-write mode is possible but requires reinstalling the system from scratch.

Warning: Switching a device to read-write mode (and/or recovering from it) is an advanced feature and may result in complete data loss.

Warning: Switching a device to read-write mode disables automatic over-the-air updates.

$ phablet-config writable-image

The system reboots in read-write mode.

Disabling read-write mode

You can disable read-write and restore automatic over-the-air updates:

$ adb shell rm /userdata/.writable_image

To restore the normally read-write protected system area to a pristine state that does not include any changes you made while in read-write mode by installing the Ubuntu system:

$ ubuntu-device-flash --channel=CHANNEL

Next steps

If you got lost somewhere, you found a bug or need some help, we’re happy to help you. Ubuntu for devices  is put together by a community of many people who are eager to work with you.