In this document
- Starting and Stopping the Emulator
- Installing Applications on the Emulator
- Using Command Line Parameters
- Using the Emulator Console
- Starting and stopping a console session
- Port redirection
- Geo location provider emulation
- Hardware events emulation
- Device power characteristics
- Network status
- Network delay emulation
- Network speed emulation
- Telephony emulation
- SMS emulation
- VM state
- Emulator window
- Simulating finger print support
- Terminating an emulator instance
- Using SD Card Emulation
- Working with Emulator Disk Images
- Setting Up Emulator Networking
- Troubleshooting Emulator Problems
The Android SDK includes a mobile device emulator — a virtual mobile device that runs on your computer. The emulator lets you develop and test Android applications without using a physical device.
This page describes command line features that you can use with the Android Emulator. For information about using the Android Emulator UI, see Using the Android Emulator.
Starting and Stopping the Emulator
During development and testing of your application, you install and run your application in the Android Emulator. You can launch the emulator as a standalone application from a command line, or you can run it from within your Android Studio development environment. In either case, you specify the AVD configuration to load and any startup options you want to use, as described in this document.
You can run your application on a single instance of the emulator or, depending on your needs, you can start multiple emulator instances and run your application in more than one emulated device. You can use the emulator built-in commands to simulate GSM phone calling or SMS between emulator instances, and you can set up network redirection that allows emulators to send data to one another. For more information, see Telephony Emulation, SMS Emulation, and Emulator Networking.
To start an instance of the emulator from the command line, navigate to the
tools/ folder of the SDK. Enter
emulator -avd <avd_name> [<options>]
This initializes the emulator, loads an AVD configuration and displays the emulator window.
Note: You can run multiple instances of the emulator concurrently, each with its own AVD configuration and storage area for user data, SD card, and so on.
When you run your app from Android Studio, it installs and launches the app on your connected device or emulator (launching the emulator, if necessary). You can specify emulator startup options in the Run/Debug dialog, in the Target tab. When the emulator is running, you can issue console commands as described later in this document.
If you are not working in Android Studio, see Installing Applications on the Emulator for information about how to install your application.
To stop an emulator instance, just close the emulator window.
Installing Applications on the Emulator
If you don't have access to Android Studio, you can install your application on the
emulator using the adb utility. Before
installing the application, you need to build and package it into an
.apk as described
in Build and Run Your App. After the application is installed,
you can start the emulator from the command
line as described previously, using any startup options necessary.
When the emulator is running, you can also connect to the emulator
console to issue commands as needed.
As you update your code, you periodically package and install it on the emulator.
The emulator preserves the application and its state data across restarts,
in a user-data disk partition. To ensure that the application runs properly
as you update it, you may need to delete the emulator user-data partition.
To do so, start the emulator with the
For more information about the user-data partition and other emulator storage,
see Working with Emulator Disk Images.
Using Command Line Parameters
The emulator supports a variety of options that you can specify
when launching the emulator, to control its appearance or behavior.
Here's the command-line syntax of the options available to the
emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]
||Required. Specifies the AVD to load for this emulator instance.||You must create an AVD configuration before launching the emulator. For information, see Managing AVDs with AVD Manager.|
||Use <filepath> as the working cache partition image.||An absolute or relative path to the current working directory.
If no cache file is specified, the emulator default behavior is to use a temporary file instead.
For more information on disk images, use
||Optionally, you can specify a path relative to the current working directory.
||When resetting the user-data image (through
||Optionally, you can specify a path relative to the current working directory. See also
For more information on disk images, use
||Start the emulator without a cache partition.||See also
||Use <filepath> as the ramdisk image.||Default value is
Optionally, you can specify a path relative to the current working directory.
For more information on disk images, use
||Use <file> as the SD card image.||Default value is
Optionally, you can specify a path relative to the current working directory. For more
information on disk images, use
||Reset the current user-data disk image (that is, the file specified by
For more information on disk images, use
||Enable/disable debug messages for the specified debug tags.||
||Enable/disable debug messages for the specified debug tag.||Use
||Disable debug messages for the specified debug tag.|
||Enable logcat output with given tags.||If the environment variable ANDROID_LOG_TAGS is defined and not empty, its value will be used to enable logcat output by default.|
||Create a root shell console on the current terminal.||You can use this command even if the adb daemon in the emulated system is broken. Pressing Ctrl-c from the shell stops the emulator instead of the shell.|
||Enable the root shell (as in
||<device> must be a QEMU device type. See the documentation for '-serial dev' at
for a list of device types.
Here are some examples:
||Display kernel messages.|
||Enable code profiling (press F9 to start), written to a specified file.|
||Enable verbose output.||Equivalent to
You can define the default verbose output options used by emulator instances in the Android environment variable
ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option:
Here's an example showing ANDROID_VERBOSE defined with the
For more information about debug tags, use
||Use the specified audio backend.|
||Use the specified audio-input backend.|
||Use the specified audio-output backend.|
||Disable audio support in the current emulator instance.|
||Redirect radio modem interface to a host character device.|
||Enable audio support in the current emulator instance.||Enabled by default.|
||Use the specified DNS server(s).||The value of
||Make all TCP connections through a specified HTTP/HTTPS proxy||The value of
||Set network latency emulation to <delay>.||Default value is
||Set network speed emulation to <speed>.||Default value is
||Set the console port number for this emulator instance to
||The console port number must be an even integer between 5554 and 5584, inclusive.
||Report the assigned console port for this emulator instance to a remote third party before starting the emulation.||
||Slow down emulated CPU speed by <delay>||Supported values for <delay> are integers between 0 and 1000.
Note that the <delay> does not correlate to clock speed or other absolute metrics — it simply represents an abstract, relative delay factor applied non-deterministically in the emulator. Effective performance does not always scale in direct relationship with <delay> values.
||Redirect NMEA GPS to character device.||Use this command to emulate an NMEA-compatible GPS unit connected to
an external character device or socket. The format of
||Disable JNI checks in the Dalvik runtime.|
||Pass arguments to the qemu emulator software.|
Important: When using this option, make sure it is the last option specified, since all options after it are interpretted as qemu-specific options.
||Enable KVM acceleration of the emulator virtual machine.||This option is only effective when your system is set up to use
KVM-based VM acceleration.
You can optionally specify a memory size (|
||Display qemu help.|
||Turn on graphics acceleration for the emulator.||This option is only available for emulators using a system image with API Level 15, revision 3 and higher. For more information, see Configuring Graphics Acceleration.|
||Redirect radio mode to the specified character device.||The format of
||Set the timezone for the emulated device to <timezone>, instead of the host timezone.||
||Display the emulator version number.|
||Scale the resolution of the emulator to match the screen size of a physical device.||The default value is 165. See also
||Disable the boot animation during emulator startup.||Disabling the boot animation can speed the startup time for the emulator.|
||Disable the emulator graphical window display.|
||Scale the emulator window.||
||Disable Unicode keyboard reverse-mapping.|
||Don't use any emulator skin.|
||Use the specified keyset file instead of the default.||The keyset file defines the list of key bindings between the emulator and the host keyboard.
For more information, use
||Use overlay image over screen.||No support for JPEG. Only PNG is supported.|
||Specify onion skin translucency value (as percent).||Default is 50.|
||Specify onion skin rotation.||
||This emulator option is deprecated.||Please set skin options using AVDs, rather than by using this emulator option. Using this option may yield unexpected and in some cases misleading results, since the density with which to render the skin may not be defined. AVDs let you associate each skin with a default density and override the default as needed. For more information, see Managing AVDs with the AVD Manager.|
||This emulator option is deprecated.||See comments for
||Print a list of all emulator options.|
||Print help for all startup options.|
||Print help for a specific startup option.|
||Print a list of all tags for
||Print help for using emulator disk images.|
||Print help for emulator environment variables.|
||Print the current mapping of keys.|
||Print help for defining a custom key mappings file.|
||Print help for Android Virtual Device usage.|
Using the Emulator Console
Each running emulator instance provides a console that lets you query and control the emulated device environment. For example, you can use the console to manage port redirection, network characteristics, and telephony events while your application is running on the emulator.
Starting and stopping a console session
To access the console and enter commands, from a terminal window, use
connect to the
console port and provide your authentication token. Each time the console displays
OK, it's ready to accept commands. It doesn't have a typical prompt.
To connect to the console of a running emulator instance:
- Open a terminal window and enter the following command:
- After the console displays OK, enter the
- After you're connected to the console, enter console commands.
- To exit the console session, enter
telnet localhost console-port
The emulator window title lists the console port number. For example, the
window title for an emulator using console port 5554
An emulator instance occupies a pair of adjacent ports: a console port and an
The port numbers differ by 1, with the
adb port having the higher port number. The console
of the first emulator instance running on a particular machine uses console port 5554 and
port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557,
5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility.
To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running, you need to determine the console port of the emulator instance you want to connect to.
adb devices command prints a list of
running emulator instances and their console port numbers. For more information, see
Querying for Emulator/Device Instances.
Note: The emulator listens for connections on ports 5554 to 5587 and accepts connections from localhost only.
Before you can enter console commands, the emulator console requires authentication.
match the contents of the
.emulator_console_auth_token file in your home directory.
If that file doesn't exist, the
telnet localhost console-port
command creates the file, which contains a randomly generated authentication token.
To disable authentication, delete the token from the
.emulator_console_auth_token file or create an empty file if it doesn't exist.
help command to see a
list of console commands and learn about specific commands.
Here's an example session:
me-macbook$ telnet localhost 5554 Trying ::1... telnet: connect to address ::1: Connection refused Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. Android Console: Authentication required Android Console: type 'auth <auth_token>' to authenticate Android Console: you can find your <auth_token> in '/Users/me/.emulator_console_auth_token' OK auth 123456789ABCdefZ Android Console: type 'help' for a list of commands OK help Android console command help: help|h|? print a list of commands crash crash the emulator instance kill kill the emulator instance quit|exit quit control session redir manage port redirections power power related commands event simulate hardware events avd control virtual device execution finger manage emulator fingerprint geo Geo-location commands sms SMS related commands cdma CDMA related commands gsm GSM related commands rotate rotate the screen by 90 degrees try 'help <command>' for command-specific help OK exit Connection closed by foreign host. me-macbook$
The following sections describe the major functional areas of the console.
You can use the console to add and remove port redirection while the emulator is running. After you connect to the console, manage port redirection by entering the following command:
redir command supports the subcommands listed in the table below.
||List the current port redirection.|
||Add a new port redirection.||
||Delete a port redirection.||The meanings of <protocol> and <host-port> are listed in the previous row.|
Geo location provider emulation
You can use the console to set the geographic location reported to the applications running
inside an emulator. Use the
geo command to send a simple GPS fix to the
emulator, with or without NMEA 1083 formatting:
geo command supports the subcommands listed in the table below.
||Send a simple GPS fix to the emulator instance.||Specify longitude and latitude in decimal degrees. Specify altitude in meters.|
||Send an NMEA 0183 sentence to the emulated device, as if it were sent from an emulated GPS modem.||
You can issue the
geo command as soon as an emulator instance is running. The
emulator sets the location you enter by creating a mock location provider. This provider responds to
location listeners set by applications, and also supplies the location to the
Any application can query the location manager to obtain the
current GPS fix for the emulated device by calling:
For more information about the Location Manager, see
Hardware events emulation
event console commands sends hardware events to the emulator. The syntax for this
command is as follows:
event command supports the subcommands listed in the table below.
||Send one or more events to the Android kernel.||You can use text names or integers for
||Simulate keypresses to send the specified string of characters as a message,||The message must be a UTF-8 string. Unicode posts will be reverse-mapped according to the current device keyboard. Unsupported characters will be discarded silently.|
Device power characteristics
power command controls the power state reported by the emulator to applications. The
syntax for this command is as follows:
event command supports the subcommands listed in the table below.
||Display battery and charger state.|
||Set AC charging state to on or off.|
||Change battery status as specified.|
||Set battery presence state.|
||Set battery health state.|
||Set remaining battery capacity state (0-100).|
You can use the console to check the network status and current delay and speed characteristics.
To do so, connect to the console and use the
netstatus command. Here's an example of
the command and its output.
Network delay emulation
The emulator lets you simulate various network latency levels, so that you can test your application in an environment more typical of the actual conditions in which it will run. You can set a latency level or range at emulator startup or you can use the console to change the latency, while the application is running in the emulator.
To set latency at emulator startup, use the
-netdelay emulator option with a
<delay> value, as listed in the table below. Here are some
emulator -netdelay gprs emulator -netdelay 40 100
To make changes to network delay while the emulator is running, connect to the console and use
netdelay command with a supported
<delay> value from the table
network delay gprs
The format of network <delay> is one of the following (numbers are milliseconds):
|GPRS||(min 150, max 550)|
|EDGE/EGPRS||(min 80, max 400)|
|UMTS/3G||(min 35, max 200)|
|No latency||(min 0, max 0)|
||Emulate an exact latency (milliseconds).|
||Emulate an specified latency range (min, max milliseconds).|
Network speed emulation
The emulator also lets you simulate various network transfer rates. You can set a transfer rate or range at emulator startup or you can use the console to change the rate, while the application is running in the emulator.
To set the network speed at emulator startup, use the
-netspeed emulator option with a supported
<speed> value, as listed in the table below. Here are some examples:
emulator -netspeed gsm emulator -netspeed 14.4 80
To make changes to network speed while the emulator is running, connect to the console and use
netspeed command with a supported
<speed> value from the table
network speed 14.4 80
The format of network
<speed> is one of the following (numbers are
||GSM/CSD||(Up: 14.4, down: 14.4)|
||HSCSD||(Up: 14.4, down: 43.2)|
||GPRS||(Up: 40.0, down: 80.0)|
||EDGE/EGPRS||(Up: 118.4, down: 236.8)|
||UMTS/3G||(Up: 128.0, down: 1920.0)|
||HSDPA||(Up: 348.0, down: 14400.0)|
||no limit||(Up: 0.0, down: 0.0)|
||Set an exact rate used for both upload and download.|
||Set exact rates for upload and download separately.|
The Android emulator includes its own GSM emulated modem that lets you simulate telephony functions in the emulator. For example, you can simulate inbound phone calls, establish data connections and terminate them. The Android system handles simulated calls exactly as it would actual calls. The emulator does not support call audio.
You can use the
gsm command to access the emulator telephony functions after connecting
to the console. The syntax for this command is as follows:
gsm command supports the subcommands listed in the table below.
||Simulate an inbound phone call from <phonenumber>.|
||Accept an inbound call from <phonenumber> and change the call state "active".||You can change a call state to "active" only if its current state is "waiting" or "held".|
||Close an outbound call to <phonenumber> and change the call state to "busy".||You can change a call state to "busy" only if its current state is "waiting".|
||Terminate an inbound or outbound phone call to/from <phonenumber>.|
||Change the state of the GPRS data connection to <state>.||Supported <state> values are:
||Change the state of a call to "held".||You can change a call state to "held" only if its current state is "active" or "waiting".|
||List all inbound and outbound calls and their states.|
||Change the state of the GPRS voice connection to <state>.||Supported <state> values are:
||Report the current GSM voice/data state.||Values are those described for the
The Android emulator console lets you generate an SMS message and direct it to an emulator instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using the following command:
sms send <senderPhoneNumber> <textmessage>
<senderPhoneNumber> contains an arbitrary numeric string.
The console forwards the SMS message to the Android framework, which passes it through to an application that handles that message type.
You can use the
vm command to control the VM on an emulator instance. The syntax for
this command is as follows:
vm command supports the subcommands listed in the table below.
||Start the VM on the instance.|
||Stop the VM on the instance.|
||Display the current status of the VM (running or stopped).|
You can use the
window command to manage the emulator window. The syntax for this
command is as follows:
vm command supports the subcommands listed in the table below.
||Scale the emulator window.||A number between 0.1 and 3 that sets the scaling factor. You can also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" tells the emulator to select the best window size.|
Simulating finger print support
Android Emulator console provides the
finger command, allowing you to simulate,
and thus validate,
finger print authentication for your app. After you set up your app to accept
authentication, your emulator or device should display the finger print authentication screen,
as shown in figure 1.
Open a terminal session, and telnet to the emulator. For example:
telnet localhost 5554
finger command to simulate finger touch and removal:
finger touch <fingerprint-id>to simulate a finger touching the sensor
finger removeto simulate finger removal
Your app should respond as if a user touched and then removed their finger from the finger print sensor.
Terminating an emulator instance
You can terminate an emulator instance through the console, using the
Using SD Card Emulation
You can create a disk image and then load it to the emulator at startup, to simulate the presence of a user's SD card in the device. To do this, you can specify an SD card image when you create an AVD, or you can use the mksdcard utility included in the SDK.
The following sections describe how to create an SD card disk image, how to copy files to it, and how to load it in the emulator at startup.
Note that you can only load a disk image at emulator startup. Similarly, you can not remove a simulated SD card from a running emulator. However, you can browse, send files to, and copy/remove files from a simulated SD card either with adb or the emulator.
The emulator supports emulated SDHC cards, so you can create an SD card image of any size up to 128 gigabytes.
Creating an SD card image
There are several ways of creating an SD card image. The easiest way is to use the AVD Manager to create a new SD card by specifying a size when you create an AVD.
You can also use the mksdcard tool, included in the SDK, to create a FAT32 disk
image that you can load in the emulator at startup. You can access mksdcard in
tools directory of the SDK and create a disk image like this:
mksdcard <size> <file>
mksdcard 1024M sdcard1.iso
For more information, see
Copying files to an SD card image
Once you have created the disk image, you can copy files to it prior to
loading it in the emulator. To copy files, you can mount the image as a loop
device and then copy the files to it, or you can use a utility such as
copy the files directly to the image. The
mtools package is available for Linux,
Mac, and Windows.
Alternatively, you can use the
adb push command to move files onto an SD card image
while it is loaded in an emulator. For more information see the
adb push documentation.
Loading an SD card image
By default, the emulator loads the SD card image that is stored with the active
AVD (see the
-avd startup option).
Alternatively, you can start the emulator with the
-sdcard flag and specify the name and path of your image (relative
to the current working directory):
emulator -sdcard <filepath>
Working with Emulator Disk Images
The emulator uses mountable disk images stored on your development machine to simulate flash (or similar) partitions on an actual device. For example, it uses a disk image containing an emulator-specific kernel, the Android system, a ramdisk image, and writable images for user data and simulated SD card.
To run properly, the emulator requires access to a specific set of disk image files. By default, the Emulator always looks for the disk images in the private storage area of the AVD in use. If no images exist there when the Emulator is launched, it creates the images in the AVD directory based on default versions stored in the SDK.
Note: The default storage location for
AVDs is in
~/.android/avd on OS X and Linux,
Settings\<user>\.android\ on Windows XP, and
on Windows Vista.
To let you use alternate or custom versions of the image files, the emulator provides startup options that override the default locations and filenames of the image files. When you use one of these options, the emulator searches for the image file under the image name or location that you specify; if it can not locate the image, it reverts to using the default names and location.
The emulator uses three types of image files: default image files, runtime image files, and temporary image files. The sections below describe how to override the location/name of each type of file.
Default image files
When the emulator launches, but does not find an existing user data image in the active AVD storage area, it creates a new one from a default version included in the SDK. The default user data image is read-only. The image files are read-only.
The emulator provides the
-system <dir> startup option to
let you override the location where the emulator looks for the default
user data image.
The emulator also provides a startup option that lets you override the name
of the default user data image, as described in the following table. When you use the
option, the emulator looks in the default directory, or in a custom location
(if you specified
||The initial user-data disk image||Override using
Runtime images: user data and SD card
At runtime, the emulator reads and writes data to two disk images: a user-data image and (optionally) an SD card image. These images emulate the user-data partition and removable storage media on actual device.
The emulator provides a default user-data disk image. At startup, the emulator creates the default image as a copy of the system user-data image (user-data.img), described above. The emulator stores the new image with the files of the active AVD.
The emulator provides startup options to let you override the actual names and storage locations of the runtime images to load, as described in the following table. When you use one of these options, the emulator looks for the specified file(s) in the current working directory, in the AVD directory, or in a custom location (if you specified a path with the filename).
||An image to which the emulator writes runtime user-data for a unique user.||Override using
||An image representing an SD card inserted into the emulated device.||Override using
Each emulator instance uses a writable user-data image to store user- and session-specific data. For example, it uses the image to store a unique user's installed application data, settings, databases, and files.
At startup, the emulator attempts to load a user-data image stored during a previous session. It looks for the file in the current working directory, in the AVD directory described in a previous section and at the custom location/name that you specified at startup.
- If it finds a user-data image, it mounts the image and makes it available to the system for reading and writing of user data.
- If it does not find one, it creates an image by copying the system user-data
image (userdata.img), described above. At device power-off, the system persists
the user data to the image, so that it will be available in the next session.
Note that the emulator stores the new disk image at the location/name that you
Note: Because of the AVD configurations used in the emulator,
each emulator instance gets its own dedicated storage. There is no longer a need
to use the
-d option to specify an instance-specific storage area.
Optionally, you can create a writable disk image that the emulator can use to simulate removeable storage in an actual device. For information about how to create an emulated SD card and load it in the emulator, see Using SD Card Emulation.
You can also use the android tool to automatically create an SD Card image for you, when creating an AVD. For more information, see Managing AVDs with the AVD Manager.
The emulator creates two writable images at startup that it deletes at device power-off. The images are:
- A writable copy of the Android system image
The emulator does not permit renaming the temporary system image or persisting it at device power-off.
/cache partition image is initially empty, and is used by
the browser to cache downloaded web pages and images. The emulator provides an
-cache <file>, which specifies the name of the file in which
to persist the
/cache image at device power-off. If
does not exist, the emulator creates it as an empty file.
You can also disable the use of the cache partition by specifying the
-nocache option at startup.
Setting Up Emulator Networking
The emulator provides versatile networking capabilities that you can use to set up complex modeling and testing environments for your application. The sections below introduce the emulator network architecture and capabilities.
Network address space
Each instance of the emulator runs behind a virtual router/firewall service that isolates it from your development machine network interfaces and settings and from the internet. An emulated device can not see your development machine or other emulator instances on the network. Instead, it sees only that it is connected through Ethernet to a router/firewall.
The virtual router for each instance manages the 10.0.2/24 network address space — all addresses managed by the router are in the form of 10.0.2.<xx>, where <xx> is a number. Addresses within this space are pre-allocated by the emulator/router as follows:
|10.0.2.2||Special alias to your host loopback interface (i.e., 127.0.0.1 on your development machine)|
|10.0.2.3||First DNS server|
|10.0.2.4 / 10.0.2.5 / 10.0.2.6||Optional second, third and fourth DNS server (if any)|
|10.0.2.15||The emulated device network/ethernet interface|
|127.0.0.1||The emulated device loopback interface|
Note that the same address assignments are used by all running emulator instances. That means that if you have two instances running concurrently on your machine, each will have its own router and, behind that, each will have an IP address of 10.0.2.15. The instances are isolated by a router and can not see each other on the same network. For information about how to let emulator instances communicate over TCP/UDP, see Interconnecting Emulator Instances.
Also note that the address 127.0.0.1 on your development machine corresponds to the emulator own loopback interface. If you want to access services running on your development machine loopback interface (a.k.a. 127.0.0.1 on your machine), you should use the special address 10.0.2.2 instead.
Finally, note that the pre-allocated addresses of an emulated devider are specific to the Android Emulator and will probably be very different on real devices (which are also very likely to be NAT-ed, specifically, behind a router/firewall).
Local networking limitations
Android applications running in an emulator can connect to the network available on your workstation. However, they connect through the emulator, not directly to hardware, and the emulator acts like a normal application on your workstation. This means that the emulator, and thus your Android applications, are subject to some limitations:
- Communication with the emulated device may be blocked by a firewall program running on your machine.
- Communication with the emulated device may be blocked by another (physical) firewall/router to which your machine is connected.
The emulator virtual router should be able to handle all outbound TCP and UDP connections/messages on behalf of the emulated device, provided your development machine network environment allows it to do so. There are no built-in limitations on port numbers or ranges except the one imposed by your host operating system and network.
Depending on the environment, the emulator may not be able to support other protocols (such as ICMP, used for "ping") might not be supported. Currently, the emulator does not support IGMP or multicast.
Using network redirection
To communicate with an emulator instance behind its virtual router, you need to set up network redirection on the virtual router. Clients can then connect to a specified guest port on the router, while the router directs traffic to/from that port to the emulated device host port.
To set up the network redirection, you create a mapping of host and guest ports/addresses on the emulator instance. There are two ways to set up network redirection: using emulator console commands and using the adb tool, as described below.
Setting up redirection through the Emulator Console
Each emulator instance provides a control console the you can connect to, to
issue commands that are specific to that instance. You can use the
redir console command to set up redirection as needed for an
First, determine the console port number for the target emulator instance. For example, the console port number for the first emulator instance launched is 5554. Next, connect to the console of the target emulator instance, specifying its console port number, as follows:
telnet localhost 5554
Once connected, use the
redir command to work with redirection.
To add a redirection, use:
<protocol> is either
<guest-port> sets the
mapping between your own machine and the emulated system, respectively.
For example, the following command sets up a redirection that handles all incoming TCP connections to your host (development) machine on 127.0.0.1:5000 and will pass them through to the emulated system 10.0.2.15:6000:
redir add tcp:5000:6000
To delete a redirection, you can use the
redir del command. To
list all redirection for a specific instance, you can use
list. For more information about these and other console commands, see
Using the Emulator Console.
Note that port numbers are restricted by your local environment. this typically
means that you cannot use host port numbers under 1024 without special
administrator privileges. Also, you won't be able to set up a redirection for a
host port that is already in use by another process on your machine. In that
redir generates an error message to that effect.
Setting up redirection through adb
The Android Debug Bridge (adb) tool provides port forwarding, an alternate way for you to set up network redirection. For more information, see Forwarding Ports in the adb documentation.
Note that adb does not currently offer any way to remove a redirection, except by killing the adb server.
Configuring the emulator DNS settings
At startup, the emulator reads the list of DNS servers that your system is currently using. It then stores the IP addresses of up to four servers on this list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4, 10.0.2.5 and 10.0.2.6 as needed.
On Linux and OS X, the emulator obtains the DNS server addresses by parsing
/etc/resolv.conf. On Windows, the emulator obtains the
addresses by calling the
GetNetworkParams() API. Note that this
usually means that the emulator ignores the content of your "hosts" file
/etc/hosts on Linux/OS X,
When starting the emulator at the command line, you can also use the
-dns-server <serverList> option to manually specify the
addresses of DNS servers to use, where <serverList> is a comma-separated
list of server names or IP addresses. You might find this option useful if you
encounter DNS resolution problems in the emulated network (for example, an
"Unknown Host error" message that appears when using the web browser).
Using the emulator with a proxy
If your emulator must access the Internet through a proxy server, you can use
-http-proxy <proxy> option when starting the emulator, to
set up the appropriate redirection. In this case, you specify proxy information
<proxy> in one of these formats:
-http-proxy option forces the emulator to use the specified
HTTP/HTTPS proxy for all outgoing TCP connections. Redirection for UDP is not
Alternatively, you can define the environment variable
http_proxy to the value you want to use for
<proxy>. In this case, you do not need to specify a value for
<proxy> in the
-http-proxy command — the
emulator checks the value of the
http_proxy environment variable at
startup and uses its value automatically, if defined.
You can use the
-verbose-proxy option to diagnose proxy
Interconnecting emulator instances
To allow one emulator instance to communicate with another, you must set up the necessary network redirection as illustrated below.
Assume that your environment is
- A is you development machine
- B is your first emulator instance, running on A
- C is your second emulator instance, also running on A
and you want to run a server on B, to which C will connect, here is how you could set it up:
- Set up the server on B, listening to
- On the B console, set up a redirection from
- On C, have the client connect to
For example, if you wanted to run an HTTP server, you can select
<serverPort> as 80 and
- B listens on 10.0.2.15:80
- On the B console, issue
redir add tcp:8080:80
- C connects to 10.0.2.2:8080
Sending a voice call or SMS to another emulator instance
The emulator automatically forwards simulated voice calls and SMS messages from one instance to another. To send a voice call or SMS, use the dialer application or SMS application, respectively, from one of the emulators.
To initiate a simulated voice call to another emulator instance:
- Launch the dialer application on the originating emulator instance.
- As the number to dial, enter the console port number of the instance you'd like to call. You can determine the console port number of the target instance by checking its window title, where the console port number is reported as "Android Emulator (<port>).
- Press "Dial". A new inbound call appears in the target emulator instance.
To send an SMS message to another emulator instance, launch the SMS application (if available). Specify the console port number of the target emulator instance as as the SMS address, enter the message text, and send the message. The message is delivered to the target emulator instance.
Troubleshooting Emulator Problems
adb utility sees the emulator as an actual physical device. For this reason, you
might have to use the
-d flag with some common
adb commands, such as
-d flag lets you specify which of several connected devices to use
as the target of a command. If you don't specify
-d, the emulator targets the first
device in its list. For more information about
adb, see Android Debug Bridge.
For emulators running on Mac OS X, if you see an error
Warning: No DNS servers found
when starting the emulator, check to see whether you have an
/etc/resolv.conf file. If
not, please run the following line in a command window:
ln -s /private/var/run/resolv.conf /etc/resolv.conf