developing/tools/avd.jd

page.title=Android Virtual Devices
@jd:body

<div id="qv-wrapper">
<div id="qv">

  <h2>AVD quickview</h2>
  <ul>
    <li>You need to create an AVD to run any app in the Android emulator</li>
    <li>Each AVD is a completely independent virtual device, with its own
        hardware options, system image, and data storage.
    <li>You create AVD configurations to model different device environments
        in the Android emulator.</li>
    <li>You can launch a graphical Android AVD Manager either through Eclipse or
through the <code>android</code> tool. The <code>android</code> tool also offers
a command-line interface for creating and managing AVDs.</li> </ul>
  <h2>In this document</h2>
  <ol>
    <li><a href="#creating">Creating an AVD</a>
      <ol>
        <li><a href="#hardwareopts">Setting hardware emulation options</a></li>
        <li><a href="#location">Default location of the AVD files</a></li>
      </ol>
    </li>
    <li><a href="#managing">Managing AVDs</a>
      <ol>
        <li><a href="#moving">Moving an AVD</a></li>
        <li><a href="#updating">Updating an AVD</a></li>
        <li><a href="#deleting">Deleting an AVD</a></li>
      </ol>
    </li>
    <li><a href="#options">Command-line options</a></li>
  </ol>
  <h2>See Also</h2>
  <ol>
    <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android
        Emulator</a></li>
  </ol>
</div>
</div>

<p>Android Virtual Devices (AVDs) are configurations of emulator options that let
you better model an actual device.</p>

<p>Each AVD is made up of: </p>

<ul>
<li>A hardware profile.&nbsp;&nbsp;You can set options to define the hardware
features of the virtual device. For example, you can define whether the device
has a camera, whether it uses a physical QWERTY keyboard or a dialing pad, how
much memory it has, and so on. </li>
<li>A mapping to a system image.&nbsp;&nbsp;You can define what version of the
Android platform will run on the virtual device. You can choose a version of the
standard Android platform or the system image packaged with an SDK add-on.</li>
<li>Other options.&nbsp;&nbsp;You can specify the emulator skin you want to use
with the AVD, which lets you control the screen dimensions, appearance, and so
on. You can also specify the emulated SD card to use with the AVD.</li>
<li>A dedicated storage area on your development machine, in which is stored the
device's user data (installed applications, settings, and so on) and emulated SD
card.</li>
</ul>

<p>You can create as many AVDs as you need, based on the types of devices you
want to model and the Android platforms and external libraries you want to run
your application on. </p>

<p>In addition to the options in an AVD configuration, you can also
specify emulator command-line options at launch or by using the emulator
console to change behaviors or characteristics at run time. For a complete
reference of emulator options, please see the <a
href="{@docRoot}guide/developing/tools/emulator.html">Emulator</a>
documentation. </p>

<p>The easiest way to create an AVD is to use the graphical AVD Manager, which
you can launch from Eclipse or from the command line using the
<code>android</code> tool. The <code>android</code> tool is provided in the
<code>tools/</code> directory of the Android SDK. When you run the
<code>android</code> tool without options, it launches the graphical AVD
Manager.</p>

<p>For more information about how to work with AVDs from inside your development
environment, see <a
href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse with
ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">Developing in
Other IDEs</a>, as appropriate for your environment.</p>

<h2 id="creating">Creating an AVD</h2>

<div class="sidebox-wrapper">
<div class="sidebox">
<p>The Android SDK does not include any preconfigured AVDs, so
you need to create an AVD before you can run any application in the emulator
(even the Hello World application).</p>
</div>
</div>
<p>The easiest way to create an AVD is to use the graphical AVD Manager, but the
<code>android</code> tool also offers a <a href="#options">command line option</a>.</p>
<p>To create an AVD:</p>
<ol>
  <li>In Eclipse, choose <strong>Window &gt; Android SDK and AVD Manager</strong>. </li>
  <p>Alternatively, you can launch the graphical AVD Manager by running the
<code>android</code> tool with no options.</p>
  <li>Select <strong>Virtual Devices</strong> in the left panel.</li>

  <li>Click <strong>New</strong>. </li>

<p>The <strong>Create New AVD</strong> dialog appears.</p> <a
href="{@docRoot}images/developing/avd-dialog.png"><img
src="{@docRoot}images/developing/avd-dialog.png" alt="AVD
Dialog" /></a>

  <li>Type the name of the AVD, such as "my_avd".</li>
  <li>Choose a target. </li>
<p>The target is the system image that you want to run on the emulator,
from the set of platforms that are installed in your SDK environment. You can
choose a version of the standard Android platform or an SDK add-on. For more
information about how to add platforms to your SDK, see <a
href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. </p>
  <li>Optionally specify any additional settings: </li>
  <dl>
  <dt><em>SD Card</em></dt> <dd>The path to the SD card image to use with this
AVD, or the size of a new SD card image to create for this AVD.</dd> </dl>
<dt><em>Skin</em></dt>
    <dd>The skin to use for this AVD, identified by name or dimensions.</dd>
<dt><em>Hardware</em></dt>
    <dd>The hardware emulation options for the device. For a list of the options, see
<a href="#hardwareopts">Setting hardware emulation options</a>.</dd>
  </dl>
  <li>Click <strong>Create AVD</strong>.</li>
</ol>

<h3 id="hardwareopts">Setting hardware emulation options</h3>

<p>When you create a new AVD that uses a standard Android system image ("Type:
platform"), the AVD Manager
 lets you set hardware emulation
options for your virtual device.
The table below lists the options available and the
default values, as well as the names of properties that store the emulated
hardware options in the AVD's configuration file (the <code>config.ini</code> file in the
AVD's local directory). </p>

<table>
<tr>
<th>Characteristic</th>
<th>Description</th>
<th>Property</th>
</tr>

<tr>
<td>Device ram size</td>
<td>The amount of physical RAM on the device, in megabytes. Default value is "96".
<td>hw.ramSize</td>
</tr>

<tr>
<td>Touch-screen support</td>
<td>Whether there is a touch screen or not on the device. Default value is "yes".</td>
<td>hw.touchScreen

<tr>
<td>Trackball support </td>
<td>Whether there is a trackball on the device. Default value is "yes".</td>
<td>hw.trackBall</td>
</tr>

<tr>

<td>Keyboard support</td>
<td>Whether the device has a QWERTY keyboard. Default value is "yes".</td>
<td>hw.keyboard</td>
</tr>

<tr>
<td>DPad support</td>
<td>Whether the device has DPad keys. Default value is "yes".</td>
<td>hw.dPad</td>
</tr>

<tr>
<td>GSM modem support</td>
<td>Whether there is a GSM modem in the device. Default value is "yes".</td>
<td>hw.gsmModem</td>
</tr>

<tr>
<td>Camera support</td>
<td>Whether the device has a camera. Default value is "no".</td>
<td>hw.camera</td>
</tr>

<tr>
<td>Maximum horizontal camera pixels</td>
<td>Default value is "640".</td>
<td>hw.camera.maxHorizontalPixels</td>
</tr>

<tr>
<td>Maximum vertical camera pixels</td>
<td>Default value is "480".</td>
<td>hw.camera.maxVerticalPixels</td>

</tr>

<tr>
<td>GPS support</td>
<td>Whether there is a GPS in the device. Default value is "yes".</td>
<td>hw.gps</td>
</tr>

<tr>
<td>Battery support</td>
<td>Whether the device can run on a battery. Default value is "yes".</td>
<td>hw.battery</td>

</tr>

<tr>
<td>Accelerometer</td>
<td>Whether there is an accelerometer in the device. Default value is "yes".</td>
<td>hw.accelerometer</td>
</tr>

<tr>
<td>Audio recording support</td>
<td>Whether the device can record audio. Default value is "yes".</td>
<td>hw.audioInput</td>

</tr>

<tr>
<td>Audio playback support</td>
<td>Whether the device can play audio. Default value is "yes".</td>
<td>hw.audioOutput</td>
</tr>

<tr>
<td>SD Card support</td>
<td>Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes".</td>
<td>hw.sdCard</td>

</tr>

<tr>
<td>Cache partition support</td>
<td>Whether we use a /cache partition on the device. Default value is "yes".</td>
<td>disk.cachePartition</td>
</tr>

<tr>
<td>Cache partition size</td>
<td>Default value is "66MB".</td>
<td>disk.cachePartition.size </td>

</tr>

<tr>
<td>Abstracted LCD density</td>
<td>Sets the generalized density characteristic used by the AVD's screen. Most
skins come with a value (which you can modify), but if a skin doesn't provide
its own value, the default is 160. </td>
<td>hw.lcd.density </td>
</tr>

<tr>
<td>Max VM application heap size</td>
<td>The maximum heap size a Dalvik application might allocate before being
killed by the system. Value is in megabytes. Most skins come with a value (which
you can modify), but if a skin doesn't provide its own value, the default is
16.</td>
<td>vm.heapSize</td>
</tr>

</table>

<h3 id="location">Default location of the AVD files</h3>

<p>When you create an AVD, the AVD Manager creates a dedicated directory for it
on your development computer. The directory contains the AVD configuration file,
the user data image and SD card image (if available), and any other files
associated with the device. Note that the directory does not contain a system
image &mdash; instead, the AVD configuration file contains a mapping to the
system image, which it loads when the AVD is launched. </p>

<p>The AVD Manager also creates a <code>&lt;AVD name&gt;.ini</code> file for the
AVD at the root of the <code>.android/avd</code> directory on your computer. The file
specifies the location of the AVD directory and always remains at the root the
.android directory.</p>

<p>By default, the AVD Manager creates the AVD directory inside
<code>~/.android/avd/</code> (on Linux/Mac), <code>C:\Documents and
Settings\&lt;user&gt;\.android\</code> on Windows XP, and
<code>C:\Users\&lt;user&gt;\.android\</code> on Windows Vista.
If you want to use a custom location for the AVD directory, you
can do so by using the <code>-p &lt;path&gt;</code> option when
you create the AVD (command line tool only): </p>

<pre>android create avd -n my_android1.5 -t 2 -p path/to/my/avd</pre>

<p>If the <code>.android</code> directory is hosted on a network drive, we recommend using
the <code>-p</code> option to place the AVD directory in another location.
The  AVD's <code>.ini</code> file remains in the <code>.android</code> directory on the network
drive, regardless of the location of the AVD directory. </p>

<h2 id="managing">Managing AVDs</h2>

<p>The sections below provide more information about how to manage AVDs once you've created them. </p>

<h3 id="moving">Moving an AVD</h3>

<p>If you want to move or rename an AVD, you can do so using this command:</p>

<pre>android move avd -n &lt;name&gt; [-&lt;option&gt; &lt;value&gt;] ...</pre>

<p>The options for this command are listed in <a href="#options">Command-line
options for AVDs</a> at the bottom of this page. </p>

<h3 id="updating">Updating an AVD</h3>

<p>
If you rename or move the root directory of a platform (or add-on), an AVD configured to use that platform will no longer be able to load the system image properly. To fix the AVD, use the <strong>Repair...</strong> button in the AVD Manager. From the command line, you can also use the <code>android update avd</code> command to recompute the path to the system images.</p>

<h3 id="deleting">Deleting an AVD</h3>

<p>You can  delete an AVD in the AVD Manager by selecting the
AVD and clicking <strong>Delete</strong>.</p>

<p>Alternatively, you can use the <code>android</code> tool to delete an AVD. Here is the command usage:</p>

<pre>android delete avd -n &lt;name&gt; </pre>

<p>When you issue the command, the <code>android</code> tool looks for an AVD matching the
specified name deletes the AVD's directory and files. </p>


<h2 id="options">Command-line options</h2>

<p>You can use the <code>android</code> tool to create and manage AVDs.</p>

<p>The command line for creating an AVD has the following syntax:</p>

<pre>
android create avd -n &lt;name&gt; -t &lt;targetID&gt; [-&lt;option&gt; &lt;value&gt;] ...
</pre>

<p>Here's an example that creates an AVD with the name "my_android2.2" and target ID "3":</p>

<pre>
android create avd -n my_android2.2 -t 3
</pre>

<p>The table below lists the command-line options you can use with the
<code>android</code> tool. </p>


<table>
<tr>
  <th width="15%">Action</th>
  <th width="20%">Option</th>
  <th width="30%">Description</th>
  <th>Comments</th>
</tr>


<tr>
  <td><code>list&nbsp;avds</code></td>
  <td>&nbsp;</td>
  <td>List all known AVDs, with name, path, target, and skin. </td>
  <td>&nbsp;</td>
</tr>
<tr>
  <td rowspan="6"><code>create&nbsp;avd</code></td>
  <td><code>-n &lt;name&gt; or <br></code></td>
  <td>The name for the AVD.</td>
  <td>Required</td>
</tr>
<tr>
  <td><code>-t &lt;targetID&gt;</code></td>
  <td>Target ID of the system image to use with the new AVD.</td>
  <td>Required. To obtain a list of available targets, use <code>android list
      targets</code>.</td>
</tr>
<tr>
  <td><code>-c &lt;path&gt;</code> or <br>
      <code>-c &lt;size&gt;[K|M]</code></td>
  <td>The path to the SD card image to use with this AVD or the size of a new SD
      card image to create for this AVD.</td>
  <td>Examples: <code>-c path/to/sdcard</code> or <code>-c 1000M</code></td>
</tr>
<tr>
  <td><code>-f</code></td>
  <td>Force creation of the AVD</td>
  <td>By default, if the name of the AVD being created matches that of an
      existing AVD, the <code>android</code> tool will not create the new AVD or overwrite
      the existing AVD. If you specify the <code>-f</code> option, however, the
      <code>android</code> tool will automatically overwrite any existing AVD that has the
      same name as the new AVD. The files and data of the existing AVD are
      deleted. </td>
</tr>

<tr>
  <td><code>-p &lt;path&gt;</code></td>
  <td>Path to the location at which to create the directory for this AVD's
files.</td>
  <td>&nbsp;</td>
</tr>
<tr>
  <td><code>-s &lt;name&gt;</code> or <br>
      <code>-s &lt;width&gt;-&lt;height&gt;</code> </td>
  <td>The skin to use for this AVD, identified by name or dimensions.</td>
  <td>The <code>android</code> tool scans for a matching skin by name or dimension in the
<code>skins/</code> directory of the target referenced in the <code>-t
&lt;targetID&gt;</code> argument. Example: <code>-s HVGA-L</code></td>
</tr>
<tr>
  <td><code>delete&nbsp;avd</code></td>
  <td><code>-n &lt;name&gt;</code></td>
  <td>Delete the specified AVD.</td>
  <td>Required</td>
</tr>
<tr>
  <td rowspan="3"><code>move&nbsp;avd</code></td>
  <td><code>-n &lt;name&gt;</code></td>
  <td>The name of the AVD to move.</td>
  <td>Required</td>
</tr>
<tr>
  <td><code>-p &lt;path&gt;</code></td>
  <td>The path to the new location for the AVD.</td>
  <td>&nbsp;</td>
</tr>
<tr>
  <td><code>-r &lt;new-name&gt;</code></td>
  <td>Rename the AVD.</td>
  <td>&nbsp;</td>
</tr>
<tr>
  <td><code>update&nbsp;avds</code></td>
  <td>&nbsp;</td>
  <td>Recompute the paths to all system images.</td>
  <td>&nbsp;</td>
</tr>


</table>