Suporte a tamanhos de página de 16 KB

Requisito de compatibilidade com o Google Play de 16 KB
A partir de 1º de novembro de 2025, todos os novos apps e atualizações de apps enviados ao Google Play e direcionados a dispositivos Android 15 ou mais recentes precisarão oferecer suporte a tamanhos de página de 16 KB em dispositivos de 64 bits.
Leia mais →

Historically, Android has only supported 4 KB memory page sizes, which has optimized system memory performance for the average amount of total memory that Android devices have typically had. Beginning with Android 15, AOSP supports devices that are configured to use a page size of 16 KB (16 KB devices). If your app uses any NDK libraries, either directly or indirectly through an SDK, then you will need to rebuild your app for it to work on these 16 KB devices.

As device manufacturers continue to build devices with larger amounts of physical memory (RAM), many of these devices will adopt 16 KB (and eventually greater) page sizes to optimize the device's performance. Adding support for 16 KB page size devices enables your app to run on these devices and helps your app benefit from the associated performance improvements. Without recompiling, apps won't work on 16 KB devices in future Android releases.

To help you add support for your app, we've provided guidance on how to check if your app is impacted, how to rebuild your app (if applicable), and how to test your app in a 16 KB environment using emulators (including Android 15 system images for the Android Emulator).

Benefícios e ganhos de performance

Os dispositivos configurados com tamanhos de página de 16 KB usam um pouco mais de memória em média, mas também têm várias melhorias de desempenho para o sistema e os apps:

  • Tempos de inicialização do app mais rápidos enquanto o sistema está sob pressão de memória: 3,16% mais baixos em média, com melhorias mais significativas (até 30%) em alguns apps testados.
  • Redução do consumo de energia durante o lançamento do app: redução média de 4,56%
  • Lançamento mais rápido da câmera: 4,48% mais rápido em média e 6,60% mais rápido em média
  • Tempo de inicialização do sistema melhorado: melhoria de 8% (aproximadamente 950 milissegundos) em média

Essas melhorias são baseadas nos testes iniciais, e os resultados em dispositivos reais provavelmente serão diferentes. Forneceremos análises adicionais de ganhos em potencial para apps à medida que continuarmos nossos testes.

Verificar se o app foi afetado

Se o app usar código nativo, recompile o app com suporte para dispositivos de 16 KB. Se você não tiver certeza se o app usa código nativo, use o APK Analyzer para identificar se há código nativo e verifique o alinhamento dos segmentos ELF de bibliotecas compartilhadas encontradas. O Android Studio também oferece recursos que ajudam a detectar automaticamente problemas de alinhamento.

Se o app usa apenas código escrito na linguagem de programação Java ou Kotlin, incluindo bibliotecas ou SDKs, ele já oferece suporte a dispositivos de 16 KB. No entanto, recomendamos que você teste o app em um ambiente de 16 KB para verificar se não há regressões inesperadas no comportamento do app.

O app usa código nativo?

Seu app usa código nativo se uma das seguintes condições se aplicar:

  • O app usa qualquer código C/C++ (nativo). Se o app usa o Android NDK, ele usa código nativo.
  • O app se vincula a bibliotecas ou dependências nativas de terceiros (como SDKs) que as usam.
  • O app é criado por um criador de apps de terceiros que usa bibliotecas nativas no dispositivo.

Identificar bibliotecas nativas usando o APK Analyzer

O APK Analyzer é uma ferramenta que permite avaliar vários aspectos de um APK. Para verificar se o app usa código nativo (independente de ser compatível com 16 KB):

  1. Abra o Android Studio, clique em File > Open e escolha qualquer projeto.

  2. Na barra de menus, clique em Build > Analyze APK...

    Opção do menu "Build" do Studio para iniciar o APK Analyzer

  3. Escolha o APK que você quer analisar.

  4. Confira se há algum arquivo de objeto compartilhado (.so) na pasta lib. Se houver arquivos de objeto compartilhados, seu app usará código nativo. A coluna Alinhamento mostra mensagens de aviso para arquivos com problemas de alinhamento. Se não houver arquivos de objeto compartilhado ou uma pasta lib, o app não usa código nativo.

    Visualização do APK Analyzer mostrando que os arquivos de objeto compartilhado estão presentes

Detectar problemas de alinhamento com verificações automatizadas

O Android Studio avisa proativamente se as bibliotecas ou APKs pré-criados não estiverem em conformidade com 16 KB. Use a ferramenta APK Analyzer para revisar quais bibliotecas precisam ser atualizadas ou se alguma mudança de código é necessária.

Notificações de aviso do Studio sobre problemas de alinhamento em um projeto

O lint no Android Studio também destaca bibliotecas nativas que não estão alinhadas a 16 KB.

Aviso do linter do Studio sobre uma biblioteca nativa não alinhada

Verificar o alinhamento de segmentos ELF para bibliotecas compartilhadas

Para todas as bibliotecas compartilhadas, verifique se os segmentos ELF estão alinhados corretamente usando o alinhamento ELF de 16 KB. Se você estiver desenvolvendo no Linux ou no macOS, use o script check_elf_alignment.sh conforme descrito na seção a seguir. Também é possível usar as ferramentas de linha de comando diretamente.

Use o script check_elf_alignment.sh (Linux ou macOS)

Siga estas etapas para verificar o alinhamento dos segmentos ELF usando o script check_elf_alignment.sh:

  1. Salve o script check_elf_alignment.sh em um arquivo.

  2. Execute o script no arquivo APK do app:

    check_elf_alignment.sh APK_NAME.apk

    O script gera ALIGNED ou UNALIGNED para todas as bibliotecas compartilhadas arm64-v8a.

  3. Se alguma biblioteca compartilhada arm64-v8a ou x86_64 for UNALIGNED, será necessário atualizar o pacote dessas bibliotecas, recompilar o app e fazer um novo teste seguindo as etapas desta seção.

Usar ferramentas de linha de comando diretamente

Siga estas etapas para verificar o alinhamento dos segmentos ELF usando ferramentas de linha de comando diretamente:

  1. Verifique se o Android SDK Build-Tools versão 35.0.0 ou mais recente e o Android NDK estão instalados usando o SDK Manager no Android Studio ou a ferramenta de linha de comando sdkmanager.

  2. Extraia o arquivo APK do app:

    Linux ou macOS

    unzip APK_NAME.apk -d /tmp/my_apk_out

    Windows (PowerShell)

    Expand-Archive -Path .\APK_NAME.apk -DestinationPath ~\tmp\my_apk_out

  3. No diretório temporário em que você extraiu o arquivo APK, verifique o conteúdo do diretório lib para arquivos de objeto compartilhado (.so). Esses são os mesmos arquivos de objeto compartilhado que você teria visto ao identificar bibliotecas nativas usando o APK Analyzer. Execute o seguinte comando em cada arquivo de objeto compartilhado:

    Linux ou macOS

    SDK_ROOT_LOCATION/Android/sdk/ndk/NDK_VERSION/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-objdump -p SHARED_OBJECT_FILE.so | grep LOAD

    Windows (PowerShell)

    SDK_ROOT_LOCATION\Android\sdk\ndk\NDK_VERSION\toolchains\llvm\prebuilt\windows-x86_64\bin\llvm-objdump.exe -p SHARED_OBJECT_FILE.so | Select-String -Pattern "LOAD"

    Em que SDK_ROOT_LOCATION é o caminho para o diretório em que você instalou o SDK do Android, SHARED_OBJECT_FILE é o nome do arquivo de objeto compartilhado que você está verificando e NDK_VERSION é a versão do NDK do Android instalada (por exemplo, 28.0.12433566). A saída será semelhante a esta para cada arquivo verificado:

    LOAD off    0x0000000000000000 vaddr 0x0000000000000000 paddr 0x0000000000000000 align 2**14
LOAD off    0x0000000000042a90 vaddr 0x0000000000043a90 paddr 0x0000000000043a90 align 2**14
LOAD off    0x0000000000046230 vaddr 0x0000000000048230 paddr 0x0000000000048230 align 2**14

  4. Verifique as linhas de saída para garantir que os segmentos de carga não tenham valores menores que 2**14. Se algum segmento de carga tiver valores 2**13, 2**12 ou menores, atualize o pacote dessas bibliotecas, recompile o app e faça um novo teste seguindo as etapas desta seção.

  5. Em seguida, execute a ferramenta de linha de comando zipalign no arquivo APK do app:

    Linux ou macOS

    SDK_ROOT_LOCATION/Android/sdk/build-tools/35.0.0/zipalign -v -c -P 16 4 APK_NAME.apk

    Windows (PowerShell)

    SDK_ROOT_LOCATION\Android\sdk\build-tools\35.0.0\zipalign.exe -v -c -P 16 4 APK_NAME.apk

    Em que SDK_ROOT_LOCATION é o caminho para o diretório em que você instalou o SDK do Android e APK_NAME é o nome do arquivo APK do seu app. A última linha da saída vai dizer "Verification successful" se todas as bibliotecas compartilhadas estiverem alinhadas corretamente.

    Se a verificação falhar, algumas bibliotecas compartilhadas precisarão ser realinhadas. Portanto, atualize o pacote dessas bibliotecas, recompile o app e faça um novo teste seguindo as etapas desta seção.

Criar o app com suporte a dispositivos de 16 KB

Se o app usar código nativo, siga as etapas descritas nas seções a seguir para garantir que ele seja compatível com dispositivos de 16 KB:

  1. Atualizar o pacote das bibliotecas compartilhadas
  2. Compile seu app usando o alinhamento ELF de 16 KB
  3. Corrigir código e resolver problemas de tempo de execução
  4. Verificar se os SDKs são compatíveis com 16 KB

Atualizar o pacote das bibliotecas compartilhadas

Recomendamos que você faça upgrade para a versão 8.5.1 ou mais recente do AGP e use bibliotecas compartilhadas não compactadas.

AGP versão 8.5.1 ou mais recente

Dispositivos de 16 KB exigem que os apps enviados com bibliotecas compartilhadas não compactadas as alinhem em um limite de 16 KB alinhado por zip. Para isso, atualize para a versão 8.5.1 ou mais recente do Plug-in do Android para Gradle (AGP). Consulte a seção Assistente de upgrade do plug-in do Android para Gradle para saber mais sobre o processo de upgrade.

AGP versão 8.5 ou anterior

Se não for possível fazer upgrade do AGP para a versão 8.5.1 ou mais recente, a alternativa é mudar para usar bibliotecas compartilhadas compactadas. Atualize a configuração do Gradle para que ele compacte as bibliotecas compartilhadas ao empacotar o app e evite problemas de instalação com bibliotecas compartilhadas desalinhadas.

Groovy

No arquivo build.gradle, adicione a seguinte opção:

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging true
      }
  }
}

Kotlin

No arquivo build.gradle.kts, adicione a seguinte opção:

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging = true
      }
  }
}

Compile seu app usando o alinhamento ELF de 16 KB

Para que o app seja executado, os dispositivos de 16 KB exigem que os segmentos ELF das bibliotecas compartilhadas sejam alinhados corretamente usando o alinhamento ELF de 16 KB.

Para desenvolvedores de jogos, se o jogo for executado no mecanismo de jogos Unity, consulte o guia do Unity. Se o jogo for executado no mecanismo de jogo Unreal, consulte o guia do Unreal. Para mecanismos de jogos nativos, continue com este guia.

Para compilar seu app usando o alinhamento ELF de 16 KB, siga as etapas em uma das seções a seguir, dependendo da versão do NDK do Android que você está usando.

Android NDK r28 e versões mais recentes

As versões r28 e mais recentes do NDK compilam 16 KB alinhados por padrão.

Android NDK r27

Para oferecer suporte à compilação de bibliotecas compartilhadas alinhadas a 16 KB com o Android NDK versão r27 e mais recentes, atualize as flags do vinculador ndk-build, build.gradle, build.gradle.kts da seguinte maneira:

ndk-build

No seu Application.mk:

APP_SUPPORT_FLEXIBLE_PAGE_SIZES := true

Groovy

No arquivo build.gradle, defina o argumento -DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON:

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {
      // For ndk-build, instead use the ndkBuild block.
      cmake {
        // Passes optional arguments to CMake.
        arguments "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
      }
    }
  }
}

Kotlin

No arquivo build.gradle.kts, defina o argumento -DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON:

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {
      // For ndk-build, instead use the ndkBuild block.
      cmake {
        // Passes optional arguments to CMake.
        arguments += listOf("-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON")
      }
    }
  }
}

Outros sistemas de build

Especifique as seguintes flags do vinculador:

-Wl,-z,max-page-size=16384

Android NDK r26 e versões anteriores

Para oferecer suporte à compilação de bibliotecas compartilhadas alinhadas a 16 KB com o Android NDK versão r26 ou anterior, atualize a configuração de ndk-build ou cmake da seguinte maneira:

ndk-build

Atualize seu Android.mk para ativar o alinhamento ELF de 16 KB:

LOCAL_LDFLAGS += "-Wl,-z,max-page-size=16384"

CMake

Atualize seu CMakeLists.txt para ativar o alinhamento ELF de 16 KB:

target_link_options(${CMAKE_PROJECT_NAME} PRIVATE "-Wl,-z,max-page-size=16384")

Android NDK r22 e versões anteriores

Além da etapa descrita para o NDK r26 e versões anteriores, você precisa definir common-page-size=16384 se estiver usando o NDK r22 ou versões anteriores. A definição de common-page-size=16384 é obrigatória devido a bugs em versões anteriores dos linkers GNU ld e LLVM lld. No entanto, recomendamos que você atualize suas ferramentas para uma versão mais recente e evite esses bugs.

Para compilar bibliotecas compartilhadas compatíveis com 16 KB com o Android NDK versão r22 ou anterior, atualize a configuração ndk-build ou cmake da seguinte maneira:

ndk-build

Atualize seu Android.mk para criar um ELF compatível com 16 KB:

LOCAL_LDFLAGS += "-Wl,-z,max-page-size=16384"
LOCAL_LDFLAGS += "-Wl,-z,common-page-size=16384"

CMake

Atualize seu CMakeLists.txt para criar um ELF compatível com 16 KB:

target_link_options(${CMAKE_PROJECT_NAME} PRIVATE "-Wl,-z,max-page-size=16384")
target_link_options(${CMAKE_PROJECT_NAME} PRIVATE "-Wl,-z,common-page-size=16384")

Corrigir o código e resolver problemas de ambiente de execução

Mesmo que o app esteja alinhado a 16 KB, ele pode encontrar erros se lugares no código presumirem que um dispositivo está usando um tamanho de página específico. Para evitar isso, siga estas etapas:

  1. Remova todas as dependências codificadas que referenciam a constante PAGE_SIZE ou instâncias na lógica do código que presumem que o tamanho da página de um dispositivo é de 4 KB (4096).

    Use getpagesize() ou sysconf(_SC_PAGESIZE).

  2. Procure usos de mmap() e outras APIs que exigem argumentos alinhados à página e substitua por alternativas quando necessário.

Em alguns casos, se o app usar PAGE_SIZE como um valor conveniente que não está vinculado ao tamanho da página subjacente, isso não vai causar falhas no app quando usado no modo de 16 KB. No entanto, se esse valor for transmitido ao kernel com mmap sem MAP_FIXED, o kernel ainda usará uma página inteira, o que desperdiça alguma memória. Por esses motivos, PAGE_SIZE fica indefinido quando o modo de 16 KB é ativado no NDK r27 e versões mais recentes.

Se o app usa PAGE_SIZE dessa forma e nunca transmite esse valor diretamente para o kernel, em vez de usar PAGE_SIZE, crie uma nova variável com um novo nome para refletir que ela é usada para outras finalidades e não reflete uma página de memória real.

Verificar se os SDKs aceitam 16 KB

Muitos SDKs são compatíveis com tamanhos de página de 16 KB, principalmente se você os criar ou usar pré-compilados recentes. No entanto, como alguns SDKs pré-criados ou versões do SDK não são compatíveis com 16 KB, verifique o site de cada provedor de SDK para determinar qual versão usar com 16 KB.

Testar o app em um ambiente de 16 KB

Depois de criar o app com suporte para dispositivos de 16 KB, teste-o em um ambiente de 16 KB para verificar se ele apresenta regressões. Para isso, siga estas etapas:

  1. Configure o SDK do Android 15.

  2. Configure um dos seguintes ambientes de teste:

  3. Inicie o dispositivo de teste e execute o seguinte comando para verificar se ele está usando um ambiente de 16 KB:

    adb shell getconf PAGE_SIZE

    O comando vai retornar um valor de 16384.

  4. Execute o comando zipalign a seguir para verificar se o app está alinhado a 16 KB, em que APK_NAME é o nome do arquivo APK do app:

    zipalign -c -P 16 -v 4 APK_NAME.apk

  5. Teste o app completamente, concentrando-se em áreas que possam ser afetadas por mudanças em instâncias de código que referenciam tamanhos de página específicos.

Configurar o Android Emulator com uma imagem do sistema Android 15 baseada em 16 KB

Para configurar um ambiente de 16 KB usando o emulador do Android, siga estas etapas:

  1. As imagens do sistema do emulador Android 15 baseadas em 16 KB são compatíveis com o Android Studio Jellyfish | 2023.3.1 ou mais recente. No entanto, para ter a melhor experiência ao trabalhar com dispositivos de 16 KB, use o Android Studio Ladybug | 2024.2.1 ou mais recente.

    Estamos sempre trabalhando em novos recursos. Por isso, considere baixar versões mais recentes ou a versão de pré-lançamento mais recente do Android Studio assim que elas estiverem disponíveis.

    Lembre-se de que você pode manter a versão atual do Android Studio instalada, já que é possível instalar diversas versões lado a lado.

  2. No Android Studio, clique em Tools > SDK Manager.

  3. Na guia SDK Platforms, marque Show Package Details e expanda a seção Android VanillaIceCream ou mais recente. Selecione uma ou ambas as imagens do sistema do emulador a seguir, dependendo dos dispositivos virtuais que você quer criar:

    • Imagem do sistema de 16 KB para APIs experimentais do Google ARM 64 v8a
    • Imagem do sistema Intel x86_64 Atom de tamanho de página de 16 KB experimental das APIs do Google
    Faça o download de imagens do sistema do emulador de 16 KB usando o SDK Manager no Android Studio

  4. Clique em Aplicar > OK para baixar as imagens do sistema selecionadas.

  5. Siga as etapas para configurar um dispositivo virtual para o Android 15 e, quando for solicitado a selecionar uma imagem do sistema, escolha a imagem de 16 KB que você baixou. Se ela não for recomendada automaticamente, você poderá encontrar a imagem do sistema de 16 KB na guia Outras imagens.

    Encontre a imagem do emulador de 16 KB na guia "Outras imagens".

Etapas adicionais para algumas versões do emulador e imagens do sistema

Para versões do Android Emulator de 35.1.5 a 35.1.20 e antes da revisão 4 das imagens do sistema Android 15.0 de 16 KB oferecidas no SDK Manager, para simular um ambiente de 16 KB em sistemas x86_64, também é necessário concluir as etapas a seguir. Essas etapas não são necessárias após a versão 35.1.21 e com a revisão 4 das imagens de sistema de tamanho de página de 16 KB do Android 15.0 ou mais recente.

  1. No Gerenciador de dispositivos, clique nos três pontos ao lado da imagem de 16 KB e em Mostrar no disco.
  2. Nessa pasta, encontre o arquivo config.ini.

  3. Adicione a seguinte linha ao arquivo config.ini e salve as mudanças:

    kernel.parameters = androidboot.page_shift=14

  4. Para verificar as mudanças, execute o comando a seguir, que vai retornar 16384:

    adb shell getconf PAGE_SIZE

Iniciar o emulador

Depois de configurar o emulador do Android e os dispositivos virtuais, inicie o emulador no menu do dispositivo de destino ou na linha de comando.

Ativar o modo de 16 KB em um dispositivo usando as opções do desenvolvedor

Ative a opção de desenvolvedor Inicializar com tamanho de página de 16 KB para inicializar um dispositivo no modo de 16 KB.

A partir do Android 15 QPR1, é possível usar a opção do desenvolvedor disponível em alguns dispositivos para inicializar o aparelho no modo de 16 KB e realizar testes no dispositivo. Antes de usar a opção do desenvolvedor, acesse Configurações > Sistema > Atualizações de software e aplique as atualizações disponíveis.

Essa opção de desenvolvedor está disponível nos seguintes dispositivos:

  • Pixel 8 e 8 Pro (com Android 15 QPR1 ou mais recente)

    Aviso: devido a um problema conhecido com o Android 15 QPR2 Beta 3, a tela sensível ao toque não funciona em dispositivos Pixel 8 depois de instalar o Android 15 QPR2 Beta 3 e iniciar o dispositivo no modo de 16 KB. Esse problema não afeta os dispositivos Pixel 8 Pro.

  • Pixel 8a (com Android 15 QPR1 ou mais recente)

    Aviso: devido a um problema conhecido com o Android 15 QPR2 Beta 3, a tela sensível ao toque não funciona em dispositivos Pixel 8a após a instalação do Android 15 QPR2 Beta 3 e a inicialização do dispositivo no modo de 16 KB.

  • Pixel 9, 9 Pro e 9 Pro XL (com Android 15 QPR2 Beta 2 ou versões mais recentes)

Requisito de compatibilidade do Google Play

À medida que os fabricantes equipam os dispositivos com mais RAM para otimizar o desempenho, muitos vão adotar tamanhos de página maiores, como 16 KB. Para se preparar para o lançamento desses dispositivos, o Google Play está introduzindo um novo requisito de compatibilidade: a partir de 1º de novembro de 2025, todos os novos apps e atualizações de apps enviados ao Google Play e direcionados a dispositivos com Android 15 (nível 35 da API) e versões mais recentes precisarão oferecer suporte a tamanhos de página de 16 KB.

Para saber mais sobre esse requisito de compatibilidade, consulte esta postagem do blog.