1page.title=Android Virtual Devices 2@jd:body 3 4<div id="qv-wrapper"> 5<div id="qv"> 6 7 <h2>AVD quickview</h2> 8 <ul> 9 <li>You need to create an AVD to run any app in the Android emulator</li> 10 <li>Each AVD is a completely independent virtual device, with its own 11 hardware options, system image, and data storage. 12 <li>You create AVD configurations to model different device environments 13 in the Android emulator.</li> 14 <li>The <code>android</code> tool offers a graphical Android AVD 15 Manager and a command-line interface for creating AVDs.</li> 16 </ul> 17 <h2>In this document</h2> 18 <ol> 19 <li><a href="#creating">Creating an AVD</a> 20 <ol> 21 <li><a href="#listingtargets">Listing targets</a></li> 22 <li><a href="#selectingtarget">Selecting a target</a></li> 23 <li><a href="#createavd">Creating the AVD</a></li> 24 <li><a href="#hardwareopts">Setting hardware emulation options</a></li> 25 <li><a href="#location">Default location of the AVD files</a></li> 26 </ol> 27 </li> 28 <li><a href="#managing">Managing AVDs</a> 29 <ol> 30 <li><a href="#moving">Moving an AVD</a></li> 31 <li><a href="#updating">Updating an AVD</a></li> 32 <li><a href="#deleting">Deleting an AVD</a></li> 33 </ol> 34 </li> 35 <li><a href="#options">Command-line options</a></li> 36 </ol> 37 <h2>See Also</h2> 38 <ol> 39 <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android 40 Emulator</a></li> 41 </ol> 42</div> 43</div> 44 45<p>Android Virtual Devices (AVDs) are configurations of emulator options that let 46you better model an actual device.</p> 47 48<p>Each AVD is made up of: </p> 49 50<ul> 51<li>A hardware profile. You can set options to define the hardware 52features of the virtual device. For example, you can define whether the device 53has a camera, whether it uses a physical QWERTY keyboard or a dialing pad, how 54much memory it has, and so on. </li> 55<li>A mapping to a system image. You can define what version of the 56Android platform will run on the virtual device. You can choose a version of the 57standard Android platform or the system image packaged with an SDK add-on.</li> 58<li>Other options. You can specify the emulator skin you want to use 59with the AVD, which lets you control the screen dimensions, appearance, and so 60on. You can also specify the emulated SD card to use with the AVD.</li> 61<li>A dedicated storage area on your development machine, in which is stored the 62device's user data (installed applications, settings, and so on) and emulated SD 63card.</li> 64</ul> 65 66<p>You can create as many AVDs as you need, based on the types of devices you 67want to model and the Android platforms and external libraries you want to run 68your application on. </p> 69 70<p>In addition to the options in an AVD configuration, you can also 71specify emulator command-line options at launch or by using the emulator 72console to change behaviors or characteristics at run time. For a complete 73reference of emulator options, please see the <a 74href="{@docRoot}guide/developing/tools/emulator.html">Emulator</a> 75documentation. </p> 76 77<p>To create and manage AVDs, you use the <code>android</code> tool provided in 78the <code>tools/</code> directory of the Android SDK. The tool provides both a 79graphical AVD manager and a command-line interface that you can use to 80create AVDs. To access the graphical AVD manager, run the 81<code>android</code> tool without options. The sections below describe how to 82use the <code>android</code> command-line interface to create and manage AVDs. 83Note that some functionality, such as the capability to create an AVD with a 84custom hardware configuration, are only available through the command-line 85interface. </p> 86 87<p>For more information about how to work with AVDs from inside your development 88environment, see <a 89href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse with 90ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">Developing in 91Other IDEs</a>, as appropriate for your environment.</p> 92 93<h2 id="creating">Creating an AVD</h2> 94 95<div class="sidebox-wrapper"> 96<div class="sidebox-inner"> 97<p>The Android SDK does not include any preconfigured AVDs, so 98you need to create an AVD before you can run any application in the emulator 99(even the Hello World application).</p> 100</div> 101</div> 102 103<p>To create an AVD, you use the <code>android</code> tool, a command-line 104utility available in the <code><sdk>/tools/</code> directory. Managing 105AVDs is one of the two main function of the <code>android</code> tool (the other 106is creating and updating Android projects). Open a terminal window and change to 107the <code><sdk>/tools/</code> directory, if needed</p> 108 109<p>To create each AVD, you issue the command <code>android create avd</code>, 110with options that specify a name for the new AVD and the system image you want 111to run on the emulator when the AVD is invoked. You can specify other options on 112the command line also, such as to create an emulated SD card for the new AVD, set 113the emulator skin to use, or set a custom location for the AVD's files.</p> 114 115<p>Here's the command-line usage for creating an AVD: </p> 116 117<pre>android create avd -n <name> -t <targetID> [-<option> <value>] ... </pre> 118 119<p>You can use any name you want for the AVD, but since you are likely to be 120creating multiple AVDs, you should choose a name that lets you recognize the 121general characteristics offered by the AVD. </p> 122 123<p>As shown in the usage above, you must use the <code>-t</code> (or 124<code>--target</code>) argument when creating a new AVD. The argument sets up a 125mapping between the AVD and the system image that you want to use whenever the 126AVD is invoked. You can specify any Android system image that is available in 127your local SDK — it can be the system image of a standard Android platform 128version or that of any SDK add-on. Later, when applications use the AVD, they'll 129be running on the system that you specify in the <code>-t</code> argument.<p> 130 131<p>To specify the system image to use, you refer to its <em>target ID</em> 132— an integer — as assigned by the <code>android</code> tool. The 133target ID is not derived from the system image name, version, or API Level, or 134other attribute, so you need to have the <code>android</code> tool list the 135available system images and the target ID of each, as described in the next 136section. You should do this <em>before</em> you run the <code>android create 137avd</code> command. 138</p> 139 140<h3 id="listingtargets">Listing targets</h3> 141 142<p>To generate a list of system image targets, use this command: </p> 143 144<pre>android list targets</pre> 145 146<p>The <code>android</code> tool scans the <code><sdk>/platforms</code> and 147<code><sdk>/add-ons</code> directories looking for valid system images and 148then generates the list of targets. Here's an example of the command output: 149</p> 150 151<pre>Available Android targets: 152id:1 153 Name: Android 1.1 154 Type: platform 155 API level: 2 156 Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P 157id:2 158 Name: Android 1.5 159 Type: platform 160 API level: 3 161 Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P 162id:3 163 Name: Google APIs 164 Type: add-on 165 Vendor: Google Inc. 166 Description: Android + Google APIs 167 Based on Android 1.5 (API level 3) 168 Libraries: 169 * com.google.android.maps (maps.jar) 170 API for Google Maps 171 Skins: HVGA (default), HVGA-L, QVGA-P, HVGA-P, QVGA-L</pre> 172 173<h3 id="selectingtarget">Selecting a target</h3> 174 175<p>Once you have generated the list of targets available, you can look at the 176characteristics of each system image — name, API Level, external 177libraries, and so on — and determine which target is appropriate for the 178new AVD. </p> 179 180<p>Keep these points in mind when you are selecting a system image target for 181your AVD:</p> 182<ul> 183<li>The API Level of the target is important, because your application will not 184be able to run on a system image whose API Level is less than that required by 185your application, as specified in the <code>minSdkVersion</code> attribute of 186the application's manifest file. For more information about the relationship 187between system API Level and application <code>minSdkVersion</code>, see <a 188href="{@docRoot}guide/publishing/versioning.html#minsdkversion">Specifying 189Minimum System API Version</a>. 190<li>Creating at least one AVD that uses a target whose API Level is greater than 191that required by your application is strongly encouraged, because it allows you to 192test the forward-compatibility of your application. Forward-compatibility 193testing ensures that, when users who have downloaded your application receive a 194system update, your application will continue to function normally. </li> 195<li>If your application declares a <code>uses-library</code> element in its 196manifest file, the application can only run on a system image in which that 197external library is present. If you want your application to run on the AVD you 198are creating, check the application's <code>uses-library</code> element and 199select a system image target that includes that library. 200 201</ul> 202 203<h3 id="createavd">Creating the AVD</h3> 204 205<p>When you've selected the target you want to use and made a note of its ID, 206use the <code>android create avd</code> command to create the AVD, supplying the 207target ID as the <code>-t</code> argument. Here's an example that creates an 208AVD with name "my_android1.5" and target ID "2" (the standard Android 1.5 209system image in the list above): </p> 210 211<pre>android create avd -n my_android1.5 -t 2</pre> 212 213<p>If the target you selected was a standard Android system image ("Type: 214platform"), the <code>android</code> tool next asks you whether you want to 215create a custom hardware profile. </p> 216<pre>Android 1.5 is a basic Android platform. 217Do you wish to create a custom hardware profile [no]</pre> 218 219<p>If you want to set custom hardware emulation options for the AVD, enter 220"yes" and set values as needed. If you want to use the default hardware 221emulation options for the AVD, just press the return key (the default is "no"). 222The <code>android</code> tool creates the AVD with name and system image mapping you 223requested, with the options you specified. 224 225<p class="note">If you are creating an AVD whose target is an SDK add-on, the 226<code>android</code> tool does not allow you to set hardware emulation options. 227It assumes that the provider of the add-on has set emulation options 228appropriately for the device that the add-on is modeling, and so prevents you 229from resetting the options. </p> 230<p>For a list of options you can use in the <code>android create avd</code> 231command, see the table in <a href="#options">Command-line options for AVDs</a>, 232at the bottom of 233this page. </p> 234 235<h3 id="hardwareopts">Setting hardware emulation options</h3> 236 237<p>When are creating a new AVD that uses a standard Android system image ("Type: 238platform"), the <code>android</code> tool lets you set hardware emulation 239options for virtual device. The table below lists the options available and the 240default values, as well as the names of properties that store the emulated 241hardware options in the AVD's configuration file (the config.ini file in the 242AVD's local directory). </p> 243 244<table> 245<tr> 246<th>Characteristic</th> 247<th>Description</th> 248<th>Property</th> 249</tr> 250 251<tr> 252<td>Device ram size</td> 253<td>The amount of physical RAM on the device, in megabytes. Default value is "96". 254<td>hw.ramSize</td> 255</tr> 256 257<tr> 258<td>Touch-screen support</td> 259<td>Whether there is a touch screen or not on the device. Default value is "yes".</td> 260<td>hw.touchScreen 261 262<tr> 263<td>Trackball support </td> 264<td>Whether there is a trackball on the device. Default value is "yes".</td> 265<td>hw.trackBall</td> 266</tr> 267 268<tr> 269<td>Keyboard support</td> 270<td>Whether the device has a QWERTY keyboard. Default value is "yes".</td> 271<td>hw.keyboard</td> 272</tr> 273 274<tr> 275<td>DPad support</td> 276<td>Whether the device has DPad keys. Default value is "yes".</td> 277<td>hw.dPad</td> 278</tr> 279 280<tr> 281<td>GSM modem support</td> 282<td>Whether there is a GSM modem in the device. Default value is "yes".</td> 283<td>hw.gsmModem</td> 284</tr> 285 286<tr> 287<td>Camera support</td> 288<td>Whether the device has a camera. Default value is "no".</td> 289<td>hw.camera</td> 290</tr> 291 292<tr> 293<td>Maximum horizontal camera pixels</td> 294<td>Default value is "640".</td> 295<td>hw.camera.maxHorizontalPixels</td> 296</tr> 297 298<tr> 299<td>Maximum vertical camera pixels</td> 300<td>Default value is "480".</td> 301<td>hw.camera.maxVerticalPixels</td> 302</tr> 303 304<tr> 305<td>GPS support</td> 306<td>Whether there is a GPS in the device. Default value is "yes".</td> 307<td>hw.gps</td> 308</tr> 309 310<tr> 311<td>Battery support</td> 312<td>Whether the device can run on a battery. Default value is "yes".</td> 313<td>hw.battery</td> 314</tr> 315 316<tr> 317<td>Accelerometer</td> 318<td>Whether there is an accelerometer in the device. Default value is "yes".</td> 319<td>hw.accelerometer</td> 320</tr> 321 322<tr> 323<td>Audio recording support</td> 324<td>Whether the device can record audio. Default value is "yes".</td> 325<td>hw.audioInput</td> 326</tr> 327 328<tr> 329<td>Audio playback support</td> 330<td>Whether the device can play audio. Default value is "yes".</td> 331<td>hw.audioOutput</td> 332</tr> 333 334<tr> 335<td>SD Card support</td> 336<td>Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes".</td> 337<td>hw.sdCard</td> 338</tr> 339 340<tr> 341<td>Cache partition support</td> 342<td>Whether we use a /cache partition on the device. Default value is "yes".</td> 343<td>disk.cachePartition</td> 344</tr> 345 346<tr> 347<td>Cache partition size</td> 348<td>Default value is "66MB".</td> 349<td>disk.cachePartition.size </td> 350</tr> 351 352<tr> 353<td>Abstracted LCD density</td> 354<td>Sets the generalized density characteristic used by the AVD's screen. Default value is "160".</td> 355<td>hw.lcd.density </td> 356</tr> 357 358</table> 359 360<h3 id="location">Default location of the AVD files</h3> 361 362<p>When you create an AVD, the <code>android</code> tool creates a dedicated directory for it 363on your development computer. The directory contains the AVD configuration file, 364the user data image and SD card image (if available), and any other files 365associated with the device. Note that the directory does not contain a system 366image — instead, the AVD configuration file contains a mapping to the 367system image, which it loads when the AVD is launched. </p> 368 369<p>The <code>android</code> tool also creates a <AVD name>.ini file for the AVD at the 370root of the .android/avd directory on your computer. The file specifies the 371location of the AVD directory and always remains at the root the .android 372directory.</p> 373 374<p>By default, the <code>android</code> tool creates the AVD directory inside 375<code>~/.android/avd/</code> (on Linux/Mac), <code>C:\Documents and 376Settings\<user>\.android\</code> on Windows XP, and 377<code>C:\Users\<user>\.android\</code> on Windows Vista. 378If you want to use a custom location for the AVD directory, you 379can do so by using the <code>-p <path></code> option when 380you create the AVD: </p> 381 382<pre>android create avd -n my_android1.5 -t 2 -p path/to/my/avd</pre> 383 384<p>If the .android directory is hosted on a network drive, we recommend using 385the <code>-p</code> option to place the AVD directory in another location. 386The AVD's .ini file remains in the .android directory on the network 387drive, regardless of the location of the AVD directory. </p> 388 389<h2 id="managing">Managing AVDs</h2> 390 391<p>The sections below provide more information about how to manage AVDs once you've created them. </p> 392 393<h3 id="moving">Moving an AVD</h3> 394 395<p>If you want to move or rename an AVD, you can do so using this command:</p> 396 397<pre>android move avd -n <name> [-<option> <value>] ...</pre> 398 399<p>The options for this command are listed in <a href="#options">Command-line 400options for AVDs</a> at the bottom of this page. </p> 401 402<h3 id="updating">Updating an AVD</h3> 403 404<p>If, for any reason, the platform/add-on root folder has its name changed (maybe because the user has installed an update of the platform/add-on) then the AVD will not be able to load the system image that it is mapped to. In this case, the <code>android list targets</code> command will produce this output: 405 406<pre>The following Android Virtual Devices could not be loaded: 407Name: foo 408Path: <path>/.android/avd/foo.avd 409Error: Invalid value in image.sysdir. Run 'android update avd -n foo' </pre> 410 411<p>To fix this error, use the <code>android update avd</code> command to recompute the path to the system images.</p> 412 413<h3 id="deleting">Deleting an AVD</h3> 414 415<p>You can use the <code>android</code> tool to delete an AVD. Here is the command usage:</p> 416 417<pre>android delete avd -n <name> </pre> 418 419<p>When you issue the command, the <code>android</code> tool looks for an AVD matching the 420specified name deletes the AVD's directory and files. </p> 421 422 423<h2 id="options">Command-line options for AVDs</h2> 424 425<p>The table below lists the command-line options you can use with the 426<code>android</code> tool. </p> 427 428 429<table> 430<tr> 431 <th width="15%">Action</th> 432 <th width="20%">Option</th> 433 <th width="30%">Description</th> 434 <th>Comments</th> 435</tr> 436 437 438<tr> 439 <td><code>list avds</code></td> 440 <td> </td> 441 <td>List all known AVDs, with name, path, target, and skin. </td> 442 <td> </td> 443</tr> 444<tr> 445 <td rowspan="6"><code>create avd</code></td> 446 <td><code>-n <name> or <br></code></td> 447 <td>The name for the AVD.</td> 448 <td>Required</td> 449</tr> 450<tr> 451 <td><code>-t <targetID></code></td> 452 <td>Target ID of the system image to use with the new AVD.</td> 453 <td>Required. To obtain a list of available targets, use <code>android list 454 targets</code>.</td> 455</tr> 456<tr> 457 <td><code>-c <path></code> or <br> 458 <code>-c <size>[K|M]</code></td> 459 <td>The path to the SD card image to use with this AVD or the size of a new SD 460 card image to create for this AVD.</td> 461 <td>Examples: <code>-c path/to/sdcard</code> or <code>-c 1000M</code></td> 462</tr> 463<tr> 464 <td><code>-f</code></td> 465 <td>Force creation of the AVD</td> 466 <td>By default, if the name of the AVD being created matches that of an 467 existing AVD, the <code>android</code> tool will not create the new AVD or overwrite 468 the existing AVD. If you specify the <code>-f</code> option, however, the 469 <code>android</code> tool will automatically overwrite any existing AVD that has the 470 same name as the new AVD. The files and data of the existing AVD are 471 deleted. </td> 472</tr> 473 474<tr> 475 <td><code>-p <path></code></td> 476 <td>Path to the location at which to create the directory for this AVD's 477files.</td> 478 <td> </td> 479</tr> 480<tr> 481 <td><code>-s <name></code> or <br> 482 <code>-s <width>-<height></code> </td> 483 <td>The skin to use for this AVD, identified by name or dimensions.</td> 484 <td>The <code>android</code> tool scans for a matching skin by name or dimension in the 485<code>skins/</code> directory of the target referenced in the <code>-t 486<targetID></code> argument. Example: <code>-s HVGA-L</code></td> 487</tr> 488<tr> 489 <td><code>delete avd</code></td> 490 <td><code>-n <name></code></td> 491 <td>Delete the specified AVD.</td> 492 <td>Required</td> 493</tr> 494<tr> 495 <td rowspan="3"><code>move avd</code></td> 496 <td><code>-n <name></code></td> 497 <td>The name of the AVD to move.</td> 498 <td>Required</td> 499</tr> 500<tr> 501 <td><code>-p <path></code></td> 502 <td>The path to the new location for the AVD.</td> 503 <td> </td> 504</tr> 505<tr> 506 <td><code>-r <new-name></code></td> 507 <td>Rename the AVD.</td> 508 <td> </td> 509</tr> 510<tr> 511 <td><code>update avds</code></td> 512 <td> </td> 513 <td>Recompute the paths to all system images.</td> 514 <td> </td> 515</tr> 516 517 518 519</table> 520 521