diff --git a/docs/guides/install-android.md b/docs/guides/install-android.md index 2e832074ac..c5d18750f4 100644 --- a/docs/guides/install-android.md +++ b/docs/guides/install-android.md @@ -1,9 +1,130 @@ ---- -title: "Install RetroArch on Android" -description: "How to download, install and update RetroArch on Android by side-loading the APK, and why the Google Play release is not recommended." ---- +# Downloading, Installing and Updating RetroArch for Android devices -# Downloading, Installing and Updating RetroArch for Android devices. +## RetroArch APK Package Variants + +| 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. This suffix also appears in RetroArch.com APK filenames. 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, on a typical 64-bit device, install both RetroArch variants: +- `com.retroarch` + `com.retroarch.aarch64` + +## Sources + +### Overview + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Installation
SourceFilenameTypeTitleVersion identifierPackage name
RetroArch officialRetroArch.apkStableRetroArch[version number]_GITcom.retroarch
RetroArch officialRetroArch_aarch64.apkStableRetroArch (AArch64)[version number]_GITcom.retroarch.aarch64
RetroArch officialRetroArch_ra32.apkStableRetroArch (32-bit)[version number]_GITcom.retroarch.ra32
RetroArch officialYYYY-MM-DD-RetroArch.apkNightlyRetroArch[version number]_GITcom.retroarch
RetroArch officialYYYY-MM-DD-RetroArch_aarch64.apkNightlyRetroArch (AArch64)[version number]_GITcom.retroarch.aarch64
RetroArch officialYYYY-MM-DD-RetroArch_ra32.apkNightlyRetroArch (32-bit)[version number]_GITcom.retroarch.ra32
F-Droidcom.retroarch_[UNIXTIMESTAMP].apkStableRetroArch[version number]com.retroarch
Play Store-StableRetroArch[version number] (YYYY-MM-DD)com.retroarch
Play Store-StableRetroArch Plus[version number] (YYYY-MM-DD)com.retroarch.aarch64
+ +### 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. + +##### RetroArch.com + +###### Manual Downloads ## Non-Google Play sources @@ -18,55 +139,118 @@ ___ 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** -### 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. +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. -### (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 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: + +* 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. + +##### RetroArch.com Package Installation Notes + +###### Install both stable and nightly RetroArch + +This section expands on the [Multi-Package Installation](#multi-package-installation) documentation, focusing specifically on retroarch.com builds. -[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) +On a typical 64-bit device, install both stable and nightly RetroArch versions as follows: +- Stable `com.retroarch` + nightly `com.retroarch.aarch64`, or +- Stable `com.retroarch.aarch64` + nightly `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) +###### Compatibility of `com.retroarch.ra32` on 64-bit ARM Devices -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/). +The 32‑bit `com.retroarch.ra32` package can typically be installed on most Android devices because 64‑bit ARM processors generally include support for running 32‑bit applications, and manufacturers usually configure the system images to enable that compatibility: -# Installation notes +``` +adb shell getprop ro.zygote # → zygote64_32 +adb shell getprop ro.product.cpu.abilist # → arm64-v8a,armeabi-v7a,armeabi +``` -## Side-loading +Note: An exception is Google. Google Pixel 6a and newer devices running Android 12 (and later) ship with 64‑bit‑only system images (ro.zygote=zygote64, no 32‑bit ABI support). On such devices, pure 32‑bit APKs will fail to install with the error INSTALL_FAILED_NO_MATCHING_ABIS. -* 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. +#### F-Droid + +The F-Droid release of [RetroArch](https://f-droid.org/packages/com.retroarch/) offers the recent stable `com.retroarch` (32/64-bit ARM) package 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. + +##### F-Droid issue + +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. + +### Google Play servers + +RetroArch is available on the Google Play Store, but is outdated and thus not recommended (see [Google Play servers issue](#google-play-servers-issue)). + +Both RetroArch, and RetroArch Plus is available on Play Store and. 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/). + +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 available in F-Droid. + +#### RetroArch on Play servers +[RetroArch](https://play.google.com/store/apps/details?id=com.retroarch&hl=en): It uses the package `com.retroarch`, which supports both 32- and 64-bit ARM devices. It provides fewer cores than RetroArch Plus but is compatible with a broader range of devices. + +#### RetroArch Plus on Play servers +[RetroArch Plus](https://play.google.com/store/apps/details?id=com.retroarch.aarch64&hl=en_US): Uses the package `com.retroarch.aarch64`, supporting only 64-bit ARM devices. It includes more cores than standard RetroArch but ~80 fewer cores than retroarch.com APKs across all variants. Note: Despite its name, RetroArch Plus isn't available on all up-to-date Android devices. + +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. + +#### Google Play servers issue +The Play Store releases of RetroArch 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 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 unknown 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 (F-Droid, retroarch.com, etc), ensure Google Play Protect either approves it or disable the service entirely. +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. -### Method 1: "Install anyway" in Google Play Protect +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. -![google-play-protect_-_install-anyway-1.png](../image/guides/google-play-protect_-_install-anyway-1.png) +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. -![google-play-protect_-_install-anyway-2.png](../image/guides/google-play-protect_-_install-anyway-2.png) +###### Method 1: Selecting ‘Install anyway’ in the Google Play Protect popup -* 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). +When you tap "Install" for the APK, Google Play Protect runs a security scan and displays options similar to those shown below: -### Method 2: Disable Google Play Protect +![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) -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. +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. -Disable Google Play Protect: +###### Method 2: 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. diff --git a/docs/guides/install-gnu.md b/docs/guides/install-gnu.md index 4e3559bfba..b53525fe1d 100644 --- a/docs/guides/install-gnu.md +++ b/docs/guides/install-gnu.md @@ -20,103 +20,91 @@ installing RetroArch on systems running the GNU/Linux kernel. ## AppImage (suitable for most GNU/Linux distributions) -### AM +### AM/AppMan -[AM](https://github.com/ivan-hc/AM) is a powerful command-line package manager for managing AppImage software. It allows users to install, update, and remove AppImages either system-wide or locally without manual setup. +[AM](https://github.com/ivan-hc/AM) (and its user-level counterpart `AppMan`) is a command-line package manager for managing AppImages, maintained alongside the [Portable Linux Apps](https://portable-linux-apps.github.io/) catalog. Both tools are installed via the main `AM` repository installer. -1. Installation +#### 1. Setup AM or AppMan -There are no system packages available for AM in common repositories, so it must be installed manually. +There are no system packages available for AM in common repositories, so it must be installed manually by following the official setup guide: [https://github.com/ivan-hc/AM](https://github.com/ivan-hc/AM). -Follow the official installation instructions provided at: [https://github.com/ivan-hc/AM](https://github.com/ivan-hc/AM) +During setup, select your preferred installation mode: -During setup, you’ll be prompted to choose one of two installation modes: +* **Option 1: AM** – System-wide installation (requires root privileges). +* **Option 2: AppMan** – Local user-level installation (no root access required). -* Option 1: AM – for system-wide AppImage management (requires root privileges). -* Option 2: appman – for local, user-level AppImage management (no root access required). -Choose the option that best suits your environment and permissions. +#### 2. Managing RetroArch with AM/AppMan -2. Searching for AppImages +##### AM/AppMan web catalog -Once installation is complete, verify that AM or AppMan is working by performing a search. -Use the appropriate command depending on your installation: +The web catalog serves as a browser interface for discovering packages and obtaining initial installation commands: -``` -# For system-wide installation -am -q retroarch +1. Open your browser and navigate to [`https://portable-linux-apps.github.io/`](https://portable-linux-apps.github.io/). +2. Search for **"RetroArch"** in the search bar (or go directly to [`https://portable-linux-apps.github.io/?s=RetroArch`](https://portable-linux-apps.github.io/?s=RetroArch)). +3. Select your preferred variant (`retroarch`, `retroarch-nightly`, `retroarch-qt`, or `retroarch-qt-nightly`). +4. Click the **"Install"** button on the application entry page to reveal the terminal command. +5. Copy and run the generated installation command in your terminal. -# For user-level installation -appman -q retroarch +##### AM/AppMan CLI management -``` +All package lifecycle tasks—searching, installing, updating, and maintaining the tool itself—are managed directly via the terminal. -This query searches for available AppImages matching “retroarch” and displays a list of results. -Example output: +**Searching Packages:** +Search for available RetroArch packages in the repository database: -``` -$ appman -q retroarch - - SEARCH RESULTS FOR "RETROARCH": +```bash +# System-wide +am -q retroarch - ◆ retroarch-nightly : RetroArch is a free and open-source, cross-platform frontend for emulators, game engines, video games, media players and other applications. - ◆ retroarch-qt-nightly : RetroArch is a free and open-source, cross-platform frontend for emulators, game engines, video games, media players and other applications. - ◆ retroarch-qt : RetroArch is a free and open-source, cross-platform frontend for emulators, game engines, video games, media players and other applications. - ◆ retroarch : RetroArch is a free and open-source, cross-platform frontend for emulators, game engines, video games, media players and other applications. +# User-level +appman -q retroarch ``` -3. Installing an AppImage - -To install your chosen AppImage, use the `-i` flag followed by the specific package name. For example, you can install either the stable release (for everyday use) or the Nightly build (ideal for testing): +**Installing Packages:** +Install your chosen package variant: ```bash -# For system-wide installation (Stable) +# System-wide installation (Stable) am -i retroarch -# For system-wide installation (Nightly) -am -i retroarch-nightly +# System-wide installation (Qt Nightly) +am -i retroarch-qt-nightly -# For user-level installation (Stable) +# User-level installation (Stable) appman -i retroarch -# For user-level installation (Nightly) -appman -i retroarch-nightly -``` +# User-level installation (Qt Nightly) +appman -i retroarch-qt-nightly -4. Updates +``` -To update RetroArch, use the `-u` (or `--update`) flag. Running the update command without specifying a package name will update all installed AppImages managed by the tool: +**Updating Packages & Tools:** +Keep RetroArch packages and the package manager scripts updated: +* **Update all installed AppImages:** ```bash -# Update all system-wide AppImages -am -u - -# Update all user-level AppImages -appman -u +am -u # System-wide +appman -u # User-level ``` -Alternatively, you can target a specific package to update only that application. This is especially useful if you have multiple Continuous Integration (CI) AppImages of other software installed that you rarely use. Since the [official bug report template](https://github.com/libretro/RetroArch/blob/master/.github/ISSUE_TEMPLATE/01-bug-report.yml) encourages using the latest AppImage, updating just `retroarch-nightly` to test your issue on the latest build before reporting is recommended: - - +* **Update a specific RetroArch package:** ```bash -# For system-wide installation -am -u retroarch-nightly - -# For user-level installation -appman -u retroarch-nightly +am -u retroarch-qt-nightly # System-wide +appman -u retroarch-qt-nightly # User-level ``` -> **Note:** Make sure to use the exact package name that you originally installed (e.g., `retroarch`, `retroarch-nightly`, `retroarch-qt`, or `retroarch-qt-nightly`). -5. Notes and Recommendations +#### 3. Notes and Recommendations * Nightly builds are recommended when submitting bug reports or testing new features. * Stable releases are better suited for everyday use. -* Use the same tool (am or appman) for all lifecycle tasks—installation, updates, and removal. +* Use the same tool (`am` or `appman`) for all lifecycle tasks—installation, updates, and removal. + ## Flatpak (suitable for most GNU/Linux distributions)