diff --git a/docs/guides/install-android.md b/docs/guides/install-android.md index d218668c38..fe1b2dd8c0 100644 --- a/docs/guides/install-android.md +++ b/docs/guides/install-android.md @@ -1,65 +1,154 @@ -# Downloading, Installing and Updating RetroArch for Android devices. +# Downloading, Installing and Updating RetroArch for Android devices -## Non-Google Play sources +## RetroArch APK Package Variants -### Installation via Side-loading -Side-loading means installing manually downloaded APK files on Android (outside official stores).
-You must follow the [installation notes](#installation-notes) for this process. +| Package Name | Supported application binary interface (ABI) | Architectures | +|-------------------------|----------------------------------------------|------------------------------------------------------------| +| `com.retroarch` | `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64` | 64-bit ARM, 32-bit ARM, 32-bit Intel/AMD, 64-bit Intel/AMD | +| `com.retroarch.aarch64` | `arm64-v8a` | 64-bit ARM | +| `com.retroarch.ra32` | `armeabi-v7a` | 32-bit ARM | + +Package names are named with an architecture suffix: `.aarch64` is a 64-bit build, `.ra32` is a 32-bit build, and no suffix is a universal build that opts for 64-bit if your system supports it. 32-bit support on Android is slowly being phased out by the industry, but these builds remain available for older devices or specific use cases. + +`com.retroarch` supports multiple instruction sets beyond ARM, including `x86` (32-bit Intel/AMD processors) and `x86_64` (64-bit Intel/AMD). These are used for Android-x86 projects, PC emulators, select Chromebooks, and some tablets running Android on Intel hardware. There are no standalone `x86` or `x86_64` releases of RetroArch like the 32-bit and 64-bit ARM variants; the universal package (`com.retroarch`) must be installed to access these ABIs. + +### Multi-Package Installation +Android 7.0+ (Nougat) supports multi-package handling, while earlier versions treat distinct package names as conflicting upgrades. However, multi-package handling makes it possible to install the universal package (com.retroarch) alongside the appropriate architecture-specific build (com.retroarch.aarch64 **or** com.retroarch.ra32, depending on device) without forcing an upgrade. + +For example, to install both the stable and nightly versions of RetroArch on a typical 64-bit device, you can install: +- Stable release (`com.retroarch`) + 64-bit nightly (`com.retroarch.aarch64`) +- 64-bit release (`com.retroarch.aarch64`) + stable nightly (`com.retroarch`) + +However, you cannot install: +- Stable + stable nightly (both `com.retroarch`) +- 64-bit + 64-bit nightly (both `com.retroarch.aarch64`) + +## Sources + +### Non-Play Store Sources + +#### Installation via Sideloading +Sideloading Android apps involves installing APK files from sources outside official stores. Apps like Obtainium automate APK downloads for the latest versions, avoiding issues with manual methods such as lengthy repeated downloads/installations and missed updates. + +To sideload successfully: +* The first time you attempt to install an APK via an app (e.g. via any file manager, or Obtainium), enable the [install unknown apps](#install-unknown-apps) permission for it. This step is straightforward, and most Android users can complete it without consulting the detailed instructions. +* If Play Protect warnings appear on Android, follow the installation notes for [allowing APK installations blocked by Google Play Protect](#allowing-apk-installations-blocked-by-google-play-protect). This step is more complex and should be read carefully to ensure success on all Android devices. + +##### From RetroArch.com Downloads + +| Type | Variant | Filename | Version identifier | Package Name | +|---------|-----------------------|------------------------------------|----------------------|-------------------------| +| Stable | Universal | `RetroArch.apk` | [version number]_GIT | `com.retroarch` | +| Stable | Architecture-specific | `RetroArch_aarch64.apk` | [version number]_GIT | `com.retroarch.aarch64` | +| Stable | Architecture-specific | `RetroArch_ra32.apk` | [version number]_GIT | `com.retroarch.ra32` | +| Nightly | Universal | `YYYY-MM-DD-RetroArch.apk` | [version number]_GIT | `com.retroarch` | +| Nightly | Architecture-specific | `YYYY-MM-DD-RetroArch_aarch64.apk` | [version number]_GIT | `com.retroarch.aarch64` | +| Nightly | Architecture-specific | `YYYY-MM-DD-RetroArch_ra32.apk` | [version number]_GIT | `com.retroarch.ra32` | + +Builds are named with an architecture suffix: `aarch64` is a 64-bit build, `ra32` is a 32-bit build, and no suffix is a universal build that opts for 64-bit if your system supports it. 32-bit support on Android is slowly being phased out by the industry, but these builds remain available for older devices or specific use cases. + +###### Manual Downloads -#### From RetroArch.com Downloads -___ 1. Visit the retroarch.com [Downloads page](https://www.retroarch.com/?page=platforms) and select **Download Stable** or **Download Nightly**. 2. Open the downloaded APK (via a file manager if your browser does not prompt you when the download is completed). 3. Select Install. -##### From Buildbot Archives -___ -All [stable](https://buildbot.libretro.com/stable/{{ unit.stable }}/android/) and [nightly](https://buildbot.libretro.com/nightly/android/) bundles are available via BuildBot If you need a specific architecture or build for testing. Builds are named with an architecture suffix: `aarch64` is a 64-bit build, `ra32` is a 32-bit build, and no suffix is a universal build that opts for 64-bit if your system supports it. -> 32-bit support on Android is slowly being phased out by the industry, but these builds remain available for older devices or specific use cases. +**From Buildbot Archives** + +All [stable](https://buildbot.libretro.com/stable/CURRENTVERSIONNUMBER/android/) and [nightly](https://buildbot.libretro.com/nightly/android/) bundles are available via BuildBot If you need a specific architecture or build for testing. + +##### Installation via Obtainium +"Obtainium allows you to install and update apps directly from their releases pages, and receive notifications when new releases are made available." - Obtainium + +Obtainium installs the latest stable RetroArch APK — whether 32‑bit, AArch64, or Universal — directly from https://buildbot.libretro.com/stable/CURRENTVERSIONNUMBER/android/, the same source used for manual downloads. The only difference is that Obtainium automates this process and provides update notifications, helping users stay current and avoid reporting issues from outdated versions. It’s also worth noting that Obtainium is Android TV–friendly, making it suitable for use across all Android devices. + +To install RetroArch from Obtainium, follow these steps: -### Installation via F-Droid -___ -RetroArch's most recent stable release can be found [in the F-Droid repository](https://f-droid.org/packages/com.retroarch/) for easier automatic updating. +* Install [Obtainium](https://f-droid.org/en/packages/dev.imranr.obtainium.fdroid/) from F-Droid. +* Add RetroArch to Obtainium + * Visit https://apps.obtainium.imranr.dev/. + * Search for "RetroArch". + * Select “Add to Obtainium” for either RetroArch (32-bit), RetroArch (AArch64), or RetroArch (Universal). +* Import and Install + * When the “Import app” prompt appears, tap **Continue**. +* Open the newly added RetroArch entry. +* Tap **Install** to download and install the app. -### (NOT RECOMMENDED) Installation via Google Play -___ -RetroArch is available on the Google Play Store, but has not been updated for years due to Play Store policy changes. You may choose to use this older version, but it is not recommended. +#### Installation via F-Droid (stable 32/64-bit) (incomplete) -[RetroArch Plus on the Play Store](https://play.google.com/store/apps/details?id=com.retroarch.aarch64&hl=en_US "RetroArch64") (Only for 64 bit devices, additional cores) +| Type | Variant | Filename | Version identifier | Package Name | +|---------|------------------|-------------------------------------|--------------------|---------------------| +| Stable | Universal | `com.retroarch_[UNIXTIMESTAMP].apk` | [version number] | `com.retroarch` | -[RetroArch on the Play Store](https://play.google.com/store/apps/details?id=com.retroarch&hl=en "RetroArch") (For 32 or 64 bit devices, fewer cores) + +The F-Droid release of [RetroArch](https://f-droid.org/packages/com.retroarch/) offers the recent stable universal release (com.retroarch) can be found in F-Droid for easier automatic updating. + +To minimize installation size, the F-Droid release includes only a basic set of assets. For a complete setup matching the retroarch.com release it is necessary to visit `Main Menu` → `Online Updater` within the app to download all additional assets, controller profiles, overlays, shaders, and other required data. + +The `ozone` menu driver lacks assets, impacting popular microconsoles (see [#18756](https://github.com/libretro/RetroArch/issues/18756)). Temporary workaround: Main Menu → Online Updater → Update Assets. + +### Installation via Google Play servers (obsolete) + +| Type | Variant | Version identifier | Package Name | +|---------|-----------------------|--------------------------------|-------------------------| +| Stable | Universal | [version number] (YYYY-MM-DD) | `com.retroarch` | +| Stable | Architecture-specific | [version number] (YYYY-MM-DD) | `com.retroarch.aarch64` | + +The stable (but outdated) release of RetroArch is available on the Google Play Store, but has not been updated for years due to Play Store policy changes. You may choose to use this older version, but it is not recommended. A more detailed difference between the Play Store versions can be found in [this libretro blog post](https://www.libretro.com/index.php/retroarch-android-new-versions-for-play-store-please-read/). -# Installation notes +DeGoogle notice: Google Play requires sign-in with a Google account. Aurora Store offers a free alternative enabling anonymous downloads and updates from Google Play servers without a Google account. [Aurora Store](https://f-droid.org/en/packages/com.aurora.store/) is avalible in F-Droid. + +#### RetroArch (stable 32/64-bit, Play Store) +[RetroArch](https://play.google.com/store/apps/details?id=com.retroarch&hl=en "RetroArch") (com.retroarch): Supports both 32- and 64-bit devices. It provides fewer cores than RetroArch Plus but is compatible with a broader range of devices. + +#### RetroArch Plus (stable 64-bit only, Play Store) +[RetroArch Plus](https://play.google.com/store/apps/details?id=com.retroarch.aarch64&hl=en_US "RetroArch64") (com.retroarch.aarch64): Only for 64 bit devices. Includes more cores than the standard RetroArch available on the Play Store. Note: Despite the implication of superiority in its name, RetroArch Plus builds support approximately 80 fewer cores than APKs from retroarch.com across all variants. Also, RetroArch Plus is not avalible on all Android devices even if they have an up to date Android system. -## Side-loading +RetroArch Plus is available on Google Pixel phones because their pure Google hardware and stock OS reliably pass compatibility checks, even for legacy apps. Native Play Store prioritizes "safe" devices and hides the outdated APK on incompatible ones—like those with non-stock OS skins, slower updates, or mid-range SoCs that trigger stricter enforcement of policies like target API levels and storage access. Aurora Store bypasses these filters entirely, making it a reliable workaround for such devices. -* Android may tell you that `the app doesn’t have permission to install APKs`. Click the available `Settings` button in that prompt. -* In the next menu, turn on the toggle allowing the app install APKs. +### Installation notes + +#### Sideloading + +##### Install unknown apps + +The first time you attempt to install an APK via an app (e.g. via any file manager, or Obtainium), Android displays a prompt: `For your security, your phone currently isn't allowed to install unknonw apps from this source. You can change this in Settings`. +* Click the available `Settings` button in that prompt. +* In the `Install unknown apps` menu, toggle on `Allow from this source` to permit the app to install APKs. + - On Android versions prior to 8.0, the APK installation prompt displays a pre-checked "Allow this installation only" checkbox—uncheck it to quickly install RetroArch updates, which is especially relevant when subscribing to daily RetroArch Nightly downloads via Obtainium. * `Hit the back button` to return to your installation. -## Allowing APK installations blocked by Google Play Protect +##### Allowing APK installations blocked by Google Play Protect + +To install RetroArch from non-Google Play sources (such as F-Droid or retroarch.com), you may need to either allow it through Google Play Protect or disable Play Protect entirely. -To install RetroArch from non-Google Play sources (F-Droid, retroarch.com, etc), ensure Google Play Protect either approves it or disable the service entirely. +Since RetroArch 1.19.1, if you skip the methods in the sub-sections below, the app may either fail to install without warning or display the message “App not installed.” This issue appears to affect some Android versions and hardware configurations, but not all. For example, the current RetroArch APK may fail to install on the standard Android version without following these methods, while it may succeed on the current Android TV version. -### Method 1: "Install anyway" in Google Play Protect +If you get "App not installed" your version of Play Protect may have a bug that prevents you from using the feature.[1] If so, use Method 2—disable Google Play Protect to permit blocked APK installs. + +###### Method 1: Selecting ‘Install anyway’ in the Google Play Protect popup + +When you tap "Install" for the APK, Google Play Protect runs a security scan and displays options similar to those shown below: ![google-play-protect_-_install-anyway-1.png](../image/guides/google-play-protect_-_install-anyway-1.png) ![google-play-protect_-_install-anyway-2.png](../image/guides/google-play-protect_-_install-anyway-2.png) -* When you select “Install anyway”, Google Play Protect will ask you to authenticate your identity. For security reasons, this step cannot be captured in a screenshot, which is why it's described here instead. If Play Protect still fails to install the app even after you’ve entered the correct password, you’ll need to disable Google Play Protect. For instructions, see [Method 2: Disable Google Play Protect](#method-2-disable-google-play-protect). - -### Method 2: Disable Google Play Protect +If you get "App not installed," your Play Protect version may have a bug preventing use of the "Install anyway" feature.[1] In that case, use Method 2—disable Google Play Protect to permit blocked APK installs. -If Google Play Protect still blocks the app installation even after you entered the correct password in Method 1 (a common issue on older Android versions), you'll need to temporarily disable Play Protect to proceed. +###### Method 2: Disable Google Play Protect -Disable Google Play Protect: -* Open the Play Store app first -* Tap your profile icon -* Select Play Protect -* Tap the gear icon in settings -* Toggle off "Scan apps with Play Protect" +* Open the Google Play Store app. +* Locate and tap "Play Protect" — its location depends on your Android version and whether you’re signed in: + - Tap the hamburger menu (☰) in the upper-left or upper-right corner. + - If you’re signed in, check both the hamburger menu (☰) and your profile icon, as Play Protect may appear under either. The profile icon shows your account initial (e.g., “F” for Foo). +* Tap the gear icon ⚙️ to open Settings. +* Toggle off "Scan apps with Play Protect": + - You may be asked whether to "Pause" scanning temporarily or "Turn off" permanently — choose the option you prefer. +* Install the APK — Play Protect will no longer interfere with the process. +* Note: Android may prompt you to re-enable Play Protect each time you sideload an APK. If your goal is to keep it permanently turned off, always select "No" when prompted. -Once disabled, install the APK — Play Protect will no longer interfere with the process. +## References +Case Report: On Android 10 with LG G7 ThinQ (LM-G710EM), after factory reset, signing into Play Store (allowing self-update and setup), sideloading RetroArch 1.22.2 from retroarch.com and tapping "Install anyway" triggers "App not installed" before the password prompt—even with the correct password entered. Disabling Play Protect was the sole workaround to install the APK; otherwise, factory reset with offline sideloading was required.