Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

Android Debug Bridge (adb)

O Android Debug Bridge (adb) é uma ferramenta de linha de comando versátil que permite a comunicação com um dispositivo. O comando adb facilita uma variedade de ações do dispositivo, como instalar e depurar apps, e fornece acesso a um shell Unix que pode ser usado para executar diversos comandos em um dispositivo. Ele é um programa cliente-servidor com três componentes:

  • Um cliente, que envia comandos. O cliente é executado no computador de desenvolvimento. Você pode emitir um comando adb para invocar o cliente de um terminal de linha de comando.
  • Um daemon (adbd), que executa comandos em um dispositivo. O daemon é executado como um processo em segundo plano em cada dispositivo.
  • Um servidor, que gerencia a comunicação entre o cliente e o daemon. O servidor é executado como um processo em segundo plano no computador de desenvolvimento.

adb está incluído no pacote Android SDK Platform-Tools. Você pode fazer o download desse pacote com o SDK Manager, que o instala em android_sdk/platform-tools/. Ou, se você quiser o pacote autônomo Android SDK Platform-Tools, faça o download aqui.

Para mais informações sobre como conectar um dispositivo para uso no ADB, incluindo como usar o assistente de conexão para solucionar problemas comuns, consulte Executar aplicativos em um dispositivo de hardware.

Como o adb funciona

Quando você inicia um cliente do adb, ele primeiro verifica se há um processo de servidor do adb em execução. Se não houver, ele inicia esse processo. Quando o servidor é iniciado, ele é vinculado à porta TCP 5037 local e escuta comandos enviados de clientes do adb. Todos os clientes do adb usam a porta 5037 para se comunicar com o servidor do adb.

Em seguida, o servidor configura as conexões para todos os dispositivos em execução. Ele localiza os emuladores por meio da varredura de portas de número ímpar no intervalo de 5555 a 5585, o intervalo usado pelos primeiros 16 emuladores. Onde o servidor encontrar um daemon do adb (adbd), ele configurará uma conexão com a porta em questão. Observe que cada emulador usa um par de portas sequenciais: uma porta com numeração par para conexões de console e uma porta ímpar para conexões adb. Por exemplo:

Emulador 1, console: 5554
Emulador 1, adb: 5555
Emulador 2, console: 5556
Emulador 2, adb: 5557
e assim por diante.

Conforme mostrado, o emulador conectado ao adb na porta 5555 é o mesmo cujo console escuta na porta 5554.

Depois que o servidor tiver configurado conexões com todos os dispositivos, você poderá usar os comandos adb para acessá-los. Como o servidor gerencia conexões com dispositivos e manipula comandos de vários clientes adb, você pode controlar qualquer dispositivo de qualquer cliente (ou de um script).

Ative a depuração do adb no seu dispositivo

Para usar o adb com um dispositivo conectado via USB, você precisa ativar a opção Depuração USB nas configurações do sistema do dispositivo, em Opções do desenvolvedor.

No Android 4.2 e versões posteriores, a tela "Opções do desenvolvedor" normalmente fica oculta por padrão. Para exibi-la, acesse Config. > Sobre o dispositivo e toque em Número da versão sete vezes. Retorne à tela anterior para encontrar as Opções do desenvolvedor na parte inferior.

Em alguns dispositivos, a tela "Opções do desenvolvedor" pode ter uma localização ou um nome diferente.

Agora você pode conectar seu dispositivo a uma porta USB. Você pode verificar se o dispositivo está conectado executando adb devices no diretório android_sdk/platform-tools/. Se eles estiverem conectados, o nome do dispositivo estará listado como “device”.

Observação: ao conectar um dispositivo com Android 4.2.2 ou versões posteriores, o sistema mostrará uma caixa de diálogo perguntando se o usuário quer aceitar uma Chave RSA que permite a depuração por meio do computador. Esse mecanismo de segurança protege dispositivos de usuários, porque garante que a depuração USB e outros comandos do adb não sejam executados, a não ser que o você consiga desbloquear o dispositivo e confirmar a caixa de diálogo.

Para saber mais sobre a conexão com um dispositivo por USB, leia Executar aplicativos em um dispositivo de hardware.

Conectar-se a um dispositivo por Wi-Fi

O adb geralmente se comunica com o dispositivo via USB, mas você também pode usar o adb via Wi-Fi após algumas configurações iniciais via USB, conforme descrito abaixo. Se você está desenvolvendo para o Wear OS, no entanto, consulte o guia para depurar um app do Wear OS, que tem instruções especiais para usar o adb com Wi-Fi e Bluetooth.

  1. Conecte o dispositivo Android e o computador host do adb a uma rede Wi-Fi acessível a ambos os dispositivos. Esteja ciente de que nem todos os pontos de acesso são adequados: pode ser necessário usar um ponto de acesso cujo firewall esteja corretamente configurado para que haja compatibilidade com adb.
  2. Se você estiver se conectando a um dispositivo Wear OS, desative o Bluetooth no smartphone que está pareado com o dispositivo.
  3. Conecte o dispositivo ao computador host usando um cabo USB.
  4. Configure o dispositivo de destino para detectar uma conexão TCP/IP na porta 5555.
        adb tcpip 5555
        
  5. Desconecte a porta USB do dispositivo de destino.
  6. Encontre o endereço IP do dispositivo Android. Por exemplo, em um dispositivo Nexus, você pode encontrar o endereço IP em Config. > Sobre o tablet (ou Sobre o dispositivo) > Status > Endereço IP. Ou, em um dispositivo Wear OS, você pode encontrar o endereço IP em Config. > Configurações de Wi-Fi > Avançado > Endereço IP.
  7. Conecte-se ao dispositivo pelo endereço IP.
        adb connect device_ip_address
        
  8. Confirme se seu computador host está conectado ao dispositivo de destino:
        $ adb devices
        List of devices attached
        device_ip_address:5555 device
        

Pronto!

Se você perder a conexão com o adb:

  1. Verifique se o host ainda está conectado à mesma rede Wi-Fi que o dispositivo Android.
  2. Execute o comando adb connect novamente para reconectar.
  3. Se isso não funcionar, redefina o host do adb:
        adb kill-server
        

    Em seguida, reinicie o processo.

Consultar dispositivos

Antes de emitir comandos do adb, é útil saber quais instâncias do dispositivo estão conectadas ao servidor do adb. Para gerar uma lista de dispositivos conectados, use o comando devices:

      adb devices -l
      

Em resposta, o adb imprime as seguintes informações de status para cada dispositivo:

  • Número de série: uma string criada pelo adb para identificar exclusivamente o dispositivo pelo número da porta. Veja um exemplo de número de série: emulator-5554
  • Estado: o estado da conexão do dispositivo pode ser um dos seguintes:
    • offline: o dispositivo não está conectado ao adb ou não está respondendo.
    • device: o dispositivo está conectado ao servidor do adb. Observe que esse estado não implica que o sistema Android está totalmente inicializado e operacional, porque o dispositivo se conecta ao adb enquanto o sistema ainda está sendo inicializado. No entanto, após a inicialização, esse é o estado operacional normal de um dispositivo.
    • no device: não há um dispositivo conectado.
  • Descrição: se você incluir a opção -l, o comando devices informará qual é o dispositivo. Essa informação é útil quando você tem vários dispositivos conectados para que você possa diferenciá-los.

O exemplo a seguir mostra o comando devices e a saída dele. Existem três dispositivos em execução. As duas primeiras linhas da lista são emuladores e a terceira linha é um dispositivo de hardware conectado ao computador.

$ adb devices
    List of devices attached
    emulator-5556 device product:sdk_google_phone_x86_64 model:Android_SDK_built_for_x86_64 device:generic_x86_64
    emulator-5554 device product:sdk_google_phone_x86 model:Android_SDK_built_for_x86 device:generic_x86
    0a388e93      device usb:1-1 product:razor model:Nexus_7 device:flo
    

Emulador não listado

O comando adb devices tem uma sequência de comando de caso isolado que faz com que o emulador em execução não apareça na saída de adb devices mesmo que os emuladores estejam visíveis na sua área de trabalho. Isso acontece quando todas as condições a seguir são verdadeiras:

  1. O servidor adb não está em execução.
  2. Você usa o comando emulator com a opção -port ou -ports com um valor de porta ímpar entre 5554 e 5584.
  3. A porta de numeração ímpar escolhida não está ocupada, portanto, a conexão pode ser feita no número de porta especificado ou, se estiver ocupada, o emulador alterna para outra porta que atende aos requisitos de 2.
  4. Você inicia o servidor adb depois de iniciar o emulador.

Uma maneira de evitar essa situação é deixar o emulador escolher as próprias portas e não executar mais de 16 emuladores de uma só vez. Outra maneira é sempre iniciar o servidor adb antes de usar o comando emulator, conforme explicado nos exemplos a seguir.

Exemplo 1: na sequência a seguir, o comando adb devices inicia o servidor adb, mas a lista de dispositivos não é exibida.

Pare o servidor adb e insira os seguintes comandos na ordem mostrada. Para o nome do avd, forneça um nome de avd válido do seu sistema. Para ver uma lista de nomes de avd, digite emulator -list-avds. O comando emulator está no diretório android_sdk/tools.

    $ adb kill-server
    $ emulator -avd Nexus_6_API_25 -port 5555
    $ adb devices

    List of devices attached
    * daemon not running. starting it now on port 5037 *
    * daemon started successfully *
    

Exemplo 2: na sequência de comandos a seguir, adb devices exibe a lista de dispositivos, porque o servidor adb foi iniciado primeiro.

Para ver o emulador na saída de adb devices, pare o servidor do adb e reinicie-o depois de usar o comando emulator e antes de usar o comando adb devices, da seguinte maneira:

    $ adb kill-server
    $ emulator -avd Nexus_6_API_25 -port 5557
    $ adb start-server
    $ adb devices

    List of devices attached
    emulator-5557 device
    

Para mais informações sobre as opções de linha de comando do emulador, consulte Como usar os parâmetros da linha de comando.

Enviar comandos a um dispositivo específico

Se vários dispositivos estiverem em execução, você precisará especificar o dispositivo de destino ao emitir o comando adb. Para especificar o destino, use o comando devices e veja o número de série do destino. Com o número de série em mãos, use a opção -s com os comandos adb para especificar o número de série. Se você emitir muitos comandos adb, defina a variável de ambiente $ANDROID_SERIAL para conter o número de série. Se você usar tanto -s como $ANDROID_SERIAL, -s substituirá $ANDROID_SERIAL.

No exemplo a seguir, a lista de dispositivos anexados é recebida e, em seguida, o número de série de um dos dispositivos é usado para instalar o helloWorld.apk nesse dispositivo.

    $ adb devices
    List of devices attached
    emulator-5554 device
    emulator-5555 device

    $ adb -s emulator-5555 install helloWorld.apk
    

Observação: se você emitir um comando sem especificar um dispositivo de destino quando vários dispositivos estiverem disponíveis, o adb gerará um erro.

Se você tiver vários dispositivos disponíveis, mas apenas um for um emulador, use a opção -e para enviar comandos ao emulador. Da mesma forma, se houver vários dispositivos, mas apenas um dispositivo de hardware anexado, use a opção -d para enviar comandos ao dispositivo de hardware.

Instalar um app

Você pode usar o adb para instalar um APK em um emulador ou dispositivo conectado com o comando install:

    adb install path_to_apk
    

Use a opção -t com o comando install ao instalar um APK de teste. Para mais informações, consulte -t.

Para saber mais sobre a criação de um arquivo de APK que possa ser instalado em uma instância de emulador/dispositivo, consulte Compilar e executar seu aplicativo.

Observe que, se você estiver usando o Android Studio, não precisará usar o adb diretamente para instalar seu app no emulador/dispositivo. Em vez disso, o Android Studio realizará o empacotamento e a instalação do app para você.

Configurar o encaminhamento de portas

É possível usar o comando forward para configurar o encaminhamento de portas arbitrário, que encaminha solicitações em uma porta de host específica para uma porta diferente em um dispositivo. O exemplo a seguir configura o encaminhamento da porta de host 6100 para a porta de dispositivo 7100:

    adb forward tcp:6100 tcp:7100
    

O exemplo a seguir configura o encaminhamento da porta de host 6100 para local:logd:

    adb forward tcp:6100 local:logd
    

Copiar arquivos de/para um dispositivo

Use os comandos pull e push para copiar arquivos de e para um dispositivo. Diferentemente do comando install, que apenas copia um arquivo de APK para um local específico, os comandos pull e push permitem copiar diretórios e arquivos arbitrários para qualquer local em um dispositivo.

Para copiar um arquivo ou diretório e os subdiretórios dele a partir do dispositivo, faça o seguinte:

    adb pull remote local
    

Para copiar um arquivo ou diretório e os subdiretórios dele para o dispositivo, faça o seguinte:

    adb push local remote
    

Substitua local e remote pelos caminhos para o diretório/os arquivos de destino na máquina de desenvolvimento (local) e no dispositivo (remoto). Por exemplo:

    adb push foo.txt /sdcard/foo.txt
    

Interromper o servidor do adb

Em alguns casos, é preciso encerrar o processo do servidor do adb e reiniciá-lo para solucionar um problema (por exemplo, se o adb não responder a um comando).

Para interromper o servidor do adb, use o comando adb kill-server. Em seguida, é possível emitir qualquer outro comando do adb para reiniciar o servidor.

Referência de comandos do adb

É possível emitir comandos do adb a partir de uma linha de comando no seu computador de desenvolvimento ou a partir de um script. O uso é o seguinte:

    adb [-d | -e | -s serial_number] command
    

Se houver apenas um emulador em execução ou um dispositivo conectado, o comando do adb será enviado para esse dispositivo por padrão. Se houver vários emuladores em execução e/ou vários dispositivos anexados, será necessário usar a opção -d, -e ou -s para especificar o dispositivo de destino ao qual o comando será direcionado.

A tabela a seguir lista todos os comandos do adb permitidos e explica o significado e uso deles.

Tabela 1. Comandos e opções disponíveis do adb

Opções globais Descrição
-a Ouve em todas as interfaces de rede, em vez de apenas no localhost.
-d Direciona um comando do adb ao único dispositivo USB anexado. Retorna um erro caso mais de um dispositivo USB esteja anexado.
-e Direciona um comando do adb ao único emulador em execução. Retorna um erro quando mais de um emulador está em execução.
-s serial_number Direciona um comando do adb para um dispositivo específico, referido por seu número de série atribuído pelo adb (como emulator-5556). Modifica o valor do número de série armazenado na variável de ambiente $ANDROID_SERIAL. Consulte Enviar comandos a um dispositivo específico.
-H server O nome do host do servidor adb. O valor padrão é localhost.
-P port O número da porta do servidor adb. O valor padrão é 5037.
-L socket Ouve no soquete do servidor adb fornecido. O valor padrão é tcp:localhost:5037.
Comandos gerais Descrição
devices [-l] Imprime uma lista de todos os dispositivos. Use a opção -l para incluir as descrições do dispositivo. Para mais informações, leia Consultar dispositivos.
help Imprime uma lista de comandos adb compatíveis e as descrições deles.
version Imprime o número da versão do adb.
run-as package_name Executa comandos em um dispositivo como um app (especificado usando package_name). Isso permite executar comandos no adb como se o app especificado estivesse executando o comando (ou seja, você tem o mesmo acesso ao dispositivo que o app tem), sem exigir acesso root. Isso pode ser necessário ao usar o adb em um dispositivo sem acesso root ou em um emulador com uma imagem da Play Store. O app precisa ser depurável.
Comandos de rede Descrição
connect host[:port] Conecta-se a um dispositivo por meio de TCP/IP. Se você não especificar uma porta, a porta padrão, 5555, será usada.
disconnect [host | host:port] Desconecta-se do dispositivo TCP/IP especificado em execução na porta especificada. Se você não especificar um host ou uma porta, todos os dispositivos serão desconectados de todas as portas TCP/IP. Se você especificar um host, mas não uma porta, a porta padrão, 5555, será usada.
forward --list Lista todas as conexões de soquete encaminhadas.
forward [--no-rebind] local remote Encaminha conexões de soquete da porta local especificada para a porta remota especificada no dispositivo. Você pode especificar as portas local e remota das seguintes maneiras:
  • tcp:port. Para escolher qualquer porta aberta, defina o valor local tcp:0.
  • localabstract:unix_domain_socket_name.
  • localreserved:unix_domain_socket_name.
  • localfilesystem:unix_domain_socket_name.
  • dev:character_device_name.
  • jdwp:pid.
forward --remove local Remove a conexão de soquete encaminhada especificada.
reverse --list Lista todas as conexões de soquete reversas do dispositivo.
reverse [--no-rebind] remote local Inverte uma conexão de soquete. A opção --no-rebind significa que a reversão falhará se o soquete especificado já estiver vinculado por meio de um comando reverse anterior. Você pode especificar a porta para argumentos locais e remotos das seguintes maneiras:
  • tcp:port. Para escolher qualquer porta aberta, defina o valor remoto tcp:0.
  • localabstract:unix_domain_socket_name.
  • localreserved:unix_domain_socket_name.
  • localfilesystem:unix_domain_socket_name.
reverse --remove remote Remove a conexão de soquete reversa especificada do dispositivo.
reverse --remove-all Remove todas as conexões de soquete reverso do dispositivo.
Comandos de transferência de arquivos Descrição
push local remote Copia arquivos e diretórios do dispositivo local (computador) para um local remoto no dispositivo.
pull [-a] remote local Copia arquivos e diretórios remotos para um dispositivo. Use a opção -a para preservar o modo e o registro de data e hora do arquivo.
sync  [system|vendor|oem|data|all] Sincroniza uma compilação do local especificado em $ANDROID_PRODUCT_OUT para o dispositivo. Todos os arquivos alterados são copiados da partição especificada. O padrão é sincronizar todas as partições. Esse comando só é usado quando você cria a origem da plataforma Android. Os desenvolvedores de apps não precisam usar esse comando.

A variável de ambiente $ANDROID_PRODUCT_OUT é definida automaticamente pelo sistema de compilação do Android para conter a localização das imagens do sistema. Normalmente, você não precisará definir $ANDROID_PRODUCT_OUT ao fazer adb sync, mas pode ser útil se você não estiver em uma árvore de compilação (mas tiver uma) ou estiver sincronizando entre árvores de compilação sem alternar entre elas.


    $ANDROID_PRODUCT_OUT=/out/target/product/generic
    adb sync
    
Comandos de instalação do app Descrição
install [options] package Envia os pacotes para o dispositivo por push e os instala. As opções possíveis são as seguintes:
  • --abi abi-identifier: força a instalação de um app para uma ABI específica.
  • -l: app de bloqueio de encaminhamento.
  • -r: substitui o app existente.
  • -t: permite pacotes de teste. Se o APK for criado usando um SDK de visualização do desenvolvedor (caso o targetSdkVersion seja uma letra em vez de um número), você precisará incluir a opção -t com o comando de instalação se estiver instalando um APK de teste. Para mais informações, consulte a opção -t.
  • -s: instala o app no cartão SD.
  • -d: permite fazer downgrade do código da versão (somente pacotes de depuração).
  • -g: concede todas as permissões de ambiente de execução.
install-multiple [options] packages

As mesmas opções de install com a adição do seguinte:

-p: instalação parcial do app.

uninstall [-k] package Remove esse pacote de app do dispositivo. Adicione a opção -k para manter os diretórios de dados e cache.
Comandos de backup e restauração Descrição
backup [-f file] [-apk | -noapk] [-obb | -noobb] [-shared | -noshared] [-all] [-system | [-nosystem] package_names Grava um arquivo dos dados do dispositivo em file. Se você não especificar um nome de arquivo, o padrão será backup.adb. A lista de package é opcional quando você especifica as opções -all e -shared. Veja a seguir a descrição do uso das outras opções:
  • -apk | -noapk: faz ou não faz backup de arquivos .apk. O valor padrão é -noapk.
  • -obb | -noobb: faz ou não faz backup de arquivos .obb. O valor padrão é -noobb.
  • -shared | -noshared: faz ou não faz backup do armazenamento compartilhado. O valor padrão é -noshared.
  • -all: faz backup de todos os apps instalados.
  • -system | -nosystem: inclui ou não inclui apps do sistema ao fazer backup de todos os apps instalados (-all). O valor padrão é -system.
restore file Restaura o conteúdo do dispositivo a partir de file.
Comandos de depuração Descrição
bugreport path Imprime um bugreport para o caminho especificado. Se path for um diretório, o relatório do bug será salvo nele usando o nome do arquivo padrão, bugreport.zip. Dispositivos não compatíveis com relatórios de bugs compactados são impressos em stdout.
jdwp Imprime uma lista dos processos JDWP disponíveis em um determinado dispositivo. Use forward jdwp:pid para se conectar a um processo específico do JDWP. Por exemplo:
adb forward tcp:8000 jdwp:472
jdb -attach localhost:8000
logcat [-help] [option] [filter-spec] Imprime dados de registro na tela. Para mais informações sobre o comando logcat e a variável de ambiente $ANDROID_LOG_TAGS, consulte Como filtrar a saída do registro na página do Logcat.

A variável de ambiente $ADB_TRACE contém uma lista separada por vírgulas das informações de depuração a serem registradas. Os valores podem ser qualquer combinação dos seguintes: all, adb, sockets, packets, rwx, usb, sync, sysdeps, transport e jdwp.

Consulte também Ferramenta de linha de comando Logcat.

Comandos de segurança Descrição
disable-verity Desative verificação de dm-verity nas compilações de userdebug. A opção dm-verity garante que, quando um usuário inicializar um dispositivo, ele esteja no mesmo estado em que estava quando foi usado pela última vez. Para mais informações, consulte Inicialização verificada.
enable-verity Ative novamente a verificação dm-verity nas compilações de userdebug. A opção dm-verity garante que, quando um usuário inicializar um dispositivo, ele esteja no mesmo estado em que estava quando foi usado pela última vez. Para mais informações, consulte Inicialização verificada.
keygen file Gerar chaves criptografadas RSA públicas e privadas do adb. A chave privada é armazenada em file. A chave pública é armazenada no em file.pub. Você precisa de um par de Chaves RSA ao usar o adb para se conectar via USB pela primeira vez. É necessário aceitar a Chave RSA do computador host para conceder explicitamente ao adb acesso ao dispositivo.

Use a variável de ambiente $ANDROID_VENDOR_KEYS para apontar para um arquivo ou diretório que contenha pares de chaves de autenticação RSA de 2048 bits que você gerou com o comando keygen. Esses pares de chaves são adicionais aos pares de chaves RSA gerados pelo servidor adb.

Quando o servidor adb precisar de uma chave, ele primeiro pesquisará no diretório de armazenamento de chaves do servidor adb. Se nenhuma chave for encontrada, ele verificará a variável de ambiente $ANDROID_VENDOR_KEYS para um local. Se ainda assim nenhuma chave for encontrada, o servidor local do adb gerará e salvará um novo par de chaves no diretório de armazenamento de chaves do servidor adb. Por esse motivo, somente um OEM criando um novo dispositivo Android precisará executar o 'adb keygen'.

Por padrão, os pares de chaves gerados pelo servidor adb ficam nos seguintes diretórios de armazenamento de chaves como adbkey (chave privada) e adbkey.pub (chave pública):

  • Linux e Mac: $HOME/.android.
  • Windows: %USERPOFILE%\.android.
Comandos de script Descrição
wait-for [-transport] -state Aguarda o dispositivo chegar ao estado especificado.
  • state: os valores podem ser device, recovery, sideload ou bootloader.
  • transport: os valores podem ser usb, local ou any.
get-state Imprime o estado adb de um dispositivo. O estado adb pode ser print offline, bootloader ou device. Para mais informações, leia Consultar dispositivos.
get-serialno Imprime a string do número de série do dispositivo adb. Para mais informações, leia Consultar dispositivos.
get-devpath Imprime o caminho do dispositivo adb.
remount Remonta as partições /system, /vendor e /oem no modo de leitura/gravação.
reboot [bootloader | recovery | sideload | sideload-auto-reboot ] Reinicializa o dispositivo. Este comando assume como padrão a inicialização da imagem do sistema, mas também é compatível com bootloader e recovery.
  • A opção bootloader reinicializa no carregador de inicialização.
  • A opção recovery reinicializa na recuperação.
  • A opção sideload reinicializa na recuperação e inicia o modo sideload.
  • A opção sideload-auto-reboot é o mesmo que sideload, mas reinicializa depois que o carregamento lateral termina.
sideload otapackage Faz o carregamento lateral (instalação no formato APK) do pacote OTA completo especificado no dispositivo.
root Reinicia o adbd com permissões de root.
unroot Reinicia o adbd sem permissões de root.
usb Reinicia o servidor adb ouvindo em USB.
tcpip port-number Reinicia o servidor adb ouvindo no TCP na porta especificada.
Comandos de depuração interna Descrição
start-server Verifica se o processo do servidor adb está em execução.
kill-server Encerra o processo do servidor adb.
reconnect Força uma reconexão do host.
reconnect device Força uma reconexão a partir do dispositivo para forçar uma reconexão.
Comandos do shell Descrição
shell Inicia um shell remoto interativo no dispositivo de destino. Para mais informações, consulte Emitir comandos do shell.
shell -e escape_char [-n] [-T] [-t] [-x] [command] Emite um comando do shell no dispositivo de destino e sai do shell remoto. Use qualquer combinação das seguintes opções:
  • -e: especifica um caractere de escape ou o valor none se você não quiser usar esse caractere. Se você não fornecer um valor, será usado o caractere de escape padrão (um traço (-)).
  • -n não ler de stdin.
  • -T: desativa a alocação da utilidade pseudo-terminal (PTY, na sigla em inglês).
  • -t: força a alocação da PTY.
  • -x: desativa os códigos de saída remota e a separação de stdout/stderr.

Para mais informações, consulte Emitir comandos do shell.

emu command Executa um comando do console do emulador. Para mais informações, consulte Controlar o emulador pela linha de comando

Emitir comandos do shell

O comando shell é útil para emitir comandos de dispositivo pelo adb, entrando ou não no shell remoto do adb no dispositivo. Para emitir um só comando sem entrar em um shell remoto, use o comando shell da seguinte maneira:

    adb [-d |-e | -s serial_number] shell shell_command
    

Ou insira um shell remoto em um dispositivo, desta maneira:

    adb [-d | -e | -s serial_number] shell
    

Quando estiver tudo pronto para sair do shell remoto, pressione as teclas Ctrl + D ou digite exit.

Os binários de comando do shell são armazenados no sistema de arquivos do dispositivo em /system/bin/.

Observação: com as Android Platform-Tools 23 ou versões posteriores, o adb processa argumentos da mesma forma que o comando ssh(1). Essa alteração corrigiu muitos problemas com a injeção de comando (link em inglês) e tornou possível executar com segurança comandos que contêm metacaracteres de shell (link em inglês), como adb install Let\'sGo.apk. No entanto, essa alteração significa que a interpretação de qualquer comando que contenha metacaracteres de shell também foi alterada. Por exemplo, o comando adb shell setprop foo 'a b' agora é um erro porque as aspas simples (') são omitidas pelo shell local, e o dispositivo vê adb shell setprop foo a b. Para que o comando funcione, coloque duas aspas, uma para o shell local e outra para o shell remoto, o mesmo que é feito para ssh(1). Por exemplo, adb shell setprop foo "'a b'".

Chame o gerenciador de atividades (am)

Em um shell do adb, é possível emitir comandos com a ferramenta de gerenciador de atividades (am) para executar diversas ações do sistema, como iniciar uma atividade, forçar a parada de um processo, transmitir um intent, modificar as propriedades da tela do dispositivo e muito mais. Em um shell, a sintaxe é a seguinte:

    am command
    

Também é possível emitir um comando do gerenciador de atividades diretamente do adb sem entrar em um shell remoto. Por exemplo:

    adb shell am start -a android.intent.action.VIEW
    

Tabela 2. Comandos disponíveis do gerenciador de atividades

Comando Descrição
start [options] intent Inicia uma Activity especificada pelo intent.

Consulte Especificação para argumentos de intent.

As opções são as seguintes:

  • -D: ative a depuração.
  • -W: aguarde a inicialização ser concluída.
  • --start-profiler file: inicie o criador de perfil e envie os resultados para o file.
  • -P file: semelhante a --start-profiler, mas a criação de perfil é interrompida quando o app fica inativo.
  • -R count: repita os tempos de count inicialização da atividade. Antes de cada repetição, a primeira atividade será concluída.
  • -S: force a parada do app de destino antes de iniciar a atividade.
  • --opengl-trace: ative o rastreamento de funções OpenGL.
  • --user user_id | current: especifique como qual usuário executar. Se não for especificado, execute como o usuário atual.
startservice [options] intent Inicia o Service especificado pelo intent.

Consulte Especificação para argumentos de intent.

As opções são as seguintes:

  • --user user_id | current: especifique como qual usuário executar. Se não for especificado, execute como o usuário atual.
force-stop package Força a parada de todos os elementos associados a package (o nome do pacote do app).
kill [options] package Encerra todos os processos associados a package (o nome do pacote do app). Esse comando encerra apenas processos que podem ser encerrados com segurança e que não afetarão a experiência do usuário.

As opções são as seguintes:

  • --user user_id | all | current: especifica o usuário cujos processos precisam ser eliminados; todos os usuários, caso não seja especificado.
kill-all Encerra todos os processos em segundo plano.
broadcast [options] intent Emite um intent de transmissão.

Consulte Especificação para argumentos de intent.

As opções são as seguintes:

  • [--user user_id | all | current]: especifica a qual usuário enviar; caso não seja especificado, envia para todos os usuários.
instrument [options] component Começa a monitorar com uma instância de Instrumentation. Geralmente, o component de destino segue o formato test_package/runner_class.

As opções são as seguintes:

  • -r: imprime resultados brutos (caso contrário, decodifica report_key_streamresult). Use com [-e perf true] para gerar uma saída bruta para as medições de desempenho.
  • -e name value: define o name do argumento como value. Para testes, um formato comum é -e testrunner_flag value[,value...].
  • -p file: grava dados de criação de perfil em file.
  • -w: aguarda a conclusão da instrumentação antes de retornar. Obrigatório para testes.
  • --no-window-animation: desativa as animações de janela durante a execução.
  • --user user_id | current: especifica qual instrumentação do usuário será executada; usuário atual, caso não seja especificado.
profile start process file Inicia o criador de perfis em process, grava os resultados em file.
profile stop process Interrompe o criador de perfis no process.
dumpheap [options] process file Despeja o heap de process, grava em file.

As opções são as seguintes:

  • --user [user_id | current]: ao fornecer um nome de processo, especifique o usuário do processo a ser despejado; caso não seja especificado, o usuário atual é usado.
  • -n: despeja o heap nativo em vez do gerenciado.
set-debug-app [options] package Define o package do app para depurar.

As opções são as seguintes:

  • -w: aguarda o depurador quando o app é iniciado.
  • --persistent: retém esse valor.
clear-debug-app Limpa o conjunto anterior do pacote para depuração com set-debug-app.
monitor [options] Começa a monitorar falhas ou ANRs.

As opções são as seguintes:

  • --gdb: inicia gdbserv na porta em questão na falha/ANR.
screen-compat {on | off} package Controla o modo de compatibilidade de tela do package.
display-size [reset | widthxheight] Modifica o tamanho de exibição do dispositivo. Esse comando é útil para testar seu app em diferentes tamanhos de tela, porque ele imita a resolução de telas pequenas usando um dispositivo com uma tela grande, e vice-versa.

Exemplo:
am display-size 1280x800

display-density dpi Modifica a densidade de exibição do dispositivo. Esse comando é útil para testar seu app em diferentes densidades de tela, porque ele imita telas de alta densidade usando uma tela de baixa densidade, e vice-versa.

Exemplo:
am display-density 480

to-uri intent Imprime a especificação de intent fornecida como um URI.

Consulte Especificação para argumentos de intent.

to-intent-uri intent Imprime a especificação de intent fornecida como um URI de intent:.

Consulte Especificação para argumentos de intent.

Especificação para argumentos de intent

Para comandos do gerenciador de atividades que incluem um argumento de intent, você pode especificar o intent com as seguintes opções:

Chamar o gerenciador de pacotes (pm)

Em um shell do adb, você pode emitir comandos com a ferramenta gerenciador de pacotes (pm) para executar ações e consultas em pacotes de apps instalados no dispositivo. Em um shell, a sintaxe é a seguinte:

    pm command
    

Você também pode emitir um comando do gerenciador de pacotes diretamente do adb sem entrar em um shell remoto. Por exemplo:

    adb shell pm uninstall com.example.MyApp
    

Tabela 3. Comandos disponíveis do gerenciador de pacotes.

Comando Descrição
list packages [options] filter Exibe todos os pacotes ou, opcionalmente, apenas os pacotes cujos nomes estiverem incluídos no texto de filter.

Opções:

  • -f: ver o arquivo associado.
  • -d: filtrar para mostrar apenas pacotes desativados.
  • -e: filtrar para mostrar apenas pacotes ativados.
  • -s: filtrar para mostrar apenas pacotes do sistema.
  • -3: filtrar para mostrar apenas pacotes de terceiros.
  • -i: ver o instalador dos pacotes.
  • -u: incluir também pacotes desinstalados.
  • --user user_id: o espaço do usuário a ser consultado.
list permission-groups Imprime todos os grupos de permissões conhecidos.
list permissions [options] group Imprime todas as permissões conhecidas ou, opcionalmente, apenas as que estiverem em group.

Opções:

  • -g: organizar por grupo.
  • -f: imprimir todas as informações.
  • -s: breve resumo.
  • -d: listar apenas permissões perigosas.
  • -u: listar apenas as permissões que o usuário verá.
list instrumentation [options] Lista todos os pacotes de teste.

Opções:

  • -f: listar o arquivo APK para o pacote de teste.
  • target_package: listar pacotes de teste apenas para este app.
list features Imprime todos os recursos do sistema.
list libraries Imprime todas as bibliotecas compatíveis com o dispositivo atual.
list users Imprime todos os usuários no sistema.
path package Imprime o caminho para o APK do package em questão.
install [options] path Instala um pacote (especificado por (path) no sistema.

Opções:

  • -l: instalar o pacote com um bloqueio de encaminhamento.
  • -r: reinstalar um app existente, mantendo os dados dele.
  • -t: permitir que APKs de teste sejam instalados. O Gradle gera um APK de teste quando você só executa ou depura seu app ou usa o comando do Android Studio Build > Build APK. Se o APK for criado com um SDK de visualização do desenvolvedor (se targetSdkVersion for uma letra em vez de um número), você precisará incluir a opção -t com o comando install se estiver instalando um APK de teste.
  • -i installer_package_name: especificar o nome do pacote do instalador.
  • -s: instalar o pacote no armazenamento em massa compartilhado (como sdcard).
  • -f: instalar o pacote na memória interna do sistema.
  • -d: permitir o downgrade do código da versão.
  • -g: conceder todas as permissões listadas no manifesto do app.
uninstall [options] package Remove um pacote do sistema.

Opções:

  • -k: manter os dados e os diretórios de cache após a remoção do pacote.
clear package Exclui todos os dados associados a um pacote.
enable package_or_component Ativa o pacote ou componente fornecido (gravado como "pacote/classe").
disable package_or_component Desativa o pacote ou componente fornecido (gravado como "pacote/classe").
disable-user [options] package_or_component

Opções:

  • --user user_id: o usuário a ser desativado.
grant package_name permission Concede uma permissão a um app. Em dispositivos que executam o Android 6.0 (API de nível 23) e versões posteriores, a permissão pode ser qualquer permissão declarada no manifesto do app. Em dispositivos que executam o Android 5.1 (API de nível 22) e versões anteriores, ela precisa ser uma permissão opcional definida pelo app.
revoke package_name permission Revoga uma permissão de um app. Em dispositivos que executam o Android 6.0 (API de nível 23) e versões posteriores, a permissão pode ser qualquer permissão declarada no manifesto do app. Em dispositivos que executam o Android 5.1 (API de nível 22) e versões anteriores, ela precisa ser uma permissão opcional definida pelo app.
set-install-location location Altera o local de instalação padrão. Valores de local:
  • 0: Automático: permite que o sistema defina o melhor local.
  • 1: Interno: instala no armazenamento interno do dispositivo.
  • 2: Externo: instala em uma mídia externa.

Observação: essa opção é destinada apenas à depuração. O uso dela pode causar a falha de apps e outros comportamentos indesejáveis.

get-install-location Retorna o local de instalação atual. Valores de retorno:
  • 0 [auto]: permite que o sistema defina o melhor local
  • 1 [internal]: instala no armazenamento interno do dispositivo
  • 2 [external]: instala em uma mídia externa
set-permission-enforced permission [true | false] Especifica se a permissão deve ser aplicada.
trim-caches desired_free_space Reduz arquivos em cache para alcançar o espaço livre fornecido.
create-user user_name Cria um novo usuário com o user_name fornecido, imprimindo o identificador de novo usuário do usuário.
remove-user user_id Remove o usuário com o user_id fornecido, excluindo todos os dados associados a esse usuário.
get-max-users Imprime o número máximo de usuários permitido pelo dispositivo.

Chamar o gerenciador de políticas de dispositivos (dpm)

Para ajudar você a desenvolver e testar seus apps de gerenciamento de dispositivos (ou outros apps empresariais), você pode emitir comandos para a ferramenta do gerenciador de políticas de dispositivo (dpm). Use a ferramenta para controlar o app de administração ativo ou alterar os dados de status de uma política no dispositivo. Em um shell, a sintaxe é a seguinte:

    dpm command
    

Você também pode emitir um comando do gerenciador de políticas de dispositivo diretamente do adb sem inserir um shell remoto:

    adb shell dpm command
    

Tabela 4. Comandos disponíveis do gerenciador de políticas de dispositivos

Comando Descrição
set-active-admin [options] component Define o component como administrador ativo.

As opções são as seguintes:

  • --user user_id: especifica o usuário de destino. Você também pode passar --user current para selecionar o usuário atual.
set-profile-owner [options] component Define component como administrador ativo, e o pacote dele como proprietário do perfil de um usuário existente.

As opções são as seguintes:

  • --user user_id: especifica o usuário de destino. Você também pode passar --user current para selecionar o usuário atual.
  • --name name: especifica o nome legível da organização.
set-device-owner [options] component Define component como administrador ativo, e o pacote dele como proprietário do dispositivo.

As opções são as seguintes:

  • --user user_id: especifica o usuário de destino. Você também pode passar --user current para selecionar o usuário atual.
  • --name name: especifica o nome legível da organização.
remove-active-admin [options] component Desativa um administrador ativo. O app precisa declarar android:testOnly no manifesto. Esse comando também remove os proprietários de perfil e dispositivo.

As opções são as seguintes:

  • --user user_id: especifica o usuário de destino. Você também pode passar --user current para selecionar o usuário atual.
clear-freeze-period-record Limpa o registro do dispositivo de períodos de congelamento definidos anteriormente para atualizações do sistema OTA. Isso é útil para evitar as restrições de agendamento do dispositivo ao desenvolver apps que gerenciam períodos de congelamento. Consulte Gerenciar atualizações do sistema.

Compatível com dispositivos que executam o Android 9.0 (API de nível 28) ou versões posteriores.

force-network-logs Força o sistema a deixar qualquer registro de rede existente pronto para recuperação por um DPC. Se houver conexão ou registros DNS disponíveis, o DPC receberá o callback onNetworkLogsAvailable(). Consulte Registro de atividades de rede.

Este comando tem limitação de taxa. Compatível com dispositivos que executam o Android 9.0 (API de nível 28) ou versões posteriores.

force-security-logs Força o sistema a disponibilizar quaisquer registros de segurança existentes para o DPC. Se houver registros disponíveis, o DPC receberá o callback onSecurityLogsAvailable(). Consulte Registrar atividade empresarial do dispositivo.

Este comando tem limitação de taxa. Compatível com dispositivos que executam o Android 9.0 (API de nível 28) ou versões posteriores.

Fazer uma captura de tela

O comando screencap é um utilitário do shell para registrar uma captura de tela de um dispositivo. Em um shell, a sintaxe é a seguinte:

    screencap filename
    

Para usar o screencap na linha de comando, digite o seguinte:

    adb shell screencap /sdcard/screen.png
    

Este é um exemplo de uma sessão de captura de tela usando o shell do adb para fazer a captura e o comando pull para fazer o download do arquivo do dispositivo:

    $ adb shell
    shell@ $ screencap /sdcard/screen.png
    shell@ $ exit
    $ adb pull /sdcard/screen.png
    

Gravar um vídeo

O comando screenrecord é um utilitário do shell para gravar a tela de dispositivos com o Android 4.4 (API de nível 19) e versões posteriores. O utilitário grava as atividades na tela em um arquivo MPEG-4. Você pode usar esse arquivo para criar vídeos promocionais ou de treinamento ou para depuração e teste.

Em um shell, use a seguinte sintaxe:

    screenrecord [options] filename
    

Para usar screenrecord na linha de comando, digite o seguinte:

    adb shell screenrecord /sdcard/demo.mp4
    

Para interromper a gravação da tela, pressione Control + C (Command + C no Mac). Caso contrário, a gravação será interrompida automaticamente em três minutos ou no limite de tempo definido por --time-limit.

Para começar a gravar a tela do seu dispositivo, execute o comando screenrecord para gravar o vídeo. Em seguida, execute o comando pull para fazer o download do vídeo do dispositivo para o computador host. Veja um exemplo de sessão de gravação:

    $ adb shell
    shell@ $ screenrecord --verbose /sdcard/demo.mp4
    (press Control + C to stop)
    shell@ $ exit
    $ adb pull /sdcard/demo.mp4
    

O utilitário screenrecord pode gravar em qualquer resolução e taxa de bits compatível que você solicitar, mantendo a proporção da tela do dispositivo. O utilitário grava na resolução e orientação nativa da tela por padrão, com uma duração máxima de três minutos.

Limitações do utilitário screenrecord:

  • O áudio não é gravado nesse arquivo de vídeo.
  • A gravação de vídeo não está disponível para dispositivos que executam Wear OS.
  • Alguns dispositivos podem não conseguir gravar na resolução nativa das respectivas telas. Se tiver problemas ao gravar a tela, tente usar uma resolução menor.
  • Não é possível girar a tela durante a gravação. Se isso acontecer, parte da tela será cortada na gravação.

Tabela 4. Opções do screenrecord

Opções Descrição
--help Exibe a sintaxe e as opções do comando
--size widthxheight Define o tamanho do vídeo: 1280x720. O valor padrão é a resolução nativa da tela do dispositivo, se for compatível, ou 1.280 x 720, se não for. Para conseguir os melhores resultados, use um tamanho compatível com o codificador de Advanced Video Coding (AVC) do seu dispositivo.
--bit-rate rate Define a taxa de bits do vídeo, em megabits por segundo. O valor padrão é 4 Mbps. É possível aumentar a taxa de bits para melhorar a qualidade do vídeo, mas isso resultará em arquivos de filme mais pesados. O exemplo a seguir define a taxa de bits da gravação para 6 Mbps:

screenrecord --bit-rate 6000000 /sdcard/demo.mp4
--time-limit time Define o tempo máximo de gravação em segundos. O valor padrão e máximo é 180 (3 minutos).
--rotate Gira a saída em 90°. Esse recurso é experimental.
--verbose Exibe informações de registro na tela da linha de comando. Se você não definir essa opção, o utilitário não exibirá informações durante a execução.

Ler perfis do ART para apps

A partir do Android 7.0 (API de nível 24), o Android Runtime (ART) coleta perfis de execução dos apps instalados, que são usados para otimizar o desempenho do app. É recomendável verificar os perfis coletados para entender quais métodos são executados com mais frequência e quais classes são usadas durante a inicialização do app.

Para produzir as informações de perfil em forma de texto, use o seguinte comando:

    adb shell cmd package dump-profiles package
    

Para recuperar o arquivo produzido, use este comando:

    adb pull /data/misc/profman/package.txt
    

Outros comandos do shell

Para ter uma lista de todos os programas de shell disponíveis, use o seguinte comando:

adb shell ls /system/bin

Há ajuda disponível para a maioria dos comandos.

A tabela abaixo lista alguns dos comandos do shell do adb mais comuns.

Tabela 6. Alguns outros comandos do shell do adb

Comando do shell Descrição
dumpsys Despeja os dados do sistema na tela. Para saber mais sobre essa ferramenta de linha de comando, leia dumpsys
dumpstate Despeja o estado em um arquivo.
logcat [option]...  [filter-spec]... Ativa o registro do sistema e do app e imprime a saída na tela.

Consulte também Ferramenta de linha de comando Logcat.

dmesg Exibe as mensagens de depuração do kernel na tela.
start Inicia (reinicia) um dispositivo.
stop Para a execução de um dispositivo.
sqlite3 Inicia o programa da linha de comando sqlite3.

A ferramenta sqlite3 inclui comandos como .dump para imprimir o conteúdo de uma tabela e .schema para imprimir a instrução SQL CREATE para uma tabela existente. Você também pode executar comandos SQLite imediatamente.

Os bancos de dados SQLite3 são armazenados na pasta /data/data/package_name/databases/.

Por exemplo:


    $ adb -s emulator-5554 shell
    $ sqlite3 /data/data/com.example.app/databases/rssitems.db
    SQLite version 3.3.12
    Enter ".help" for instructions
    

Para mais informações, consulte a documentação da linha de comando sqlite3 (link em inglês).