Iniciar o emulador pela linha de comando

O SDK do Android inclui um emulador de dispositivo Android, um dispositivo virtual que é executado no computador. O Android Emulator permite desenvolver e testar apps Android sem usar um dispositivo físico.

Esta página descreve os recursos de linha de comando que você pode usar com o Android Emulator. Para saber mais sobre como usar a interface do Android Emulator, consulte Executar apps no Android Emulator.

Iniciar o emulador

Use o comando emulator para iniciar o emulador, como uma alternativa para executar seu projeto ou iniciá-lo com o AVD Manager.

Esta é a sintaxe básica da linha de comando para iniciar um dispositivo virtual por um prompt de terminal:

emulator -avd avd_name [ {-option [value]} … ]

Ou

emulator @avd_name [ {-option [value]} … ]

Por exemplo, se você iniciar o emulador no Android Studio em execução em um Mac, a linha de comando padrão vai ser parecida com o exemplo abaixo:

/Users/janedoe/Library/Android/sdk/emulator/emulator -avd Pixel8_API_34 -netdelay none -netspeed full -qt-hide-window -grpc-use-token -idle-grpc-timeout

Os argumentos -qt-hide-window -grpc-use-token -idle-grpc-timeout são usados apenas para executar a janela do emulador no Android Studio. Se você quiser executar o emulador em uma janela própria, não use esses parâmetros extras.

Você pode especificar opções de inicialização ao iniciar o emulador, mas não depois disso.

Para ver uma lista de nomes de AVD, digite este comando:

emulator -list-avds

Use essa opção para exibir uma lista de nomes de AVD do seu diretório inicial do Android. É possível modificar o diretório inicial padrão definindo a variável de ambiente ANDROID_SDK_HOME que especifica a raiz do diretório específico do usuário em que toda a configuração e o conteúdo do AVD são armazenados.

Você pode definir a variável de ambiente na janela do terminal antes de iniciar um dispositivo virtual ou usando as configurações do usuário no sistema operacional. Por exemplo, no arquivo .bashrc do Linux.

Para interromper o Android Emulator, basta fechar a janela do emulador.

Instalar um app

Além de instalar um app no Android Studio ou na interface do emulador, é possível instalá-lo em um dispositivo virtual usando o utilitário adb.

Para usar o adb na instalação, execução e teste do app, siga estas etapas gerais:

  1. Crie e empacote o app em um APK, conforme descrito em Criar e executar seu app.
  2. Inicie o emulador pela linha de comando, conforme descrito na seção anterior, usando qualquer opção de inicialização necessária.
  3. Instale o app usando adb.
  4. Execute e teste o app no emulador.
    Enquanto o emulador estiver em execução, você também vai poder usar o Console do Emulator para emitir comandos conforme necessário.

Para desinstalar um app, faça isso da maneira como você faria em um dispositivo Android.

O dispositivo virtual preserva o app e os dados de estado nas reinicializações, em uma partição de disco de dados do usuário (userdata-qemu.img). Para limpar esses dados, inicie o emulador com a opção -wipe-data ou apague os dados no AVD Manager. Para saber mais sobre a partição de dados do usuário e outro armazenamento, consulte a seção a seguir.

Observação: para o utilitário adb, o dispositivo virtual é como um dispositivo físico real. Por esse motivo, talvez seja necessário usar a flag -d com alguns comandos comuns do adb, como install. A sinalização -d permite especificar quais dos vários dispositivos conectados serão usados como destino de um comando. Se você não especificar -d, o emulador vai ser direcionado ao primeiro dispositivo da lista dele.

Entender os diretórios e arquivos padrão

O emulador utiliza arquivos associados, sendo que o sistema AVD e os diretórios de dados são os mais importantes. É útil entender a estrutura de diretórios e arquivos do emulador ao especificar as opções de linha de comando, embora você normalmente não precise modificar os diretórios ou arquivos padrão.

O Android Emulator usa o hipervisor (QEMU).

Diretório do sistema AVD

O diretório do sistema contém as imagens do sistema Android que o emulador usa para simular o sistema operacional. Ele compartilha arquivos somente leitura específicos da plataforma com todos os AVDs do mesmo tipo, incluindo o nível da API, a arquitetura da CPU e a variante do Android. Veja os locais padrão:

  • macOS e Linux: ~/Library/Android/sdk/system-images/android-apiLevel/variant/arch/
  • Windows: C:\Users\user\Library\Android\sdk\system-images\android-apiLevel\variant\arch\

Em que:

  • apiLevel é um nível numérico de API ou uma letra para versões de pré-lançamento. Por exemplo, android-V indica que o Android Prévia do VanillaIceCream. No lançamento, tornou-se uma API de nível 35, designada por android-35:
  • variant é um nome que corresponde a recursos específicos implementados pela imagem do sistema, por exemplo, google_apis ou android-wear.
  • arch é a arquitetura de CPU de destino, por exemplo, x86.

Use a opção -sysdir para especificar um diretório de sistema diferente para o AVD.

O emulador lê os seguintes arquivos no diretório do sistema:

Tabela 1. Arquivos de diretórios do sistema lidos pelo Android Emulator.

Arquivo Descrição Opção para especificar um arquivo diferente
kernel-qemu ou kernel-ranchu A imagem do kernel binário para o AVD. kernel-ranchu tem como base o Emulador QEMU. -kernel
ramdisk.img A imagem da partição de inicialização. Trata-se de um subconjunto de system.img carregado pelo kernel inicialmente antes da imagem do sistema ser montada. Geralmente contém apenas alguns binários e scripts de inicialização. -ramdisk
system.img A versão inicial somente leitura da imagem do sistema. Especificamente, a partição que contém as bibliotecas do sistema e os dados correspondentes ao nível e à variante da API. -system
userdata.img A versão inicial da partição de dados, que aparece como data/ no sistema emulado e contém todos os dados graváveis para o AVD. O emulador usa esse arquivo quando você cria um novo AVD ou usa a opção ‑wipe-data. Para saber mais, consulte a descrição do arquivo userdata-qemu.img na seção a seguir. -initdata
-init-data

Diretório de dados AVD

O diretório de dados AVD, também chamado de diretório de conteúdo, é específico para uma única instância do AVD e contém todos os dados modificáveis do AVD.

Veja o local padrão, em que name é o nome do AVD:

  • macOS e Linux: ~/.android/avd/name.avd/
  • Windows 10 e mais recentes: C:\Users\user\.android\name.avd\

Use a opção -datadir para especificar um diretório diferente.

A tabela a seguir lista os arquivos mais importantes contidos nesse diretório.

Tabela 2. Arquivos importantes no diretório de dados do AVD.

Arquivo Descrição Opção para especificar um arquivo diferente
userdata-qemu.img

O conteúdo da partição de dados, que aparece como data/ no sistema emulado. Quando você cria um novo AVD ou usa a opção -wipe-data para redefinir o AVD para o padrão de fábrica, o emulador copia o arquivo userdata.img no diretório do sistema para criar esse arquivo.

Cada instância de dispositivo virtual usa uma imagem de dados do usuário gravável para armazenar dados específicos do usuário e da sessão. Por exemplo, ela usa a imagem para armazenar dados, configurações, bancos de dados e arquivos de apps instalados de um usuário único. Cada usuário tem um diretório ANDROID_SDK_HOME diferente que armazena os diretórios de dados dos AVDs criados por esse usuário. Cada AVD tem um único arquivo userdata-qemu.img.

-data
cache.img A imagem da partição de cache, que aparece como cache/ no sistema emulado. Ela não tem conteúdo quando você cria um AVD ou usa a opção -wipe-data. Ela armazena arquivos de download temporários e é preenchida pelo gerenciador de download e, às vezes, pelo sistema. Por exemplo, o navegador a usa para armazenar em cache páginas da Web e imagens salvas enquanto o emulador está em execução. Quando você desliga o dispositivo virtual, o arquivo é excluído. Você pode manter o arquivo usando a opção -cache. -cache
sdcard.img

(Opcional) Uma imagem da partição do cartão SD que permite simular um cartão SD em um dispositivo virtual. Você pode criar um arquivo de imagem de cartão SD no AVD Manager ou usar a ferramenta mksdcard. O arquivo é armazenado no computador de desenvolvimento e precisa ser carregado na inicialização.

Ao definir um AVD no AVD Manager, você pode usar um arquivo de cartão SD gerenciado automaticamente ou um arquivo criado com a ferramenta mksdcard. Você pode ver o arquivo sdcard.img associado a um AVD no AVD Manager. A opção -sdcard substitui o arquivo do cartão SD especificado no AVD. Observe que essa opção de cartão SD não funciona em um Mac com Apple Silicon.

É possível procurar, enviar, copiar e remover arquivos de um cartão SD simulado usando a interface do emulador ou o utilitário adb enquanto o dispositivo virtual está em execução. Não é possível remover um cartão SD simulado de um dispositivo virtual em execução.

Para copiar arquivos no arquivo do cartão SD antes de carregá-lo, monte o arquivo de imagem como um dispositivo de loop. Também é possível usar um utilitário, como o pacote mtools, para copiar os arquivos diretamente na imagem.

O emulador trata o arquivo como um conjunto de bytes. Por isso, o formato do cartão SD não importa.

A opção -wipe-data não afeta o arquivo. Se você quiser limpar o arquivo, exclua-o e, em seguida, recrie-o usando o AVD Manager ou a ferramenta mksdcard. Mudar o tamanho também exclui o arquivo e cria um novo.

-sdcard

Listar diretórios e arquivos usados pelo emulador

Você pode descobrir onde os arquivos estão localizados de duas maneiras:

  • Use a opção -verbose ou -debug init ao iniciar o emulador pela linha de comando. Veja o resultado.
  • Use o comando -help-option do emulator para listar um diretório padrão. Por exemplo:
    emulator -help-datadir
    Use '-datadir <dir>' to specify a directory where writable image files will be searched. On this system, the default directory is: /Users/me/.android See '-help-disk-images' for more information about disk image files.

Opções de inicialização de linha de comando

Esta seção lista as opções que você pode usar na linha de comando ao iniciar o emulador.

Observação: o Android Emulator está em contínuo desenvolvimento para ficar mais confiável. Para saber mais sobre os problemas relatados em várias opções de linha de comando e informar bugs, consulte o Issue Tracker do Android.

Opções usadas com mais frequência

A tabela a seguir lista as opções de inicialização da linha de comando que você pode usar com mais frequência:

Tabela 3. Opções de linha de comando usadas com frequência

Opção de linha de comando Descrição
Quick Boot
-no-snapshot-load Executa uma inicialização a frio e salva o estado do emulador na saída.
-no-snapshot-save Executa um Quick Boot, se possível, mas não salva o estado do emulador na saída.
-no-snapshot Desativa completamente o recurso Quick Boot e não carrega ou salva o estado do emulador.
Hardware do dispositivo
-camera-back mode
-camera-front mode
Define o modo de emulação para uma câmera voltada para trás ou para frente. Isso substitui qualquer configuração de câmera do AVD.

O mode pode ter qualquer um destes valores:

  • emulated: o emulador simula uma câmera no software.
  • webcamn: o emulador usa uma webcam conectada ao computador de desenvolvimento, especificada por número. Para ver uma lista de webcams, use a opção -webcam-list. Por exemplo, webcam0.
  • none: desativa a câmera no dispositivo virtual.

Por exemplo:

emulator @Pixel8_API_34 -camera-back webcam0
-webcam-list Lista as webcams disponíveis para emulação no computador de desenvolvimento. Por exemplo:
emulator @Pixel8_API_34 -webcam-list
        List of web cameras connected to the computer:
        Camera 'webcam0' is connected to device 'webcam0'
        on channel 0 using pixel format 'UYVY'

No exemplo, a primeira webcam0 é o nome que você usa na linha de comando. A segunda webcam0 é o nome usado pelo sistema operacional no computador de desenvolvimento. O segundo nome varia de acordo com o sistema operacional.

A partir das Ferramentas do SDK 25.2.4, o nome do AVD será necessário.

Imagens do disco e memória
-memory size

Especifica o tamanho da RAM física de 1.536 a 8.192 MB. Exemplo:

emulator @Pixel8_API_34 -memory 2048

Esse valor substitui a configuração do AVD.

-sdcard filepath Especifica o nome do arquivo e o caminho para um arquivo de imagem da partição do cartão SD. Por exemplo:

emulator @Pixel8_API_34 -sdcard C:/sd/sdcard.img

Se o arquivo não for encontrado, o emulador ainda será aberto, mas sem um cartão SD. O comando vai retornar um aviso No SD Card Image.

Se você não especificar essa opção, o padrão será sdcard.img no diretório de dados, a menos que o AVD especifique algo diferente. Para ver detalhes sobre cartões SD emulados, consulte o diretório de dados do AVD.

-wipe-data Exclui os dados do usuário e copia os dados do arquivo de dados inicial. Essa opção limpa os dados do dispositivo virtual e os retorna ao mesmo estado em que foram definidos pela primeira vez. Todos os apps e configurações instalados são removidos. Por exemplo:

emulator @Pixel8_API_34 -wipe-data

Por padrão, o arquivo de dados do usuário é userdata-qemu.img e o arquivo de dados inicial é userdata.img. Ambos os arquivos residem no diretório de dados. A opção -wipe-data não afeta o arquivo sdcard.img. Para saber mais sobre dados de usuários, consulte a seção Compreender os diretórios e arquivos padrão.

Depuração
-debug tags Ativa ou desativa a exibição de mensagens de depuração para uma ou mais tags. Separe várias tags com um espaço, vírgula ou coluna. Por exemplo:

$ emulator @Pixel8_API_34 -debug init,metrics

Para desativar uma tag, coloque um traço (-) na frente dela. Por exemplo, a opção a seguir mostra todas as mensagens de depuração, exceto aquelas relacionadas a métricas e soquetes de rede:

-debug all,-socket,-metrics

Para ver uma lista de tags e descrições, use a opção -help-debug-tags. Por exemplo:

emulator -help-debug-tags

Você pode definir as tags de depuração padrão na variável de ambiente ANDROID_VERBOSE. Defina as tags que você quer usar em uma lista delimitada por vírgulas. Veja um exemplo que mostra como especificar as tags socket e gles:

ANDROID_VERBOSE=socket,gles

Isso é equivalente a usar:

-debug-socket -debug-gles

ou

-debug socket,gles

-debug-tag
-debug-no-tag
Ativa um tipo específico de mensagem de depuração. Use a forma no para desativar um tipo de mensagem de depuração. Por exemplo:

emulator @Pixel8_API_34 -debug-all -debug-no-metrics

Para ver uma lista de tags, use o comando emulator -help-debug-tags.

-logcat logtags Ativa a exibição de mensagens do Logcat para uma ou mais tags e as grava na janela do terminal. Por exemplo, o comando a seguir ativa mensagens de erro de todos os componentes:

emulator @Pixel8_API_34 -logcat *:e

O logtags usa o mesmo formato do comando adb logcat logtags. Digite adb logcat -help para saber mais. É uma lista de filtros de registro separados por espaços ou vírgulas do formato componentName:logLevel. componentName é um asterisco curinga (*) ou um nome de componente, como ActivityManager, SystemServer, InputManager ou WindowManager.

logLevel é um destes valores:

  • v: detalhado
  • d: depuração
  • i: informativo
  • w: nível de registro de avisos
  • e: erro
  • s: silenciado

O exemplo a seguir exibe mensagens do componente GSM no nível de registro informativo.

emulator @Pixel8_API_34 -logcat '*:s GSM:i'

Se você não informar a opção -logcat na linha de comando, o emulador vai procurar a variável de ambiente ANDROID_LOG_TAGS. Se ANDROID_LOG_TAGS for definido com um valor válido de logtags e não estiver vazio, o emulador vai usar o próprio valor para ativar a saída do Logcat para o terminal por padrão. Você também pode redirecionar as mesmas mensagens de registro, ou outras, para o terminal usando adb.

Para saber mais sobre o Logcat e o adb, consulte Ferramenta de linha de comando do Logcat, Ver e gravar registros com o Logcat, classe Log e Emitir comandos do adb.

-show-kernel Mostra mensagens de depuração do kernel na janela do terminal. Por exemplo:

emulator @Pixel8_API_34 -show-kernel

Um uso dessa opção é verificar se o processo de inicialização funciona corretamente.

-verbose Exibe mensagens de inicialização do emulador na janela do terminal. Por exemplo:

emulator @Pixel8_API_34 -verbose

Ele exibe os arquivos e as configurações que estão realmente selecionados ao iniciar um dispositivo virtual definido em um AVD. Essa opção é o mesmo que especificar -debug-init.

Rede
-dns-server servers Usa os servidores DNS especificados. servers é uma lista separada por vírgulas de até quatro nomes de servidores DNS ou endereços IP. Por exemplo:
emulator @Pixel8_API_34 -dns-server 192.0.2.0,
192.0.2.255

Por padrão, o emulador tenta detectar os servidores DNS que você está usando e configura aliases especiais na rede de firewalls emulada para permitir que o sistema Android se conecte diretamente a eles. Use a opção -dns-server para especificar uma lista diferente de servidores DNS.

-http-proxy proxy Faz todas as conexões TCP usando um proxy HTTP/HTTPS especificado. Se o emulador precisa acessar a Internet com um servidor proxy, você pode usar essa opção ou a variável de ambiente http_proxy para definir o redirecionamento adequado. Por exemplo:

emulator @Pixel8_API_34 -http-proxy myserver:1981

proxy pode ser um destes links:

http://server:port
http://username:password@server:port

O prefixo http:// pode ser omitido.

Se essa opção não for fornecida, o emulador vai pesquisar a variável de ambiente http_proxy e usar automaticamente qualquer valor correspondente ao formato proxy. Para saber mais, consulte Como usar o emulador com um proxy.

-netdelay delay

Define a emulação de latência da rede como um destes valores delay em milissegundos:

  • gsm: GSM/CSD (mín. 150, máx. 550).
  • hscsd: HSCSD (mín. 80, máx. 400).
  • gprs: GPRS (mín. 35, máx. 200).
  • edge: EDGE/EGPRS (mín. 80, máx. 400).
  • umts: UMTS/3G (mín. 35, máx. 200).
  • hsdpa: HSDPA (mín. 0, máx. 0).
  • lte: LTE (mín. 0, máx. 0).
  • evdo: EVDO (mín. 0, máx. 0).
  • none: sem latência, o padrão (mín. 0, máx. 0).
  • num: especifica a latência exata.
  • min:max: especifica latências mínimas e máximas individuais.

Por exemplo:

emulator @Pixel8_API_34 -netdelay gsm

O emulador tem suporte à limitação de rede e a maiores latências de conexão. Você pode defini-la pela configuração de aparência ou com as opções ‑netspeed e -netdelay.

-netfast Desativa a limitação de rede. Por exemplo:

emulator @Pixel8_API_34 -netfast

Esta opção é igual a especificar -netspeed full -netdelay none. Esses são os valores padrão para essas opções.

-netspeed speed

Define a emulação de velocidade da rede. Especifica as velocidades máximas de upload e download da rede com um dos seguintes valores de speed em kbps:

  • gsm: GSM/CSD (upload: 14,4, download: 14,4).
  • hscsd: HSCSD (upload: 14,4, download: 57,6).
  • gprs: GPRS (upload: 28,8, download: 57,6).
  • edge: EDGE/EGPRS (upload: 473,6, download: 473,6).
  • umts: UMTS/3G (upload: 384, download: 384).
  • hsdpa: HSDPA (upload: 5.760, download: 13.980).
  • lte: LTE (upload: 58.000, download: 173.000).
  • evdo: EVDO (upload: 75.000, download: 280.000).
  • full: sem limite, o padrão (upload: 0.0, download: 0.0).
  • num: especifica a velocidade de upload e download.
  • up:down: especifica as velocidades individuais de upload e download.

Por exemplo:

emulator @Pixel8_API_34 -netspeed edge

O emulador tem suporte à limitação de rede e a maiores latências de conexão. Você pode defini-la pela configuração de aparência ou com as opções ‑netspeed e -netdelay.

-port port Define o número da porta TCP usada para o console e adb. Por exemplo:

emulator @Pixel8_API_34 -port 5556

O valor padrão é 5554 para a primeira instância de dispositivo virtual em execução na sua máquina. Um dispositivo virtual normalmente ocupa um par de portas adjacentes: uma porta de console e uma porta adb. O console do primeiro dispositivo virtual em execução em uma determinada máquina usa a porta do console 5554 e a porta adb 5555. As instâncias subsequentes usam números de porta que aumentam em dois. Por exemplo, 5556/5557, 5558/5559 e assim por diante. O intervalo é de 5554 a 5682, permitindo 64 dispositivos virtuais simultâneos.

As atribuições de porta geralmente são iguais a especificar -ports port,{port + 1}. {port + 1} precisa estar livre e reservado para adb. Se qualquer uma das portas do console ou adb já estiver em uso, o emulador não será iniciado.

A opção ‑port informa quais portas e número de série o dispositivo virtual está usando e avisa se há algum problema com os valores fornecidos. Na interface do emulador, é possível ver o número da porta do console no título da janela e o número da porta adb selecionando Help > About.

Se o valor de port não for uniforme e estiver no intervalo entre 5554 e 5584, o dispositivo virtual será iniciado, mas não ficará visível quando você usar o comando adb devices se o adb server for iniciado após o emulador. Por esse motivo, recomendamos o uso de um número de porta par para o console.

-ports
console-port,adb-port
Define as portas TCP usadas para o console e adb. Por exemplo:

emulator @Pixel8_API_34 -ports 5556,5559

O intervalo de portas válido é de 5554 a 5682, permitindo 64 dispositivos virtuais simultâneos. A opção -ports informa quais portas e qual número de série a instância do emulador está usando e avisa se há algum problema com os valores fornecidos.

Recomendamos usar a opção -port sempre que possível. A opção -ports está disponível para configurações de rede que exigem configurações especiais.

Para saber mais sobre a configuração das portas do console e do adb, consulte a opção -port.

-tcpdump filepath Captura pacotes de rede e os armazena em um arquivo. Por exemplo:

emulator @Pixel8_API_34 -tcpdump /path/dumpfile.cap

Use esta opção para começar a capturar todos os pacotes de rede que são enviados pela LAN Ethernet virtual do emulador. Em seguida, use uma ferramenta como o Wireshark para analisar o tráfego.

Esta opção captura todos os pacotes Ethernet e não está limitada a conexões TCP.

Sistema
-accel mode Configura a aceleração de VM do emulador. Por exemplo:

emulator @Pixel8_API_34 -accel auto

A emulação acelerada funciona apenas para imagens do sistema x86 e x86_64. No Linux, ela depende da KVM. No Windows e Mac, ela conta com CPU da Intel e um driver Intel HAXM. Essa opção é ignorada se você não estiver emulando um dispositivo x86 ou x86_64.

Estes são os valores válidos para mode:

  • auto: determina automaticamente se a aceleração tem suporte e a usa quando possível (padrão).
  • off: desativa totalmente a aceleração, o que é útil principalmente para depuração.
  • on: força a aceleração. Se a KVM ou o HAXM não estiverem instalados ou não forem utilizáveis, o emulador não será iniciado e exibirá uma mensagem de erro.

Para saber mais, consulte Configurar a aceleração de hardware para o Android Emulator.

-accel-check Verifica se um hipervisor obrigatório para aceleração de VM do emulador está instalado (HAXM ou KVM). Por exemplo:

emulator -accel-check

Para saber mais, consulte Verificar se há um hipervisor instalado.

-engine engine

Especifica o mecanismo do emulador:

  • auto: seleciona automaticamente um mecanismo (padrão).
  • classic: usa o mecanismo QEMU 1 mais antigo (descontinuado).
  • qemu2: usa o novo mecanismo QEMU 2.

Por exemplo:

emulator @Pixel8_API_34 -engine auto

A detecção automática indica o valor que fornece a melhor performance ao emular um determinado AVD. Use a opção -engine apenas para fins de depuração e comparação.

-gpu mode Seleciona o modo de emulação de GPU. Por exemplo:

emulator @Pixel8_API_34 -gpu swiftshader_indirect

Para saber mais, consulte Configurar aceleração gráfica.

-no-accel Desativa a aceleração da VM do emulador ao usar uma imagem do sistema x86 ou x86_64. É útil apenas para depuração e é igual a especificar -accel off. Por exemplo:

emulator @Pixel8_API_34 -no-accel

Para saber mais, consulte Configurar a aceleração de hardware para o Android Emulator.

-nojni
-no-jni
Desativa as verificações estendidas da Java Native Interface (JNI) no ambiente de execução do Android Dalvik ou ART. Por exemplo:

emulator @Pixel8_API_34 -nojni

Quando você inicia um dispositivo virtual, as verificações estendidas da JNI são ativadas por padrão. Para ver mais informações, consulte Dicas sobre a JNI.

-selinux {disabled|permissive} Define o módulo de segurança do Security-Enhanced Linux (SELinux) para o modo disabled ou permissive em um sistema operacional Linux. Por exemplo:

me-linux$ emulator @Pixel8_API_34 -selinux permissive

Por padrão, o SELinux está no modo enforcing, o que significa que a política de segurança é aplicada. O modo permissive carrega a política do SELinux, mas não a aplica. Essa opção registra apenas violações de políticas. O modo disabled desativa o suporte ao kernel para SELinux.

-timezone timezone

Define o fuso horário do dispositivo virtual para timezone, em vez do fuso horário do host. Por exemplo:

emulator @Pixel8_API_34 -timezone Europe/Paris

Por padrão, o emulador usa o fuso horário do computador de desenvolvimento. Use essa opção para especificar um fuso horário diferente ou se a detecção automática não estiver funcionando corretamente. O valor timezone precisa estar no formato zoneinfo (em inglês), que é area/location ou area/subarea/location. Por exemplo:

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

O fuso horário especificado precisa estar no banco de dados zoneinfo.

-version Mostra o número da versão do emulador. Por exemplo:

emulator @Pixel8_API_34 -version

Ou

emulator -version
interface
-no-boot-anim Desativa a animação de inicialização para acelerar o processo durante a inicialização do emulador. Por exemplo:

emulator @Pixel8_API_34 -no-boot-anim

Em computadores mais lentos, essa opção pode acelerar significativamente a sequência de inicialização.

-screen mode Define o modo da tela touchscreen emulada. Por exemplo:

emulator @Pixel8_API_34 -screen no-touch

O mode pode ter qualquer um destes valores:

  • touch: emula uma tela touchscreen (padrão).
  • multi-touch: emula uma tela multitoque.
  • no-touch: desativa a emulação de toque e de tela multitoque.

Opções avançadas

As opções de inicialização de linha de comando na tabela a seguir estão disponíveis, mas não são usadas com frequência pelo desenvolvedor médio do app.

Nas descrições, o diretório de trabalho é o diretório atual no terminal em que você está inserindo comandos. Para saber mais sobre o diretório de sistema, o diretório de dados do AVD e os arquivos armazenados nele, consulte a seção sobre diretórios e arquivos padrão.

Algumas destas opções são adequadas para desenvolvedores de apps externos, e algumas delas são usadas principalmente por desenvolvedores de plataformas. Os desenvolvedores de apps criam apps Android e os executam em AVDs específicos. Os desenvolvedores de plataformas trabalham no sistema Android e o executam dentro do emulador sem nenhum AVD pré-criado.

Tabela 4. Opções avançadas de linha de comando.

Opção avançada Breve descrição
-bootchart timeout

Ativa a inicialização, com um tempo limite em segundos. Algumas imagens do sistema Android têm um sistema init modificado que integra um recurso de inicialização. Você pode passar um período de tempo limite de inicialização para o sistema com essa opção. Caso seu sistema init não tenha a inicialização ativada, a opção não fará nada. Essa opção é útil principalmente para desenvolvedores de plataformas, não para desenvolvedores de apps externos.

Por exemplo:

emulator @Pixel8_API_34 -bootchart 120
-cache filepath

Especifica um arquivo de imagem da partição de cache. Fornece um nome de arquivo e um caminho absoluto ou relativo ao diretório de dados para configurar um arquivo de cache persistente. Se o arquivo não existir, o emulador o criará como um arquivo vazio.

Por exemplo:

emulator @Pixel8_API_34 -cache
   ~/.android/avd/Pixel8_API_34.avd/cache_persistent.img

Se você não usar essa opção, o padrão será um arquivo temporário chamado cache.img. Para saber mais, consulte o diretório de dados do AVD.

-cache-size size

Define o tamanho da partição de cache em MB.

Por exemplo:

emulator @Pixel8_API_34 -cache-size 1000

Se você não especificar essa opção, o padrão será 66 MB. Normalmente, a maioria dos desenvolvedores de apps não precisa dessa opção, a menos que precisem fazer o download de arquivos maiores do que o cache padrão. Para saber mais sobre o arquivo de cache, consulte o diretório de dados do AVD.

-data filepath

Define o arquivo de imagem da partição de dados do usuário. Fornece um nome de arquivo e um caminho absoluto ou relativo ao diretório de trabalho para configurar um arquivo de dados do usuário persistente. Se o arquivo não existir, o emulador criará uma imagem usando o arquivo userdata.img padrão, armazenando-o no nome de arquivo especificado e mantendo os dados do usuário no encerramento.

Por exemplo:

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

Se você não usar essa opção, o padrão será um arquivo chamado userdata-qemu.img. Para saber mais sobre o arquivo de dados do usuário, consulte o diretório de dados do AVD.

-datadir dir

Especifica um diretório de dados usando um caminho absoluto. Para saber mais, consulte o diretório de dados do AVD.

Por exemplo:

emulator @Pixel8_API_34 -datadir
   ~/.android/avd/Pixel8_API_34.avd/mytest
-force-32bit

Usa o emulador de 32 bits em plataformas de 64 bits. Ocasionalmente, essa opção é útil para testes ou depuração. Por exemplo, havia um problema em que o emulador às vezes não era executado no Windows de 64 bits, mas era no de 32 bits. Essa opção foi útil para fazer comparações e depurar o problema. Veja um exemplo:

emulator @Pixel8_API_34 -force-32bit
-help-disk-images

Recebe ajuda sobre imagens de disco. Essa opção fornece informações relevantes para desenvolvedores de apps e plataformas. Por exemplo:

emulator -help-disk-images
-help-char-devices

Recebe ajuda sobre as especificações de caracteres device. Um parâmetro de device é exigido por algumas opções de emulador. Por exemplo:

emulator -help-char-devices
-help-sdk-images

Recebe ajuda sobre as imagens de disco relevantes para desenvolvedores de apps. Essa opção detecta onde os arquivos de imagem estão localizados para um AVD criado com as Ferramentas do SDK. Por exemplo:

emulator -help-sdk-images
-help-build-images

Recebe ajuda sobre as imagens de disco relevantes para desenvolvedores de plataformas. Por exemplo:

emulator -help-build-images
-initdata filepath
-init-data filepath

Especifica a versão inicial da partição de dados. Depois de excluir permanentemente os dados do usuário, o emulador copia o conteúdo do arquivo especificado para os dados do usuário (por padrão, o arquivo userdata-qemu.img) em vez de usar o arquivo userdata.img padrão como a versão inicial. Fornece o nome do arquivo e um caminho absoluto ou relativo para o diretório de trabalho.

Por exemplo:

emulator @Pixel8_API_34 -initdata
   ~/Library/Android/sdk/system-images/android-34/
   google_apis/x86_64/userdata-test.img

Se você não especificar um caminho, ele vai colocar o arquivo no diretório do sistema. Para saber mais, consulte o diretório do sistema AVD.

-kernel filepath

Usa um kernel emulado específico. Se você não especificar um caminho, o emulador vai procurar no diretório do sistema.

Use a opção ‑show‑kernel para ver as mensagens de depuração do kernel.

Por exemplo:

emulator @Pixel8_API_34 -kernel
   ~/Library/Android/sdk/system-images/android-34/
   google_apis/x86_64/kernel-test.img -show-kernel

Se você não especificar essa opção, o padrão será kernel-ranchu. Para saber mais, consulte o diretório do sistema AVD.

-noaudio
-no-audio

Desativa o suporte de áudio para esse dispositivo virtual. Alguns computadores Linux e Windows têm drivers de áudio com falhas que causam sintomas diferentes, como impedir que o emulador seja iniciado. Nesse caso, use essa opção para resolver o problema. Como alternativa, você pode usar a variável de ambiente QEMU_AUDIO_DRV para mudar o back-end de áudio.

Por exemplo:

emulator @Pixel8_API_34 -noaudio
-nocache
-no-cache

Inicia o emulador sem uma partição de cache. Se você não usar essa opção, o padrão será um arquivo temporário chamado cache.img. Essa opção é apenas para desenvolvedores de plataformas. Para mais informações, consulte o diretório de dados do AVD.

Por exemplo:

emulator @Pixel8_API_34 -nocache
-no-snapshot

Inibe tanto o carregamento automático quanto as operações de salvamento, fazendo com que o emulador execute uma sequência de inicialização completa e perca o estado quando fechado. Ele substitui a opção -snapshot.

Por exemplo:

emulator @Pixel8_API_34 -no-snapshot
-no-snapshot-load

Evita que o emulador carregue o estado AVD do armazenamento de snapshots. Realiza uma inicialização completa.

Por exemplo:

emulator @Pixel8_API_34 -no-snapshot-load
-no-snapshot-save

Evita que o emulador salve o estado do AVD no armazenamento de snapshots ao sair, o que significa que todas as mudanças serão perdidas.

Por exemplo:

emulator @Pixel8_API_34 -no-snapshot-save
-no-snapshot-update-time

Não tenta corrigir a hora do relógio do AVD imediatamente na restauração do snapshot. Essa opção pode ser útil durante o teste, porque evita um salto de tempo repentino. Atualizações de tempo ainda serão enviadas para o AVD a cada 15 segundos.

Por exemplo:

emulator @Pixel8_API_34 -no-snapshot-update-time
-no-snapstorage

Inicie o emulador sem ativar um arquivo para armazenar ou carregar snapshots de estado, forçando uma inicialização completa e desativando a funcionalidade de snapshot de estado. Essa opção modifica as opções -snapstorage e -snapshot.

Por exemplo:

emulator @Pixel8_API_34 -no-snapstorage
-no-window

Desativa a exibição da janela gráfica no emulador. Essa opção é útil ao executar o emulador em servidores que não têm exibição. Você pode acessar o emulador por adb ou pelo console. Por exemplo:

emulator @Pixel8_API_34 -no-window
-partition-size size

Especifica o tamanho da partição de dados do sistema em MB. Por exemplo:

emulator @Pixel8_API_34 -partition-size 1024
-prop name=value

Define uma propriedade do sistema Android no emulador na inicialização. name precisa ser um nome de propriedade rotulado como qemu_prop de no máximo 32 caracteres, sem espaços, e value precisa ser uma string de no máximo 92 caracteres. Para ver um exemplo, consulte o arquivo property_contexts. Você pode especificar várias opções de ‑prop em uma linha de comando. Essa opção pode ser útil para depuração. Por exemplo:

emulator @Pixel8_API_34 -prop qemu.name=value -prop qemu.abc=xyz
-qemu args Transmite argumentos para o software do emulador QEMU. Ao usar essa opção, ela precisa ser a última opção especificada, porque todas as opções depois dela são interpretadas como específicas do QEMU. Essa opção é bastante avançada, e recomendamos que seja usada somente por desenvolvedores que estejam muito familiarizados com emulação QEMU e Android.
-qemu -h

Mostra a ajuda do -qemu. Por exemplo:

emulator -qemu -h
-ramdisk filepath

Especifica uma imagem de inicialização do ramdisk. Especifica o nome do arquivo e um caminho absoluto ou relativo ao diretório de trabalho.

Por exemplo:

emulator @Pixel8_API_34 -ramdisk
   ~/Library/Android/sdk/system-images/android-34/
   google_apis/x86_64/ramdisk-test.img

Se você não usar essa opção, o padrão será o arquivo ramdisk.img no diretório do sistema. Para saber mais, consulte o diretório do sistema AVD.

-report-console socket

Informa a porta do console para um terceiro remoto antes de iniciar a emulação. Pode ser útil para um script de teste automatizado. socket precisa usar um destes formatos:

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

Para saber mais, use a opção -help-report-console, conforme descrito na seção sobre ajuda para opções específicas.

-shell

Cria um console do shell raiz no terminal atual. Essa opção é diferente do comando adb shell das seguintes maneiras:

  • Ela cria um shell raiz que permite modificar várias partes do sistema.
  • Ela vai funcionar mesmo se o adb daemon no sistema emulado estiver corrompido.
  • Pressione Ctrl + C (ou Command + C no macOS) para interromper o emulador em vez do shell.

Por exemplo:

emulator @Pixel8_API_34 -shell
-snapshot name

Especifica o nome de um snapshot dentro de um arquivo de armazenamento de snapshots para iniciar e salvar operações automaticamente.

Em vez de executar uma sequência de inicialização completa, o emulador pode retomar a execução de um snapshot de estado anterior, que costuma ser significativamente mais rápido. Quando você fornece essa opção, o emulador carrega o snapshot desse nome usando a imagem e o salva com o mesmo nome na saída.

Se você não usar essa opção, o padrão será uma sequência de inicialização completa. Se o snapshot especificado não existir, o emulador vai executar uma sequência de inicialização completa e uma operação de salvamento.

Consulte a opção -snapstorage para saber mais sobre como especificar um arquivo de armazenamento de snapshot e o arquivo padrão.

emulator @Pixel8_API_34 -snapshot snapshot2

No processo de carregamento de um snapshot, todo o conteúdo do sistema, os dados do usuário e as imagens do cartão SD são substituídos pelo conteúdo que eles continham quando o snapshot foi feito. A menos que você salve essas informações em um snapshot diferente, todas as mudanças feitas desde então serão perdidas.

Você também pode criar um snapshot no console do emulador usando o comando avd snapshot save name. Para saber mais, consulte Enviar comandos do console do emulador.

-snapshot-list

Mostra uma lista de snapshots disponíveis. O comando exibe uma tabela de snapshots armazenados no arquivo em que o emulador foi iniciado e, em seguida, a fecha. Se você especificar -snapstorage file, esse comando exibirá uma tabela dos snapshots armazenados no arquivo.

Por exemplo:

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

Você pode usar os valores da coluna ID e TAG na saída como argumentos para a opção -snapshot.

-snapstorage filepath

Especifica um arquivo de repositório que contenha todos os snapshots de estado. Todos os snapshots feitos durante a execução são salvos nesse arquivo. Somente snapshots armazenados nesse arquivo podem ser restaurados durante a execução do emulador.

Por exemplo:

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

Se você não especificar essa opção, o padrão será snapshots.img no diretório de dados. Se o arquivo especificado não existir, o emulador será iniciado, mas sem suporte a salvamento ou carregamento de snapshots de estado.

-sysdir dir

Especifica um diretório do sistema usando um caminho absoluto. Para saber mais, consulte o diretório do sistema AVD. Por exemplo:

emulator @Pixel8_API_34 -sysdir
   ~/Library/Android/sdk/system-images/android-34/
   google_apis/x86_64/test
-system filepath

Especifica um arquivo inicial do sistema. Fornece o nome do arquivo e um caminho absoluto ou relativo para o diretório de trabalho.

Por exemplo:

emulator @Pixel8_API_34 -system
   ~/Library/Android/sdk/system-images/android-34/
   google_apis/x86_64/system-test.img

Se você não usar essa opção, o padrão será o arquivo system.img no diretório do sistema. Para saber mais, consulte o diretório do sistema AVD.

-use-system-libs

No Linux, usa o sistema libstdc++ em vez da versão empacotada com o sistema do emulador. Use essa opção apenas se o emulador não for iniciado normalmente. Ela nem sempre funciona. Como alternativa, defina a variável de ambiente ANDROID_EMULATOR_USE_SYSTEM_LIBS como 1.

Por exemplo:

me-linux$ emulator @Pixel8_API_34 -use-system-libs
-writable-system

Use essa opção para ter uma imagem do sistema gravável durante a sessão de emulação. Para fazer isso:

  1. Inicie um dispositivo virtual com a opção -writable-system.
  2. Digite o comando adb remount em um terminal de comando para dizer ao emulador para montar system/ novamente como leitura/gravação. Por padrão, ele é montado como somente leitura.

O uso dessa flag cria uma cópia temporária da imagem do sistema que pode ser muito grande, até várias centenas de MB, mas que será destruída quando o emulador for fechado.

Opções descontinuadas

Estas opções de linha de comando foram descontinuadas:

  • -audio-in
  • -audio-out
  • -charmap
  • -code-profile
  • -cpu-delay
  • -dpi-device
  • -dynamic_skin
  • -enable-kvm
  • -gps
  • -image
  • -keyset
  • -help-keys
  • -help-keyset-file
  • -nand-limits
  • -noskin
  • -no-skin
  • -onion
  • -onion-alpha
  • -onion-rotation
  • -radio
  • -ranchu
  • -raw-keys
  • -scale
  • -shared-net-id
  • -shell-serial
  • -skin
  • -skindir
  • -trace
  • -useaudio

Ajuda sobre opções de linha de comando

Esta seção descreve como receber ajuda sobre as opções de linha de comando. Ela fornece informações mais detalhadas sobre as opções de linha de comando do emulador mais usadas, que estão disponíveis quando você inicia o emulador.

Listar todas as opções do emulador

Para exibir uma lista de todas as opções do emulador, incluindo uma breve descrição, digite este comando:

emulator -help

Ajuda detalhada para uma opção específica

Para receber ajuda para uma opção de inicialização específica, digite este comando:

emulator -help-option

Por exemplo:

emulator -help-netspeed

Essa ajuda é mais detalhada que a descrição fornecida pela opção -help.

Ajuda detalhada para todas as opções

Para receber ajuda detalhada para todas as opções do emulador, digite este comando:

emulator -help-all

Listar variáveis de ambiente do emulador

Para ver uma lista de variáveis de ambiente do emulador, digite este comando:

emulator -help-environment

Antes de iniciar um dispositivo virtual, defina variáveis de ambiente na janela do terminal ou nas configurações de usuário no sistema operacional. Por exemplo, no arquivo .bashrc no Linux.

Listar tags de depuração

Para mostrar uma lista de tags para as opções de -debug, digite este comando:

emulator -help-debug-tags

As opções -debug permitem ativar ou desativar mensagens de depuração de componentes específicos do emulador, conforme especificado pelas tags.