Getting the emulator

Minimal requirements for the emulator

  • 512MB of RAM dedicated for the emulator
  • 4GB of disk space
  • OpenGL capable desktop drivers (due the OpenGLES 2.0 translator)

Installing the pre-built emulator

/!\ If you are on amd64

  • A word of warning though: if you are on amd64, take care if you uninstall the emulator and run apt-get autoremove to automatically clean the dependencies, this will break your system. Issue was fixed with android-emulator 20131120-0225-0ubuntu2, but you could still have the issue (in case you installed a previous version of the emulator, so check if you have libc6-amd64 installed in your system).

If that happens to you:

From still running system, initramfs / break-bottom, or elsehow:

/lib/x86_64-linux-gnu/ld-2.18.so /bin/ln -s /lib/x86_64-linux-gnu/ld-2.18.so /lib64/ld-linux-x86-64.so.2

Alternatively you can do:

  1. reboot and eventually press shift to get to grub
  2. press e to edit your command line
  3. on the line "linux <…>", remove "quiet splash" and replace with break=bottom

  4. press F10 or Ctrl-x to start, you will be dropped in the initramfs busybox
  5. mkdir /mnt
  6. you need to know your FS layout and mount /dev/<your root partition> in /mnt

  7. cd /mnt/lib64/ && rm ld-linux-x86-64.so.2 && ln -s ../lib/x86_64-linux-gnu/ld-2.17.so ld-linux-x86-64.so.2

  8. reboot


  • Install the ubuntu-emulator package in Trusty
  • Create an instance
  • Run the emulator

sudo apt-get install ubuntu-emulator
sudo ubuntu-emulator create myinstance
ubuntu-emulator run myinstance


  • By default the latest built image from devel-proposed channel is used.
    • This can be changed during creation with the --channel and --revision options.
  • XDG_CACHE_DIR/ubuntuimage is used to download images; it is shared with ubuntu-device-flash.
  • Images are stored in XDG_DATA_DIR/ubuntu-emulator.
  • To update to a latest image; it is safe to create over the previous instance (upgrade option comming soon).
  • Once migrated to this ubuntu-emulator-images and android-emulator can be safely removed.
  • All references to run-emulator.sh and build-emulator-sdcard.sh do no apply anymore.
  • Snapshotting is taken care of with the snapshot subcommand from ubuntu-emulator.
  • If ubuntu-emulator run fails with libGL error: Couldn't dlopen libudev.so.1 or libudev.so.0, driver detection may be broken on amd64, this is bug:1291333. You can work around this by doing sudo apt-get install libudev1:i386


Until system-image works in the emulator, you can do the following to rebuild the image using the cached ubuntu-rootfs.tar.xz:

$ cd ~/emulator/
$ ./build-emulator-sdcard.sh

To update the image to the newest version of ubuntu-rootfs.tar.xz:

$ cd ~/emulator/
$ rm -f ./out/target/product/generic/ubuntu-rootfs.tar.xz
$ ./build-emulator-sdcard.sh

Building from scratch

To build

$ sudo apt-get install phablet-tools git bzr

$ # install android build-dependencies
$ sudo apt-get build-dep android

$ # if we're on amd64, we need to pull in certain 32-bit packages explicitly
$ sudo apt-get install libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-dev:i386 zlib1g-dev:i386

$ # this here is only needed if you didn't follow https://wiki.ubuntu.com/Touch/Porting before
$ sudo apt-get install schedtool openjdk-6-jdk g++-multilib bison flex

$ # and then work around the fact that libgl1-mesa-dev isn't Multi-Arch: same yet
$ sudo ln -s /usr/lib/x86_64-linux-gnu/mesa/libGL.so.1 /usr/lib/x86_64-linux-gnu/libGL.so

$ mkdir -p emulator/
$ phablet-dev-bootstrap emulator
$ cd emulator
$ source build/envsetup.sh
$ lunch cm_goldfish-eng
$ mka

To generate sdcard with the ubuntu rootfs

$ ./build/tools/build-emulator-sdcard.sh

Launch the emulator with the run-emulator script:

$ ./build/tools/run-emulator.sh

You can also launch the emulator using your own arguments and options:

$ emulator -verbose -gpu on -system $OUT/system.img -memory 512 -show-kernel -shell -no-jni -qemu -cpu cortex-a8

As of 2013/11/05 there is a bug in the goldfish kernel wrt AppArmor, so you may want to launch with AppArmor disabled until this issue is resolved:

$ emulator -verbose -gpu on -system $OUT/system.img -memory 512 -show-kernel -shell -no-jni -qemu -cpu cortex-a8 -append 'apparmor=0'

Username & password are:


To update your existing working tree to pull in new changes from the server, run repo sync.

For more information about how to use the repo command to manage your android working tree, see this page.

Using the emulator

After starting the emulator with the wrapper script following should be available:

  • Adb
    • Emulator will appear in the output of $ adb devices, and will, once fully booted allow
      $ adb shell
      access into ubuntu.
  • Serial console
    • The terminal will start an Ubuntu console by default, which can be used as any virtual console. Just be aware that hiiting Control + C will stop the emulator.
  • SSH access
    • SSH is enabled by default in the emulator, but you can only access it via localhost (QEMU handles the routes and NAT internally). All you need is to forward the target SSH port to a known port at your host:
      $ adb forward tcp:9999 tcp:22
      $ ssh phablet@localhost -p 9999
  • Telnet access
    • Once launched graphical window title will show a port number, e.g. 5554. Connect to that over telnet, to send hardware events to the emulator
      $ telnet 5554
      Connected to
      Escape character is '^]'.
      Android Console: type 'help' for a list of commands
      Android console command help:
          help|h|?         print a list of commands
          event            simulate hardware events
          geo              Geo-location commands
          gsm              GSM related commands
          cdma             CDMA related commands
          kill             kill the emulator instance
          network          manage network settings
          power            power related commands
          quit|exit        quit control session
          redir            manage port redirections
          sms              SMS related commands
          avd              control virtual device execution
          window           manage emulator window
          qemu             QEMU-specific commands
          sensor           manage emulator sensors
      try 'help <command>' for command-specific help
  • Autopilot
    1. Start up emulator with ubuntu-emulator as per above.

    2. Get emulator serial:
      • $ adb devices
        List of devices attached
        emulator-5554 device
        emulator-5556 device
    3. Pass -s emulator-XXXX to phablet-config and phablet-test* commands

    4. otherwise use same as described in https://wiki.ubuntu.com/Touch/Testing#Testing_your_Ubuntu_Touch_Code_before_submission, but without "phablet-flash" step for the time being.

Handling disk snapshots


ubuntu-emulator handles disk snapshots:

$ ubuntu-emulator snapshot --help
  ubuntu-emulator [OPTIONS] snapshot [snapshot-OPTIONS]

Create and revert to snapshots of the emulator instance name 'name' which was previously created

Help Options:
  -h, --help             Show this help message

Manipulates snapshots for emulator instance named 'name':
      --revert=          Reverts to the selected snapshot
      --create=          Creates the selected snapshot
      --revert-pristine  Reverts to the originally created snapshot

Help Options:
  -h, --help             Show this help message

Qcow2 images with snapshots are used by default when creating images with ubuntu-emulator create. The basic workflow is:

$ sudo ubuntu-emulator create trusty
$ ubuntu-emulator run trusty
<do work>
<shutdown or close the emulator with window/ctrl-c>
$ ubuntu-emulator snapshot --revert-pristine trusty
$ ubuntu-emulator run trusty
<perform tests in pristine environment>
<shutdown or close the emulator with window/ctrl-c>
$ ubuntu-emulator snapshot --revert-pristine trusty

Because a number of things happen on first boot after creating the image (or updating via system-image, which isn't supported yet, but will be), the first boot is very slow. You can workaround this by updating your pristine snapshot after your first boot, like so:

$ sudo ubuntu-emulator create trusty
$ ubuntu-emulator run trusty # first boot, be patient and wait until unity8 comes up
$ adb shell shutdown -h now  # wait until system is halted, then close the emulator with window/ctrl-c
$ ubuntu-emulator snapshot --create=pristine trusty

The above boots the emulator, cleanly shuts it down and then updates the pristine snapshot. See ubuntu-emulator snapshot --help for more details.

Legacy instructions

Since 20131126-0210-0ubuntu1, the run-emulator.sh script also supports disk snapshots.

Being able to create a snapshot and roll back to it is very useful for developers. Eg, developers can

  • develop features, etc on the image, then package them up, roll back the image and test on a pristine image
  • save time on system-image upgrade testing
  • do multiple test runs, reverting to the pristine image between runs to cut down on variances
  • verify bugs in the image easily
  • etc

Snapshotting can be complicated, but most of the time you just want to have a pristine snapshot that you can rollback to with the option of committing changes.

Run emulator usage:

$ ./run-emulator.sh help

Usage: run-emulator.sh
       run-emulator.sh [COMMAND]

 use-disk-snapshots Convert images to qcow2 and create 'pristine' snapshot
 convert-disk DISK Convert DISK to qcow2 and create 'pristine' snapshot
 snapshot-disks Update 'pristine' snapshot to current state
 revert-disks Revert current images to 'pristine' snapshot
 info-disks Show disk information for current images

Without arguments, run the emulated image.

Note: these commands only manipulate the qemu qcow2 disk images and are
      unrelated to the -snapshot* and -no-snapshot* emulator command line

Basic workflow:

$ ./build-emulator-sdcard.sh # create image like normal, skip if already have image
$ ./run-emulator.sh use-disk-snapshots
$ ./run-emulator.sh
<do work>
$ ./run-emulator.sh revert-disks
$ ./run-emulator.sh
<perform tests in pristine environment>
$ ./run-emulator.sh revert-disks

If need to rebuild the image after using snapshots:

$ for i in system.img userdata.img cache.img ; do cp -f /usr/share/android/emulator/out/target/product/generic/$i out/target/product/generic/ ; done
$ ./build-emulator-sdcard.sh

Keyboard Commands

Emulated Device Key

Keyboard Key

Power button


Audio volume up button


Audio volume down button


Switch to previous layout orientation (for example, portrait, landscape)

KEYPAD_7, Ctrl-F11

Switch to next layout orientation (for example, portrait, landscape)

KEYPAD_9, Ctrl-F12

Known Issues

  • Powerd is disabled by default as suspending & resuming corrupts the root filesystem.

  • A few other services might also be disabled by default until everything is working properly with the emulator. Please check build-emulator-sdcard.sh to see the extra customization done for the emulator image.

  • The first boot might take a few minutes as it generates the ssh key, install the click packages and so on. It shouldn't take too much though, always check with adb if the emulator is still running correctly (e.g. check with top).
  • It's quite common for Qemu to hang while booting (like an I/O-type hang), just abort and restart the emulator (still needs proper debugging).
  • If Unity8 fails to start, make sure your i386 GL driver is properly in place (check for error libGL.so.1: cannot open shared object file: No such file or directory when starting the emulator). If everything goes well, you should see 'qemu.gles=1' in the qemu kernel parameters.


Touch/Emulator (last edited 2014-03-12 12:04:08 by jdstrand)