Start the Emulator from the Command Line

The content of the data partition, which appears as data/ in the emulated system. When you create a new AVD, or when you use the -wipe-data option to reset the AVD to the factory defaults, the emulator copies the userdata.img file in the system directory to create this file.

Each virtual device 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 app data, settings, databases, and files. Each user has a different ANDROID_SDK_HOME directory that stores the data directories for the AVDs created by that user; each AVD has a single userdata-qemu.img file.

(Optional) An SD card partition image that lets you simulate an SD card on a virtual device. You can create an SD card image file in the AVD Manager or using the mksdcard tool. The file is stored on your development computer and must be loaded at startup.

When defining an AVD in the AVD Manager, you have the choice to use an automatically managed SD card file, or a file that you created with the mksdcard tool. You can view the sdcard.img file associated with an AVD in the AVD Manager. The -sdcard option overrides the SD card file specified in the AVD.

You can browse, send files to, and copy and remove files from a simulated SD card by using the emulator UI or the adb utility while the virtual device is running. You can't remove a simulated SD card from a running virtual device.

To copy files to the SD card file before loading it, you can mount the image file as a loop device and then copy the files. Or use a utility such as the mtools package to copy the files directly to the image.

The emulator treats the file as a pool of bytes so the SD card format doesn't matter.

Note that the -wipe-data option doesn't affect this file. If you want to clear the file, you need to delete the file and then recreate it using the AVD Manager or the mksdcard tool. Changing the size of the file also deletes the file and creates a new file.

mode can be any of the following values:

• emulated - The emulator simulates a camera in the software.
• webcamn - The emulator uses a webcam connected to your development computer, specified by number. For a list of webcams, use the -webcam-list option; for example, webcam0.
• none - Disable the camera in the virtual device.

For example:

$ emulator @Nexus_5X_API_23 -camera-back webcam0

$ emulator @Nexus_5X_API_23 -webcam-list
List of web cameras connected to the computer:
  Camera 'webcam0' is connected to device 'webcam0' on channel 0 using
  pixel format 'UYVY'

In the example, the first webcam0 is the name you use on the command line. The second webcam0 is the name used by the OS on the development computer. The second name varies depending on the OS.

As of SDK Tools 25.2.4, the AVD name is required, although it might not be in the future.

$ emulator @Nexus_5X_API_23 -memory 2048

This value overrides the AVD setting.

$ emulator @Nexus_5X_API_23 -sdcard C:/sd/sdcard.img

If the file isn't found, the emulator still launches, but without an SD card; the command returns a No SD Card Image warning.

If you don't specify this option, the default is sdcard.img in the data directory (unless the AVD specifies something different). For details about emulated SD cards, see AVD data directory.

$ emulator @Nexus_5X_API_23 -wipe-data

By default, the user data file is userdata-qemu.img and the initial data file is userdata.img, both residing in the data directory. The -wipe-data option doesn't affect the sdcard.img file. For more information about user data, see Understanding the default directories and files.

$ emulator @Nexus_5X_API_23 -debug init,metrics

To disable a tag, place a dash (-) in front of it; for example, the following option displays all debug messages, except the ones related to network sockets and metrics:

-debug all,-socket,-metrics

For a list of tags and descriptions, use the -help-debug-tags option. For example:

$ emulator -help-debug-tags

You can define the default debug tags in the ANDROID_VERBOSE environment variable. Define the tags you want to use in a comma-delimited list. Here's an example showing it defined with the socket and gles tags:

ANDROID_VERBOSE=socket,gles

It's equivalent to using:

-debug-socket -debug-gles

$ emulator @Nexus_5X_API_23 -debug-all -debug-no-metrics

For a list of tags, use the emulator -help-debug-tags command.

$ emulator @Nexus_5X_API_23 -logcat *:e

logtags uses the same format as the adb logcat logtags command (enter adb logcat -help for more information). It's a list of space- or comma-separated log filters of the format componentName:logLevel. componentName is either a wildcard asterisk (*) or a component name, such as ActivityManager, SystemServer, InputManager, WindowManager, and so on. logLevel is one of these values:

• v - verbose
• d - debug
• i - informative
• w - warning log level
• e - error
• s - silent

The following example displays GSM component messages at the informative log level:

$ emulator @Nexus_5X_API_23 -logcat '*:s GSM:i'

If you don't supply the -logcat option on the command line, the emulator looks for the ANDROID_LOG_TAGS environment variable. If ANDROID_LOG_TAGS is defined with a valid logtags value and isn't empty, the emulator uses its value to enable logcat output to the terminal by default. You can also redirect the same, or other, log messages to the terminal through adb. For more information about logcat and adb, see logcat Command-Line Tool, Write and View Logs with Logcat, Log class, and adb commands reference.

$ emulator @Nexus_5X_API_23 -show-kernel

One use of this option is to check that the boot process works correctly.

$ emulator @Nexus_5X_API_23 -verbose

It displays which files and settings are actually selected when starting a virtual device defined in an AVD. This option is the same as specifying -debug-init.

$ emulator @Nexus_5X_API_23 -dns-server 192.0.2.0,192.0.2.255

By default, the emulator tries to detect the DNS servers you're using and sets up special aliases in the emulated firewall network to allow the Android system to connect directly to them. Use the -dns-server option to specify a different list of DNS servers.

$ emulator @Nexus_5X_API_23 -http-proxy myserver:1981

proxy can be one of the following:
http://server:port
http://username:password@server:port

The http:// prefix can be omitted.

If this option isn't supplied, the emulator looks up the http_proxy environment variable and automatically uses any value matching the proxy format. For more information, see Using the emulator with a proxy.

Set network latency emulation to one of the following delay values in milliseconds:

• gsm - GSM/CSD (min 150, max 550).
• hscsd - HSCSD (min 80, max 400).
• gprs - GPRS (min 35, max 200).
• edge - EDGE/EGPRS (min 80, max 400).
• umts - UMTS/3G (min 35, max 200).
• hsdpa - HSDPA (min 0, max 0).
• lte - LTE (min 0, max 0).
• evdo - EVDO (min 0, max 0).
• none - No latency, the default (min 0, max 0).
• num - Specify exact latency.
• min:max - Specify individual minimum and maximum latencies.

For example:

$ emulator @Nexus_5X_API_23 -netdelay gsm

The emulator supports network throttling (limiting the maximum network bandwidth, also called network shaping) as well as higher connection latencies. You can define it either through the skin configuration, or with the ‑netspeed and -netdelay options.

$ emulator @Nexus_5X_API_23 -netfast

This option is the same as specifying -netspeed full -netdelay none. These are the default values for these options.

Set the network speed emulation. Specify the maximum network upload and download speeds with one of the following speed values in kbps:

• gsm - GSM/CSD (up: 14.4, down: 14.4).
• hscsd - HSCSD (up: 14.4, down: 57.6).
• gprs - GPRS (up: 28.8, down: 57.6).
• edge - EDGE/EGPRS (up: 473.6, down: 473.6).
• umts - UMTS/3G (up: 384.0, down: 384.0).
• hsdpa - HSDPA (up: 5760.0, down: 13,980.0).
• lte - LTE (up: 58,000, down: 173,000).
• evdo - EVDO (up: 75,000, down: 280,000).
• full - No limit, the default (up: 0.0, down: 0.0).
• num - Specify both upload and download speed.
• up:down - Specify individual up and down speeds.

For example:

$ emulator @Nexus_5X_API_23 -netspeed edge

The emulator supports network throttling (limiting the maximum network bandwidth, also called network shaping) as well as higher connection latencies. You can define it either through the skin configuration, or with the ‑netspeed and -netdelay options.

$ emulator @Nexus_5X_API_23 -port 5556

The default value is 5554 for the first virtual device instance running on the your machine. A virtual device normally occupies a pair of adjacent ports: a console port and an adb port. The console of the first virtual device running on a particular machine uses console port 5554 and adb port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, 5558/5559, and so on. The range is 5554 to 5682, allowing for 64 concurrent virtual devices.

The port assignments are often the same as specifying -ports port,{port + 1}. {port + 1} must be free and will be reserved for adb. If any of the console or adb ports is already in use, the emulator won't start. The ‑port option reports which ports and serial number the virtual device is using, and warns if there are any issues with the values you provided. In the emulator UI, you can see the console port number in the window title, and you can view the adb port number by selecting Help > About.

Note that if the port value is not even and is in the range 5554 to 5584, the virtual device will start but not be visible when you use the adb devices command if the adb server starts after the emulator. For this reason, we recommend using an even console port number.

$ emulator @Nexus_5X_API_23 -ports 5556,5559

The valid ports range is 5554 to 5682, allowing for 64 concurrent virtual devices. The -ports option reports which ports and serial number the emulator instance is using, and warns if there are any issues with the values you provided.

We recommend using the -port option instead, where possible. The -ports option is available for network configurations that require special settings.

For more information about setting console and adb ports, see the -port option.

$ emulator @Nexus_5X_API_23 -tcpdump /path/dumpfile.cap

Use the option to begin capturing all network packets that are sent through the virtual Ethernet LAN of the emulator. After, you can use a tool like Wireshark to analyze the traffic.

Note that this option captures all Ethernet packets, and isn't limited to TCP connections.

$ emulator @Nexus_5X_API_23 -accel auto

Accelerated emulation works for x86 and x86_64 system images only. On Linux, it relies on KVM. On Windows and Mac, it relies on an Intel CPU and Intel HAXM driver. This option is ignored if you're not emulating an x86 or x86_64 device.

Valid values for mode are:

• auto - Determine automatically if acceleration is supported and use it when possible (default).
• off - Disables acceleration entirely, which is primarily useful for debugging.
• on - Force acceleration. If KVM or HAXM isn't installed or usable, the emulator won't start and prints an error message.

For more information, see Configure Hardware Acceleration.

$ emulator -accel-check

For more information, see Determining whether HAXM or KVM is installed.

Specify the emulator engine:

• auto - Automatically select an engine (default).
• classic - Use the older QEMU 1 engine.
• qemu2 - Use the newer QEMU 2 engine.

For example:

$ emulator @Nexus_5X_API_23 -engine auto

Auto-detection should choose the value that provides the best performance when emulating a particular AVD. You should use the -engine option for debugging and comparison purposes only.

$ emulator @Nexus_5X_API_23 -gpu swiftshader_indirect

For more information, see Configuring graphics acceleration on the command line.

$ emulator @Nexus_5X_API_23 -no-accel

For more information, see Configure Hardware Acceleration.

$ emulator @Nexus_5X_API_23 -nojni

When you start a virtual device, extended JNI checks are enabled by default. For more information, see JNI Tips.

me-linux$ emulator @Nexus_5X_API_23 -selinux permissive

By default, SELinux is in enforcing mode, meaning the security policy is enforced. permissive mode loads the SELinux policy, but doesn't enforce it; it just logs policy violations. disabled mode disables kernel support for SELinux.

Set the timezone for the virtual device to timezone, instead of the host timezone. For example:

$ emulator @Nexus_5X_API_23 -timezone Europe/Paris

By default, the emulator uses the timezone of your development computer. Use this option to specify a different timezone or if the automatic detection isn't working correctly. The timezone value must be in zoneinfo format, which is area/location or area/subarea/location. For example:

• America/Los_Angeles
• Europe/Paris
• America/Argentina/Buenos_Aires

The specified timezone must be in the zoneinfo database.

$ emulator @Nexus_5X_API_23 -version

Or

$ emulator -version

$ emulator @Nexus_5X_API_23 -no-boot-anim

On slower computers, this option can significantly speed up the boot sequence.

$ emulator @Nexus_5X_API_23 -screen no-touch

mode can be any of the following values:

• touch - Emulate a touch screen (default).
• multi-touch - Emulate a multi-touch screen.
• no-touch - Disable touch and multi-touch screen emulation.

Enable bootcharting, with a timeout in seconds. Some Android system images have a modified init system that integrates a bootcharting facility. You can pass a bootcharting timeout period to the system with this option. If your init system doesn't have bootcharting activated, the option does nothing. This option is primarily useful to platform developers, not external app developers.

For example:

$ emulator @Nexus_5X_API_23 -bootchart 120

Specify a cache partition image file. Provide a filename, and an absolute path or a path relative to the data directory, to set up a persistent cache file. If the file doesn't exist, the emulator creates it as an empty file. If you don't use this option, the default is a temporary file named cache.img. For more information, see AVD data directory.

For example:

$ emulator @Nexus_5X_API_23 -cache
   ~/.android/avd/Nexus_5X_API_23.avd/cache_persistent.img

Set the cache partition size in MBs. If you don't specify this option, the default is 66 MB. Normally, most app developers don't need this option, unless they need to download very large files that are larger than the default cache. For more information about the cache file, see AVD data directory.

For example:

$ emulator @Nexus_5X_API_23 -cache-size 1000

Set the user data partition image file. Provide a filename, and an absolute path or a path relative to the working directory, to set up a persistent user data file. If the file doesn't exist, the emulator creates an image from the default userdata.img file, stores it in the filename you specified, and persists user data to it at shutdown. If you don't use this option, the default is a file named userdata-qemu.img. For more information about the user data file, see AVD data directory.

For example:

$ emulator @Nexus_5X_API_23 -data
   ~/.android/avd/Nexus_5X_API_23.avd/userdata-test.img

Specify a data directory using an absolute path. For more information, see AVD data directory.

For example:

$ emulator @Nexus_5X_API_23 -datadir
   ~/.android/avd/Nexus_5X_API_23.avd/mytest

Use the 32-bit emulator on 64-bit platforms. Occasionally, this option is useful for testing or debugging. For example, there was an issue where the emulator would sometimes not run on 64-bit Windows, but 32-bit did run; this option was helpful for performing comparisons to debug the issue. Here's an example:

$ emulator @Nexus_5X_API_23 -force-32bit

Get help about about disk images. It provides information relevant to both app and platform developers. For example:

$ emulator -help-disk-images

Get help about character device specifications. A device parameter is required by some emulator options. For example:

$ emulator -help-char-devices

Get help about disk images relevant to app developers. It explains where the image files are located for an AVD created with the SDK tools. For example:

$ emulator -help-sdk-images

Get help about disk images relevant to platform developers. For example:

$ emulator -help-build-images

Specify the initial version of the data partition. After wiping user data, the emulator copies the contents of the specified file to user data (by default, the userdata-qemu.img file) instead of using the default userdata.img file as the initial version. Specify the filename, and an absolute path or a path relative to the working directory. If you don't specify a path, it places the file in the system directory. For more information, see AVD system directory.

For example:

$ emulator @Nexus_5X_API_23 -initdata
   ~/Library/Android/sdk/system-images/android-23/google_apis/x86/userdata-test.img

Use a specific emulated kernel. If you don't specify a path, the emulator looks in the system directory. If you don't specify this option, the default is kernel-ranchu. For more information, see AVD system directory. Use the ‑show‑kernel option to view kernel debug messages.

For example:

$ emulator @Nexus_5X_API_23 -kernel
   ~/Library/Android/sdk/system-images/android-23/google_apis/x86/kernel-test.img
   -show-kernel
   

Disable audio support for this virtual device. Some Linux and Windows computers have faulty audio drivers that cause different symptoms, such as preventing the emulator from starting. In this case, you can use this option to overcome the issue. Alternatively, you can use the QEMU_AUDIO_DRV environment variable to change the audio backend.

For example:

$ emulator @Nexus_5X_API_23 -noaudio

Start the emulator without a cache partition. If you don't use this option, the default is a temporary file named cache.img. This option is for platform developers only. For more information, see AVD data directory.

For example:

$ emulator @Nexus_5X_API_23 -nocache

Inhibit both the automatic load and save operations, causing the emulator to execute a full boot sequence and to lose its state when closed. It overrides the -snapshot option.

For example:

$ emulator @Nexus_5X_API_23 -no-snapshot

Prevent the emulator from loading the AVD state from snapshot storage. Perform a full boot.

For example:

$ emulator @Nexus_5X_API_23 -no-snapshot-load

Prevent the emulator from saving the AVD state to snapshot storage on exit, meaning that all changes will be lost.

For example:

$ emulator @Nexus_5X_API_23 -no-snapshot-save

Don't try to correct the AVD clock time immediately on snapshot restore. This option can be useful during testing as it avoids a sudden time jump. Time updates are still sent to the AVD about every 15 seconds, however.

For example:

$ emulator @Nexus_5X_API_23 -no-snapshot-update-time

Start the emulator without mounting a file to store or load state snapshots, forcing a full boot and disabling state snapshot functionality. This option overrides the -snapstorage and -snapshot options.

For example:

$ emulator @Nexus_5X_API_23 -no-snapstorage

Disable graphical window display on the emulator. This option is useful when running the emulator on servers that have no display. You'll still be able to access the emulator through adb or the console. For example:

$ emulator @Nexus_5X_API_23 -no-window

Specify the system data partition size in MBs. For example:

$ emulator @Nexus_5X_API_23 -partition-size 1024

Set an Android system property in the emulator when it boots. name must be a property name of at most 32 characters, without any spaces in it, and value must be a string of at most 92 characters. You can specify several ‑prop options on one command line. This option can be useful for debugging. For example:

$ emulator @Nexus_5X_API_23 -prop status.battery.level_raw=80
   -prop ro.serialno=123456

Display -qemu help. For example:

$ emulator -qemu -h

Specify a ramdisk boot image. Specify the filename, and an absolute path or a path relative to the working directory. If you don't use this option, the default is the ramdisk.img file in the system directory. For more information, see AVD system directory.

For example:

$ emulator @Nexus_5X_API_23 -ramdisk
   ~/Library/Android/sdk/system-images/android-23/google_apis/x86/ramdisk-test.img

Report the console port to a remote third party before starting emulation. It can be useful for an automated testing script. socket must use one of these formats:

• tcp:port[,server][,max=seconds][,ipv6]
• unix:port[,server][,max=seconds][,ipv6]

For more information, use the -help-report-console option as described in Getting detailed help for a specific option.

Create a root shell console on the current terminal. It differs from the adb shell command in the following ways:

• It creates a root shell that allows you to modify many parts of the system.
• It works even if the adb daemon in the emulated system is broken.
• Pressing Ctrl+C (⌘C) stops the emulator, instead of the shell.

For example:

$ emulator @Nexus_5X_API_23 -shell

Specify the name of a snapshot within a snapshot storage file for automatic start and save operations. Rather than executing a full boot sequence, the emulator can resume execution from an earlier state snapshot, which is usually significantly faster. When you supply this option, the emulator loads the snapshot of that name from the snapshot image and saves it back under the same name on exit. If you don’t use this option, the default is a full boot sequence. If the specified snapshot doesn’t exist, the emulator performs a full boot sequence instead, and performs a save operation.

See the -snapstorage option for information on specifying a snapshot storage file and the default file.

$ emulator @Nexus_5X_API_23 -snapshot snapshot2

It’s important to remember that in the process of loading a snapshot, all contents of the system, user data, and SD card images are overwritten with the contents they held when the snapshot was made. Unless you save this information in a different snapshot, any changes since then are lost.

You can also create a snapshot from the Emulator Console by using the avd snapshot save name command. For more information, see Send Emulator Console Commands to a Virtual Device.

Display a list of available snapshots. It prints a table of snapshots that are stored in the snapshot storage file that the emulator was started with, then exits. If you specify -snapstorage file as well, this command prints a table of the snapshots stored in file.

For example:

$ emulator @Nexus_5X_API_23 -snapshot-list -snapstorage
   ~/.android/avd/Nexus_5X_API_23.avd/snapshots-test.img

You can use the ID and TAG column values in the output as arguments for the -snapshot option.

Specify a repository file that contains all state snapshots. All snapshots made during execution will be saved in this file, and only snapshots in this file can be restored during the emulator run. If you don’t specify this option, the default is snapshots.img in the data directory. If the specified file doesn’t exist, the emulator will start, but without support for saving or loading state snapshots.

For example:

$ emulator @Nexus_5X_API_23 -snapstorage
   ~/.android/avd/Nexus_5X_API_23.avd/snapshots-test.img

Specify a system directory using an absolute path. For more information, see AVD system directory. For example:

$ emulator @Nexus_5X_API_23 -sysdir
   ~/Library/Android/sdk/system-images/android-23/google_apis/x86/test

Specify an initial system file. Provide the filename, and an absolute path or a path relative to the working directory. If you don't use this option, the default is the system.img file in the system directory. For more information, see AVD system directory. For example:

$ emulator @Nexus_5X_API_23 -system
   ~/Library/Android/sdk/system-images/android-23/google_apis/x86/system-test.img

On Linux, use the system libstdc++ instead of the version bundled with the emulator system. Use this option only if the emulator won’t start normally, although it doesn’t always work. Alternatively, set the ANDROID_EMULATOR_USE_SYSTEM_LIBS environment variable to 1.

For example:

me-linux$ emulator @Nexus_5X_API_23 -use-system-libs

Use this option to have a writable system image during your emulation session. To do so:

1. Start a virtual device with the -writable-system option.
2. Enter the adb remount command from a command terminal to tell the emulator to remount system/ as read/write (it’s mounted as read-only by default).

Note that using this flag will create a temporary copy of the system image that can be very large (several hundred MBs), but will be destroyed when the emulator exits.