use '-sysdir ' to specify a directory where system read-only image files will be searched. on this system, the default directory is:
/mnt/sdc1/android-sdk-linux_x86/tools/lib/images
see '-help-disk-images' for more information about disk image files
========= help for option -system:
use '-system ' to specify the intial system image that will be loaded. the default image is 'system.img' from the system directory.
NOTE: In previous releases of the Android SDK, this option was named '-image'. And using '-system ' was equivalent to using '-sysdir ' now.
see '-help-disk-images' for more information about disk image files
========= help for option -datadir:
use '-datadir ' to specify a directory where writable image files will be searched. on this system, the default directory is:
/home/xuming/.android
see '-help-disk-images' for more information about disk image files
========= help for option -kernel:
use '-kernel ' to specify a Linux kernel image to be run. the default image is 'kernel-qemu' from the system directory.
you can use '-debug-kernel' to see debug messages from the kernel to the terminal
see '-help-disk-images' for more information about disk image files
========= help for option -ramdisk:
use '-ramdisk ' to specify a Linux ramdisk boot image to be run in the emulator. the default image is 'ramdisk.img' from the system directory.
see '-help-disk-images' for more information about disk image files
========= help for option -image:
This option is obsolete, you should use '-system ' instead to point to the initial system image.
see '-help-disk-images' for more information about disk image files
========= help for option -initdata:
same as '-init-data '========= help for option -data:
use '-data ' to specify a different /data partition image file.
see '-help-disk-images' for more information about disk image files
========= help for option -partition_size:
system/data partition size in MBs========= help for option -cache:
use '-cache ' to specify a /cache partition image. if does not exist, it will be created empty. by default, the cache partition is backed by a temporary file that is deleted when the emulator exits. using the -cache option allows it to be persistent.
the '-no-cache' option can be used to disable the cache partition.
see '-help-disk-images' for more information about disk image files
========= help for option -no_cache:
use '-no-cache' to disable the cache partition in the emulated system. the cache partition is optional, but when available, is used by the browser to cache web pages and images
see '-help-disk-images' for more information about disk image files
========= help for option -nocache:
same as -no-cache========= help for option -sdcard:
use '-sdcard ' to specify a SD Card image file that will be attached to the emulator. By default, the 'sdcard.img' file is searched in the data directory.
if the file does not exist, the emulator will still start, but without an attached SD Card.
see '-help-disk-images' for more information about disk image files
========= help for option -snapstorage:
Use '-snapstorage ' to specify a repository file for snapshots. All snapshots made during execution will be saved in this file, and only snapshots in this file can be restored during the emulator run.
If the option is not specified, it defaults to 'snapshots.img' in the data directory. If the specified file does not exist, the emulator will start, but without support for saving or loading state snapshots.
see '-help-disk-images' for more information about disk image files see '-help-snapshot' for more information about snapshots
========= help for option -no_snapstorage:
This starts the emulator without mounting a file to store or load state snapshots, forcing a full boot and disabling state snapshot functionality.
This command overrides the configuration specified by the parameters '-snapstorage' and '-snapshot'. A warning will be raised if either of those parameters was specified anyway.
========= help for option -snapshot:
Rather than executing a full boot sequence, the Android emulator can resume execution from an earlier state snapshot (which is usually significantly faster). When the parameter '-snapshot ' is given, the emulator loads the snapshot of that name from the snapshot image, and saves it back under the same name on exit.
If the option is not specified, it defaults to 'default-boot'. If the specified snapshot does not exist, the emulator will perform a full boot sequence instead, but will still save.
WARNING: In the process of loading, all contents of the system, userdata and SD card images will be OVERWRITTEN with the contents they held when the snapshot was made. Unless saved in a different snapshot, any changes since will be lost!
If you want to create a snapshot manually, connect to the emulator console:
telnet localhost
Then execute the command 'avd snapshot save '. See '-help-port' for information on obtaining .
========= help for option -no_snapshot:
This inhibits both the autoload and autosave operations, forcing emulator to perform a full boot sequence and losing state on close. It overrides the '-snapshot' parameter. If '-snapshot' was specified anyway, a warning is raised.
========= help for option -no_snapshot_save:
Prevents the emulator from saving the AVD's state to the snapshot storage on exit, meaning that all changes will be lost.
========= help for option -no_snapshot_load:
Prevents the emulator from loading the AVD's state from the snapshot storage on start.
========= help for option -snapshot_list:
This prints a table of snapshots that are stored in the snapshot storage file that the emulator was started with, then exits. Values from the 'ID' and 'TAG' columns can be used as arguments for the '-snapshot' parameter.
If '-snapstorage ' was specified as well, this command prints a table of the snapshots stored in .
See '-help-snapshot' for more information on snapshots.
========= help for option -no_snapshot_update_time:
Prevent the emulator from sending an unsolicited time update in response to the first signal strength query after loadvm, to avoid a sudden time jump that might upset testing. (Signal strength is queried approximately every 15 seconds)
========= help for option -wipe_data:
use '-wipe-data' to reset your /data partition image to its factory defaults. this removes all installed applications and settings.
see '-help-disk-images' for more information about disk image files
========= help for option -avd:
use '-avd ' to start the emulator program with a given Android Virtual Device (a.k.a. AVD), where must correspond to the name of one of the existing AVDs available on your host machine.
See -help-virtual-device to learn how to create/list/manage AVDs.
As a special convenience, using '@' is equivalent to using '-avd '.
========= help for option -skindir:
use '-skindir ' to specify a directory that will be used to search for emulator skins. each skin must be a subdirectory of . by default the emulator will look in the 'skins' sub-directory of the system directory
the '-skin ' option is required when -skindir is used. ========= help for option -skin:
use '-skin ' to specify an emulator skin, each skin corresponds to the visual appearance of a given device, including buttons and keyboards, and is stored as subdirectory of the skin root directory (see '-help-skindir')
note that can also be 'x' (e.g. '320x480') to specify an exact framebuffer size, without any visual ornaments.
========= help for option -no_skin:
don't use any emulator skin========= help for option -noskin:
same as -no-skin========= help for option -memory:
physical RAM size in MBs========= help for option -netspeed:
the Android emulator supports network throttling, i.e. slower network bandwidth as well as higher connection latencies. this is done either through skin configuration, or with '-netspeed ' and '-netdelay '.
the format of -netspeed is one of the following (numbers are kbits/s):
-netspeed select both upload and download speed -netspeed : select individual up and down speed
The format of -netdelay is one of the following (numbers are msec):
-netdelay gprs GPRS (min 150, max 550) -netdelay edge EDGE/EGPRS (min 80, max 400) -netdelay umts UMTS/3G (min 35, max 200) -netdelay none no latency (min 0, max 0) -netdelay select exact latency -netdelay : select min and max latencies
the emulator uses the following defaults:
Default network speed is 'full' Default network latency is 'none'
========= help for option -netdelay:
the Android emulator supports network throttling, i.e. slower network bandwidth as well as higher connection latencies. this is done either through skin configuration, or with '-netspeed ' and '-netdelay '.
the format of -netspeed is one of the following (numbers are kbits/s):
-netspeed select both upload and download speed -netspeed : select individual up and down speed
The format of -netdelay is one of the following (numbers are msec):
-netdelay gprs GPRS (min 150, max 550) -netdelay edge EDGE/EGPRS (min 80, max 400) -netdelay umts UMTS/3G (min 35, max 200) -netdelay none no latency (min 0, max 0) -netdelay select exact latency -netdelay : select min and max latencies
the emulator uses the following defaults:
Default network speed is 'full' Default network latency is 'none'
========= help for option -netfast:
the Android emulator supports network throttling, i.e. slower network bandwidth as well as higher connection latencies. this is done either through skin configuration, or with '-netspeed ' and '-netdelay '.
the format of -netspeed is one of the following (numbers are kbits/s):
-netspeed select both upload and download speed -netspeed : select individual up and down speed
The format of -netdelay is one of the following (numbers are msec):
-netdelay gprs GPRS (min 150, max 550) -netdelay edge EDGE/EGPRS (min 80, max 400) -netdelay umts UMTS/3G (min 35, max 200) -netdelay none no latency (min 0, max 0) -netdelay select exact latency -netdelay : select min and max latencies
the emulator uses the following defaults:
Default network speed is 'full' Default network latency is 'none'
========= help for option -trace:
use '-trace ' to start the emulator with runtime code profiling support profiling itself will not be enabled unless you press F9 to activate it, or the executed code turns it on programmatically.
trace information is stored in directory , several files are created there, that can later be used with the 'traceview' program that comes with the Android SDK for analysis.
note that execution will be slightly slower when enabling code profiling, this is a necessary requirement of the operations being performed to record the execution trace. this slowdown should not affect your system until you enable the profiling though...
========= help for option -show_kernel:
use '-show-kernel' to redirect debug messages from the kernel to the current terminal. this is useful to check that the boot process works correctly.
========= help for option -shell:
use '-shell' to create a root shell console on the current terminal. this is unlike the 'adb shell' command for the following reasons:
* this is a *root* shell that allows you to modify many parts of the system * this works even if the ADB daemon in the emulated system is broken * pressing Ctrl-C will stop the emulator, instead of the shell.
See also '-shell-serial'.
========= help for option -no_jni:
disable JNI checks in the Dalvik runtime========= help for option -nojni:
same as -no-jni========= help for option -logcat:
use '-logcat ' to redirect log messages from the emulated system to the current terminal. is a list of space/comma-separated log filters where each filter has the following format:
:
where is either '*' or the name of a given component, and is one of the following letters:
v verbose level d debug level i informative log level w warning log level e error log level s silent log level
for example, the following only displays messages from the 'GSM' component that are at least at the informative level:
-logcat '*:s GSM:i'
if '-logcat ' is not used, the emulator looks for ANDROID_LOG_TAGS in the environment. if it is defined, its value must match the format and will be used to redirect log messages to the terminal.
note that this doesn't prevent you from redirecting the same, or other, log messages through the ADB or DDMS tools too.
========= help for option -no_audio:
use '-no-audio' to disable all audio support in the emulator. this may be unfortunately be necessary in some cases:
* at least two users have reported that their Windows machine rebooted instantly unless they used this option when starting the emulator. it is very likely that the problem comes from buggy audio drivers.
* on some Linux machines, the emulator might get stuck at startup with audio support enabled. this problem is hard to reproduce, but seems to be related too to flaky ALSA / audio driver support.
on Linux, another option is to try to change the default audio backend used by the emulator. you can do that by setting the QEMU_AUDIO_DRV environment variables to one of the following values:
alsa (use the ALSA backend) esd (use the EsounD backend) sdl (use the SDL audio backend, no audio input supported) oss (use the OSS backend) none (do not support audio)
the very brave can also try to use distinct backends for audio input and audio outputs, this is possible by selecting one of the above values into the QEMU_AUDIO_OUT_DRV and QEMU_AUDIO_IN_DRV environment variables.
========= help for option -noaudio:
same as -no-audio========= help for option -audio:
the '-audio ' option allows you to select a specific backend to be used to both play and record audio in the Android emulator.
use '-audio none' to disable audio completely.
========= help for option -raw_keys:
this option is deprecated because one can do the same using Ctrl-K at runtime (this keypress toggles between unicode/raw keyboard modes)
by default, the emulator tries to reverse-map the characters you type on your keyboard to device-specific key presses whenever possible. this is done to make the emulator usable with a non-QWERTY keyboard.
however, this also means that single keypresses like Shift or Alt are not passed to the emulated device. the '-raw-keys' option disables the reverse mapping. it should only be used when using a QWERTY keyboard on your machine (should only be useful to Android system hackers, e.g. when implementing a new input method).
========= help for option -radio:
use '-radio ' to redirect the GSM modem emulation to an external character device or program. this bypasses the emulator's internal modem and should only be used for testing.
see '-help-char-devices' for the format of
the data exchanged with the external device/program are GSM AT commands
note that, when running in the emulator, the Android GSM stack only supports a *very* basic subset of the GSM protocol. trying to link the emulator to a real GSM modem is very likely to not work properly.
========= help for option -port:
at startup, the emulator tries to bind its control console at a free port starting from 5554, in increments of two (i.e. 5554, then 5556, 5558, etc..) this allows several emulator instances to run concurrently on the same machine, each one using a different console port number.
use '-port ' to force an emulator instance to use a given console port
note that must be an *even* integer between 5554 and 5584 included. +1 must also be free and will be reserved for ADB. if any of these ports is already used, the emulator will fail to start.
========= help for option -ports:
the '-ports ,' option allows you to explicitely set the TCP ports used by the emulator to implement its control console and communicate with the ADB tool.
This is a very special option that should probably *not* be used by typical developers using the Android SDK (use '-port ' instead), because the corresponding instance is probably not going to be seen from adb/DDMS. Its purpose is to use the emulator in very specific network configurations.
is the TCP port used to bind the control console is the TCP port used to bind the ADB local transport/tunnel.
If both ports aren't available on startup, the emulator will exit.
========= help for option -onion:
use '-onion ' to specify a PNG image file that will be displayed on top of the emulated framebuffer with translucency. this can be useful to check that UI elements are correctly positioned with regards to a reference graphics specification.
the default translucency is 50%, but you can use '-onion-alpha <%age>' to select a different one, or even use keypresses at runtime to alter it (see -help-keys for details)
finally, the onion image can be rotated (see -help-onion-rotate)
========= help for option -onion_alpha:
use '-onion-alpha ' to change the translucency level of the onion image that is going to be displayed on top of the framebuffer (see also -help-onion). the default is 50%.
must be an integer between 0 and 100.
you can also change the translucency dynamically (see -help-keys)
========= help for option -onion_rotation:
use '-onion-rotation ' to change the rotation of the onion image loaded through '-onion '. valid values for are:
the '-scale ' option is used to scale the emulator window to something that better fits the physical dimensions of a real device. this can be *very* useful to check that your UI isn't too small to be usable on a real device.
there are three supported formats for :
* if is a real number (between 0.1 and 3.0) it is used as a scaling factor for the emulator's window.
* if is an integer followed by the suffix 'dpi' (e.g. '110dpi'), then it is interpreted as the resolution of your monitor screen. this will be divided by the emulated device's resolution to get an absolute scale. (see -help-dpi-device for details).
* finally, if is the keyword 'auto', the emulator tries to guess your monitor's resolution and automatically adjusts its window accordingly
NOTE: this process is *very* unreliable, depending on your OS, video driver issues and other random system parameters
the emulator's scale can be changed anytime at runtime through the control console. see the help for the 'window scale' command for details
========= help for option -dpi_device:
use '-dpi-device ' to specify the screen resolution of the emulated device. must be an integer between 72 and 1000. the default is taken from the skin, if available, or uses the contant value 165 (an average of several prototypes used during Android development).
the device resolution can also used to rescale the emulator window with the '-scale' option (see -help-scale)
========= help for option -http_proxy:
the Android emulator allows you to redirect all TCP connections through a HTTP/HTTPS proxy. this can be enabled by using the '-http-proxy ' option, or by defining the 'http_proxy' environment variable.
can be one of the following:
the 'http://' prefix can be omitted. If '-http-proxy ' is not used, the 'http_proxy' environment variable is looked up and any value matching the format will be used automatically
========= help for option -timezone:
by default, the emulator tries to detect your current timezone to report it to the emulated system. use the '-timezone ' option to choose a different timezone, or if the automatic detection doesn't work correctly.
VERY IMPORTANT NOTE:
the value must be in zoneinfo format, i.e. it should look like Area/Location or even Area/SubArea/Location. valid examples are:
America/Los_Angeles Europe/Paris
using a human-friendly abbreviation like 'PST' or 'CET' will not work, as well as using values that are not defined by the zoneinfo database.
NOTE: unfortunately, this will not work on M5 and older SDK releases
========= help for option -dns_server:
by default, the emulator tries to detect the DNS servers you're using and will setup special aliases in the emulated firewall network to allow the Android system to connect directly to them. use '-dns-server ' to select a different list of DNS servers to be used.
must be a comma-separated list of up to 4 DNS server names or IP addresses.
NOTE: on M5 and older SDK releases, only the first server in the list will be used.
========= help for option -cpu_delay:
this option is purely experimental, probably doesn't work as you would expect, and may even disappear in a later emulator release.
use '-cpu-delay ' to throttle CPU emulation. this may be useful to detect weird race conditions that only happen on 'lower' CPUs. note that is a unit-less integer that doesn't even scale linearly to observable slowdowns. use trial and error to find something that suits you, the 'correct' machine is very probably dependent on your host CPU and memory anyway...
========= help for option -no_boot_anim:
use '-no-boot-anim' to disable the boot animation (red bouncing ball) when starting the emulator. on slow machines, this can surprisingly speed up the boot sequence in tremendous ways.
NOTE: unfortunately, this will not work on M5 and older SDK releases
========= help for option -no_window:
disable graphical window display========= help for option -version:
display emulator version number========= help for option -report_console:
the '-report-console ' option can be used to report the automatically-assigned console port number to a remote third-party before starting the emulation. must be in one of these formats:
tcp:[,server][,max=] unix:[,server][,max=]
if the 'server' option is used, the emulator opens a server socket and waits for an incoming connection to it. by default, it will instead try to make a normal client connection to the socket, and, in case of failure, will repeat this operation every second for 10 seconds. the 'max=' option can be used to modify the timeout
when the connection is established, the emulator sends its console port number as text to the remote third-party, then closes the connection and starts the emulation as usual. *any* failure in the process described here will result in the emulator aborting immediately
as an example, here's a small Unix shell script that starts the emulator in the background and waits for its port number with the help of the 'netcat' utility:
use '-gps ' to emulate an NMEA-compatible GPS unit connected to an external character device or socket. the format of is the same than the one used for '-radio ' (see -help-char-devices for details)
========= help for option -keyset:
use '-keyset ' to specify a different keyset file name to use when starting the emulator. a keyset file contains a list of key bindings used to control the emulator with the host keyboard.
by default, the emulator looks for the following file:
/home/xuming/.android/default.keyset
however, if -keyset is used, then the emulator does the following:
- first, if doesn't have an extension, then the '.keyset' suffix is appended to it (e.g. "foo" => "foo.keyset"),
- then, the emulator searches for a file named in the following directories:
* the emulator configuration directory: /home/xuming/.android * the 'keysets' subdirectory of , if any * the 'keysets' subdirectory of the program location, if any
if no corresponding file is found, a default set of key bindings is used.
use '-help-keys' to list the default key bindings. use '-help-keyset-file' to learn more about the format of keyset files.
========= help for option -shell_serial:
use '-shell-serial ' instead of '-shell' to open a root shell to the emulated system, while specifying an external communication channel / host device.
'-shell-serial stdio' is identical to '-shell', while you can use '-shell-serial tcp::4444,server,nowait' to talk to the shell over local TCP port 4444. '-shell-serial fdpair:3:6' would let a parent process talk to the shell using fds 3 and 6.
see -help-char-devices for a list of available specifications.
NOTE: you can have only one shell per emulator instance at the moment
========= help for option -old_system:
use '-old-system' if you want to use a recent emulator binary to run an old version of the Android SDK system images. Here, 'old' means anything older than version 1.4 of the emulator.
NOTE: using '-old-system' with recent system images is likely to not work properly, though you may not notice it immediately (e.g. failure to start the emulated GPS hardware)
========= help for option -tcpdump:
use the -tcpdump option to start capturing all network packets that are sent through the emulator's virtual Ethernet LAN. You can later use tools like WireShark to analyze the traffic and understand what really happens.
note that this captures all Ethernet packets, and is not limited to TCP connections.
you can also start/stop the packet capture dynamically through the console; see the 'network capture start' and 'network capture stop' commands for details.
========= help for option -bootchart:
some Android system images have a modified 'init' system that integrates a bootcharting facility (see ). You can pass a bootcharting period to the system with the following:
-bootchart
where 'timeout' is a period expressed in seconds. Note that this won't do anything if your init doesn't have bootcharting activated.
========= help for option -charmap:
use '-charmap ' to use key character map specified in that file. must be a full path to a kcm file, containing desired character map.
========= help for option -prop:
use '-prop =' to set a boot-time system property. must be a property name of at most 32 characters, without any space in it, and must be a string of at most 92 characters.
the corresponding system property will be set at boot time in the emulated system. This can be useful for debugging purposes.
note that you can use several -prop options to define more than one boot property.
========= help for option -shared_net_id:
Normally, Android instances running in the emulator cannot talk to each other directly, because each instance is behind a virtual router. However, sometimes it is necessary to test the behaviour of applications if they are directly exposed to the network.
This option instructs the emulator to join a virtual network shared with emulators also using this option. The number given is used to construct the IP address 10.1.2., which is bound to a second interface on the emulator. Each emulator must use a different number.
========= help for option -nand_limits:
use '-nand-limits ' to enable a debugging feature that sends a signal to an external process once a read and/or write limit is achieved in the emulated system. the format of is the following:
pid=,signal=,[reads=][,writes=]
where 'pid' is the target process identifier, 'signal' the number of the target signal. the read and/or write threshold'reads' are a number optionally followed by a K, M or G suffix, corresponding to the number of bytes to be read or written before the signal is sent.
========= help for option -memcheck:
use '-memcheck ' to start the emulator with memory access checking support.
enables, or disables memory access checking, and also controls what events are going to be logged by the memory access checker. can be one of the following: 1 - Enables memory access checking with default logging ("LIRW"), or 0 - Disables memory access checking, or A combination (in no particular order) of the following: L - Logs memory leaks on process exit. I - Logs attempts to use invalid pointers in free, or realloc routines. R - Logs memory access violation on read operations. W - Logs memory access violation on write operations. N - Logs new process ID allocation. F - Logs guest's process forking. S - Logs guest's process starting. E - Logs guest's process exiting. C - Logs guest's thread creation (clone). B - Logs libc.so initialization in the guest system. M - Logs module mapping and unmapping in the guest system. A - Logs all emulator events. Equala to "LIRWFSECANBM" combination. e - Logs error messages, received from the guest system. d - Logs debug messages, received from the guest system. i - Logs information messages, received from the guest system. a - Logs all messages, received from the guest system. This is equal to "edi" combination.
note that execution might be significantly slower when enabling memory access checking, this is a necessary requirement of the operations being performed to analyze memory allocations and memory access.
========= help for -help-disk-images
The emulator needs several key image files to run appropriately. Their exact location depends on whether you're using the emulator from the Android SDK, or not (more details below).
The minimal required image files are the following:
kernel-qemu the emulator-specific Linux kernel image ramdisk.img the ramdisk image used to boot the system system.img the *initial* system image userdata.img the *initial* data partition image
It will also use the following writable image files:
userdata-qemu.img the persistent data partition image system-qemu.img an *optional* persistent system image cache.img an *optional* cache partition image sdcard.img an *optional* SD Card partition image
snapshots.img an *optional* state snapshots image
If you use a virtual device, its content directory should store all writable images, and read-only ones will be found from the corresponding platform/add-on directories. See -help-sdk-images for more details.
If you are building from the Android build system, you should have ANDROID_PRODUCT_OUT defined in your environment, and the emulator shall be able to pick-up the right image files automatically. See -help-build-images for more details.
If you're neither using the SDK or the Android build system, you can still run the emulator by explicitely providing the paths to *all* required disk images through a combination of the following options: -sysdir, -datadir, -kernel, -ramdisk, -system, -data, -cache -sdcard and -snapstorage.
The actual logic being that the emulator should be able to find all images from the options you give it.
