1 page.title=Android Emulator 2 parent.title=Tools 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 9 <h2>In this document</h2> 10 <ol> 11 <li><a href="#startup-options">Emulator Startup Options</a></li> 12 <li><a href="#KeyMapping">Emulator Keyboard Mapping</a></li> 13 </ol> 14 15 <h2>See also</h2> 16 <ol> 17 <li><a href="{@docRoot}guide/developing/devices/emulator.html">Using the Android Emulator</a></li> 18 <li><a href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a></li> 19 </ol> 20 21 </div> 22 </div> 23 24 25 <p>The Android SDK includes a mobile device emulator — a virtual mobile device 26 that runs on your computer. The emulator lets you develop and test 27 Android applications without using a physical device.</p> 28 29 <p>When the emulator is running, you can interact with the emulated mobile 30 device just as you would an actual mobile device, except that you use your mouse 31 pointer to "touch" the touchscreen and can use some keyboard keys to 32 invoke certain keys on the device. </p> 33 34 <p>This document is a reference to the available command line options and the keyboard mapping to device keys. 35 For a complete guide to using the Android Emulator, see 36 <a href="{@docRoot}guide/developing/devices/emulator.html">Using the Android Emulator</a>. 37 38 39 <h2 id="startup-options">Emulator Startup Options</h2> 40 41 <p>The emulator supports a variety of options that you can specify 42 when launching the emulator, to control its appearance or behavior. 43 Here's the command-line usage for launching the emulator with options: </p> 44 45 <pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre> 46 47 <p class="table-caption"><strong>Table 1.</strong>Emulator startup options</p> 48 49 <table> 50 <tr> 51 <th width="10%" >Category</th> 52 <th width="20%" >Option</th> 53 <th width="30%" >Description</th> 54 <th width="40%" >Comments</th> 55 </tr> 56 57 <tr> 58 <td rowspan="9">Help</td> 59 <td><code>-help</code></td> 60 <td>Print a list of all emulator options.</td> 61 <td> </td> 62 </tr> 63 <tr> 64 <td><code>-help-all</code></td> 65 <td>Print help for all startup options.</td> 66 <td> </td> 67 </tr> 68 <tr> 69 <td><code>-help-<option></code></td> 70 <td>Print help for a specific startup option.</td> 71 <td> </td> 72 </tr> 73 <tr> 74 <td><code>-help-debug-tags</code></td> 75 <td>Print a list of all tags for <code>-debug <tags></code>.</td> 76 <td> </td> 77 </tr> 78 <tr> 79 <td><code>-help-disk-images</code></td> 80 <td>Print help for using emulator disk images.</td> 81 <td> </td> 82 </tr> 83 <tr> 84 <td><code>-help-environment</code></td> 85 <td>Print help for emulator environment variables.</td> 86 <td> </td> 87 </tr><tr> 88 <td><code>-help-keys</code></td> 89 <td>Print the current mapping of keys.</td> 90 <td> </td> 91 </tr> 92 <tr> 93 <td><code>-help-keyset-file</code></td> 94 <td>Print help for defining a custom key mappings file.</td> 95 <td> </td> 96 </tr> 97 <tr> 98 <td><code>-help-virtual-device</code></td> 99 <td>Print help for Android Virtual Device usage.</td> 100 <td> </td> 101 </tr> 102 <tr> 103 <td>AVD</td> 104 <td><code>-avd <avd_name></code> or <br> 105 <code>@<avd_name></code></td> 106 <td><strong>Required</strong>. Specifies the AVD to load for this emulator 107 instance.</td> 108 <td>You must create an AVD configuration before launching the emulator. For 109 information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html#createavd"> 110 Managing AVDs with AVD Manager</a>.</td> 111 <tr> 112 <td rowspan="7">Disk Images</td> 113 <td><code>-cache <filepath></code></td> 114 <td>Use <filepath> as the working cache partition image. </td> 115 <td>Optionally, you can specify a path relative to the current working directory. 116 If no cache file is specified, the emulator's default behavior is to use a temporary file instead. 117 <p>For more information on disk images, use <code>-help-disk-images</code>.</p> 118 </td></tr> 119 <tr> 120 <td><code>-data <filepath></code></td> 121 <td>Use <filepath> as the working user-data disk image. </td> 122 <td>Optionally, you can specify a path relative to the current working directory. 123 If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img" 124 in the storage area of the AVD being used (see <code>-avd</code>). 125 </td></tr> 126 <!-- 127 <tr> 128 <td><code>-datadir <dir></code></td> 129 <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td> 130 <td><code><dir></code> is a path relative to the current working directory. 131 132 <p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image 133 in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information 134 on disk images, use <code>-help-disk-images</code>.</p> 135 </td></tr> 136 --> 137 <!-- 138 <tr> 139 <td><code>-image <filepath></code></td> 140 <td>Use <filepath> as the system image.</td> 141 <td>Optionally, you can specify a path relative to the current working directory. 142 Default is <system>/system.img.</td> 143 </tr> 144 --> 145 <tr> 146 <td><code>-initdata <filepath></code></td> 147 <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents 148 of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td> 149 <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> 150 </tr> 151 <!-- 152 <tr> 153 <td><code>-kernel <filepath></code></td> 154 <td>Use <filepath> as the emulated kernel.</td> 155 <td>Optionally, you can specify a path relative to the current working directory. </td> 156 </tr> 157 --> 158 <tr> 159 <td><code>-nocache</code></td> 160 <td>Start the emulator without a cache partition.</td> 161 <td>See also <code>-cache <file></code>.</td> 162 </tr> 163 <tr> 164 <td><code>-ramdisk <filepath></code></td> 165 <td>Use <filepath> as the ramdisk image.</td> 166 <td>Default value is <code><system>/ramdisk.img</code>. 167 <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> 168 </td> 169 </tr> 170 <tr> 171 <td><code>-sdcard <filepath></code></td> 172 <td>Use <file> as the SD card image.</td> 173 <td>Default value is <code><system>/sdcard.img</code>. 174 <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> 175 </td> 176 </tr> 177 <!-- 178 <tr> 179 <td><code>-system <dirpath></code></td> 180 <td>Search for system, ramdisk and user data images in <dir>.</td> 181 <td><code><dir></code> is a directory path relative to the current 182 working directory.</td> 183 </tr> 184 --> 185 <tr> 186 <td><code>-wipe-data</code></td> 187 <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and 188 <code>-data</code>, or the default file). The emulator deletes all data from the user data image file, 189 then copies the contents of the file at <code>-inidata</code> data to the image file before starting. 190 </td> 191 <td>See also <code>-initdata</code>. 192 <p>For more information on disk images, use <code>-help-disk-images</code>.</p> 193 </td> 194 </tr> 195 <tr> 196 <td rowspan="9">Debug</td> 197 <td><code>-debug <tags></code></td> 198 <td>Enable/disable debug messages for the specified debug tags.</td> 199 <td><code><tags></code> is a space/comma/column-separated list of debug component names. 200 Use <code>-help-debug-tags</code> to print a list of debug component names that you can use. </td> 201 </tr> 202 <tr> 203 <td><code>-debug-<tag></code></td> 204 <td>Enable/disable debug messages for the specified debug tag.</td> 205 <td rowspan="2">Use <code>-help-debug-tags</code> to print a list of debug component names that you can use in <code><tag></code>. </td> 206 </tr> 207 <tr> 208 <td><code>-debug-no-<tag></code></td> 209 <td>Disable debug messages for the specified debug tag.</td> 210 </tr> 211 <tr> 212 <td><code>-logcat <logtags></code></td> 213 <td>Enable logcat output with given tags.</td> 214 <td>If the environment variable ANDROID_LOG_TAGS is defined and not 215 empty, its value will be used to enable logcat output by default.</td> 216 </tr> 217 <tr> 218 <td><code>-shell</code></td> 219 <td>Create a root shell console on the current terminal.</td> 220 <td>You can use this command even if the adb daemon in the emulated system is broken. 221 Pressing Ctrl-c from the shell stops the emulator instead of the shell.</td> 222 </tr> 223 <tr> 224 <td><code>-shell-serial <device></code></td> 225 <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character 226 device to use for communication with the shell.</td> 227 <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at 228 <a href="http://wiki.qemu.org/download/qemu-doc.html">wiki.qemu.org</a> 229 for more information.</p> 230 231 <p>Here are some examples: </p> 232 <ul> 233 <li><code>-shell-serial stdio</code> is identical to <code>-shell</code></li> 234 <li><code>-shell-serial tcp::4444,server,nowait</code> lets you communicate with the shell over TCP port 4444</li> 235 <li><code>-shell-serial fdpair:3:6</code> lets a parent process communicate with the shell using fds 3 (in) and 6 (out)</li> 236 <li><code>-shell-serial fdpair:0:1</code> uses the normal stdin and stdout fds, except that QEMU won't tty-cook the data.</li> 237 </ul> 238 </td> 239 </tr> 240 <tr> 241 <td><code>-show-kernel <name></code></td> 242 <td>Display kernel messages.</td> 243 <td> </td> 244 </tr> 245 <tr> 246 <td><code>-trace <name></code></td> 247 <td>Enable code profiling (press F9 to start), written to a specified file.</td> 248 <td> </td> 249 </tr> 250 <tr> 251 <td><code>-verbose</code></td> 252 <td>Enable verbose output.</td> 253 <td>Equivalent to <code>-debug-init</code>. 254 <p>You can define the default verbose output options used by emulator instances in the Android environment variable 255 ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option: 256 <code>-debug-<tags>.</code> </p> 257 <p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options: 258 <p><code>ANDROID_VERBOSE=init,modem</code></p> 259 <p>For more information about debug tags, use <code><-help-debug-tags></code>.</p> 260 </td> 261 </tr> 262 <tr> 263 <td rowspan="6">Media</td> 264 <td><code>-audio <backend></code></td> 265 <td>Use the specified audio backend.</td> 266 <td> </td> 267 </tr> 268 <tr> 269 <td><code>-audio-in <backend></code></td> 270 <td>Use the specified audio-input backend.</td> 271 <td> </td> 272 </tr> 273 <tr> 274 <td><code>-audio-out <backend></code></td> 275 <td>Use the specified audio-output backend.</td> 276 <td> </td> 277 </tr> 278 <!--<tr> 279 <td><code>-mic <device or file></code></td> 280 <td>Use device or WAV file for audio input.</td> 281 <td> </td> 282 </tr> 283 --> 284 <tr> 285 <td><code>-noaudio</code></td> 286 <td>Disable audio support in the current emulator instance.</td> 287 <td> </td> 288 </tr> 289 <tr> 290 <td><code>-radio <device></code></td> 291 <td>Redirect radio modem interface to a host character device.</td> 292 <td> </td></tr> 293 <tr> 294 <td><code>-useaudio</code></td> 295 <td>Enable audio support in the current emulator instance.</td> 296 <td>Enabled by default. </td> 297 </tr> 298 299 <tr> 300 <td rowspan="7">Network</td> 301 <td><code>-dns-server <servers></code></td> 302 <td>Use the specified DNS server(s). </td> 303 <td>The value of <code><servers></code> must be a comma-separated list of up to 4 DNS server names or 304 IP addresses.</td> 305 </tr> 306 <tr> 307 <td><code>-http-proxy <proxy></code></td> 308 <td>Make all TCP connections through a specified HTTP/HTTPS proxy</td> 309 <td>The value of <code><proxy></code> can be one of the following:<br> 310 <code>http://<server>:<port>;</code><br> 311 <code>http://<username>:<password>@<server>:<port>;</code> 312 <p>The <code>http://</code> prefix can be omitted. If the <code>-http-proxy <proxy></code> command is not supplied, 313 the emulator looks up the <code>http_proxy</code> environment variable and automatically uses any value matching 314 the <code><proxy></code> format described above.</p></td> 315 </tr> 316 <tr> 317 <td><code>-netdelay <delay></code></td> 318 <td>Set network latency emulation to <delay>.</td> 319 <td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for 320 supported <code><delay></code> values. </td> 321 </tr> 322 <tr> 323 <td><code>-netfast</code></td> 324 <td>Shortcut for <code>-netspeed full -netdelay none</code></td> 325 <td> </td></tr> 326 <tr> 327 <td><code>-netspeed <speed></code></td> 328 <td>Set network speed emulation to <speed>.</td> 329 <td>Default value is <code>full</code>. See the table in <a href="#netspeed">Network Speed Emulation</a> for 330 supported <code><speed></code> values. </td> 331 </tr> 332 <tr> 333 <td><code>-port <port></code></td> 334 <td>Set the console port number for this emulator instance to <code><port></code>.</td> 335 <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1 336 must also be free and will be reserved for ADB.</td> 337 </tr> 338 <tr> 339 <td><code>-report-console <socket></code></td> 340 <td>Report the assigned console port for this emulator instance to a remote third party 341 before starting the emulation. </td> 342 <td><code><socket></code> must use one of these formats: 343 344 <p><code>tcp:<port>[,server][,max=<seconds>]</code></br> 345 <code>unix:<port>[,server][,max=<seconds>]</code></p> 346 347 <p>Use <code>-help-report-console</code></p> to view more information about this topic. </td> 348 </tr> 349 <tr> 350 <td rowspan="8">System</td> 351 <td><code>-cpu-delay <delay></code></td> 352 <td>Slow down emulated CPU speed by <delay> </td> 353 <td>Supported values for <delay> are integers between 0 and 1000. 354 355 <p>Note that the <delay> does not correlate to clock speed or other absolute metrics 356 — it simply represents an abstract, relative delay factor applied non-deterministically 357 in the emulator. Effective performance does not always 358 scale in direct relationship with <delay> values.</p> 359 </td> 360 </tr> 361 <tr> 362 <td><code>-gps <device></code></td> 363 <td>Redirect NMEA GPS to character device.</td> 364 <td>Use this command to emulate an NMEA-compatible GPS unit connected to 365 an external character device or socket. The format of <code><device></code> must be QEMU-specific 366 serial device specification. See the documentation for 'serial -dev' at 367 <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. 368 </td> 369 </tr> 370 <tr> 371 <td><code>-nojni</code></td> 372 <td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr> 373 <tr> 374 <td><code>-qemu</code></td> 375 <td>Pass arguments to qemu.</td> 376 <td> </td></tr> 377 <tr> 378 <td><code>-qemu -h</code></td> 379 <td>Display qemu help.</td> 380 <td></td></tr> 381 <tr> 382 <td><code>-radio <device></code></td> 383 <td>Redirect radio mode to the specified character device.</td> 384 <td>The format of <code><device></code> must be QEMU-specific 385 serial device specification. See the documentation for 'serial -dev' at 386 <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. 387 </td> 388 </tr> 389 <tr> 390 <td><code>-timezone <timezone></code></td> 391 <td>Set the timezone for the emulated device to <timezone>, instead of the host's timezone.</td> 392 <td><code><timezone></code> must be specified in zoneinfo format. For example: 393 <p>"America/Los_Angeles"<br> 394 "Europe/Paris"</p> 395 </td> 396 </tr> 397 <tr> 398 <td><code>-version</code></td> 399 <td>Display the emulator's version number.</td> 400 <td> </td> 401 </tr> 402 <tr> 403 <td rowspan="12">UI</td> 404 <td><code>-dpi-device <dpi></code></td> 405 <td>Scale the resolution of the emulator to match the screen size 406 of a physical device.</td> 407 <td>The default value is 165. See also <code>-scale</code>.</td> 408 </tr> 409 <tr> 410 <td><code>-no-boot-anim</code></td> 411 <td>Disable the boot animation during emulator startup.</td> 412 <td>Disabling the boot animation can speed the startup time for the emulator.</td> 413 </tr> 414 <tr> 415 <td><code>-no-window</code></td> 416 <td>Disable the emulator's graphical window display.</td> 417 <td> </td> 418 </tr> 419 <tr> 420 <td><code>-scale <scale></code></td> 421 <td>Scale the emulator window. </td> 422 <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can 423 also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" 424 tells the emulator to select the best window size.</td> 425 </tr> 426 <tr> 427 <td><code>-raw-keys</code></td> 428 <td>Disable Unicode keyboard reverse-mapping.</td> 429 <td> </td></tr> 430 <tr> 431 <td><code>-noskin</code></td> 432 <td>Don't use any emulator skin.</td> 433 <td> </td></tr> 434 <tr> 435 <td><code>-keyset <file></code></td> 436 <td>Use the specified keyset file instead of the default.</td> 437 <td>The keyset file defines the list of key bindings between the emulator and the host keyboard. 438 For more information, use <code>-help-keyset</code> to print information about this topic. 439 </td> 440 </tr> 441 <tr> 442 <td><code>-onion <image></code></td> 443 <td>Use overlay image over screen.</td> 444 <td>No support for JPEG. Only PNG is supported.</td></tr> 445 <tr> 446 <td><code>-onion-alpha <percent></code></td> 447 <td>Specify onion skin translucency value (as percent). 448 <td>Default is 50.</td> 449 </tr> 450 <tr> 451 <td><code>-onion-rotation <position></code></td> 452 <td>Specify onion skin rotation. 453 <td><code><position></code> must be one of the values 0, 1, 2, 3.</td> 454 </tr> 455 <tr> 456 <td><code>-skin <skinID></code></td> 457 <td>This emulator option is deprecated. </td> 458 <td>Please set skin options using AVDs, rather than by using this emulator 459 option. Using this option may yield unexpected and in some cases misleading 460 results, since the density with which to render the skin may not be defined. 461 AVDs let you associate each skin with a default density and override the default 462 as needed. For more information, see <a 463 href="{@docRoot}guide/developing/devices/managing-avds.html#createavd"> 464 Managing Virtual Devices with AVD Manager</a>. 465 </td> 466 </tr> 467 <tr> 468 <td><code>-skindir <dir></code></td> 469 <td>This emulator option is deprecated. </td> 470 <td>See comments for <code>-skin</code>, above.</td></tr> 471 </table> 472 473 474 475 <h2 id="KeyMapping">Emulator Keyboard Mapping</h2> 476 477 <p>The table below summarizes the mappings between the emulator keys and and 478 the keys of your keyboard. </p> 479 <p class="table-caption"><strong>Table 2.</strong> Emulator keyboard mapping</p> 480 <table border="0" style="clear:left;"> 481 <tr> 482 <th>Emulated Device Key </th> 483 <th>Keyboard Key </th> 484 </tr> 485 <tr> 486 <td>Home</td> 487 <td>HOME</td> 488 </tr> 489 <tr> 490 <td>Menu (left softkey)</td> 491 <td>F2 <em>or</em> Page-up button</td> 492 </tr> 493 <tr> 494 <td>Star (right softkey)</td> 495 <td>Shift-F2 <em>or </em>Page Down</td> 496 </tr> 497 <tr> 498 <td>Back</td> 499 <td>ESC</td> 500 </tr> 501 <tr> 502 <td>Call/dial button </td> 503 <td>F3</td> 504 </tr> 505 <tr> 506 <td>Hangup/end call button</td> 507 <td>F4</td> 508 </tr> 509 <tr> 510 <td>Search</td> 511 <td>F5 </td> 512 </tr> 513 <tr> 514 <td>Power button</td> 515 <td>F7 </td> 516 </tr> 517 <tr> 518 <td>Audio volume up button</td> 519 <td>KEYPAD_PLUS, Ctrl-5</td> 520 </tr> 521 522 <tr> 523 <td>Audio volume down button</td> 524 <td>KEYPAD_MINUS, Ctrl-F6</td> 525 </tr> 526 <tr> 527 <td>Camera button</td> 528 <td>Ctrl-KEYPAD_5, Ctrl-F3</td> 529 </tr> 530 <tr> 531 <td>Switch to previous layout orientation (for example, portrait, landscape)</td> 532 <td>KEYPAD_7, Ctrl-F11</td> 533 </tr> 534 <tr> 535 <td>Switch to next layout orientation (for example, portrait, landscape)</td> 536 <td>KEYPAD_9, Ctrl-F12</td> 537 </tr> 538 <tr> 539 <td>Toggle cell networking on/off</td> 540 <td>F8</td> 541 </tr> 542 <tr> 543 <td>Toggle code profiling</td> 544 <td>F9 (only with <code>-trace</code> startup option)</td> 545 </tr> 546 <tr> 547 <td>Toggle fullscreen mode</td> 548 <td>Alt-Enter</td> 549 </tr> 550 <tr> 551 <td>Toggle trackball mode</td> 552 <td>F6</td> 553 </tr> 554 <tr> 555 <td>Enter trackball mode temporarily (while key is pressed)</td> 556 <td>Delete</td> 557 </tr> 558 <tr> 559 <td>DPad left/up/right/down</td> 560 <td>KEYPAD_4/8/6/2</td> 561 </tr> 562 <tr> 563 <td>DPad center click</td> 564 <td>KEYPAD_5</td> 565 </tr> 566 <tr> 567 <td>Onion alpha increase/decrease</td> 568 <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td> 569 </tr> 570 </table> 571 572 <p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p> 573
