LineageOS for MicroG on the Pixel 3a

By: Owen T. Heisler
Updated: 2024-09-08
Published: 2021-06-09

The goal

  • Mostly open source operating system

  • For privacy and security, no Google account/login is required

  • Apps from the Google Play Store are available for use

  • System root available for any apps that require it (such as for backups and ad blocking)

  • Uses the privacy-respecting microG substitute for the Google Services Framework (required by many apps on the Play Store)

  • Software updates beyond Google’s end-of-life (May 2022—see When you’ll get Android updates on Google Support)

The phone

Obviously this page targets the Google Pixel 3a, but of course there are a variety of variants falling under this designation. The phone used for testing was as follows:

  • Model G020G, the “North America” model

  • The phone is bootloader unlockable. This is an absolute requirement: locked bootloaders prevent the installation of custom software on a phone. Generally, Pixel devices purchased from Google are bootloader unlockable whereas devices purchased from carriers are not, but this is not universally true.

  • The phone is SIM unlocked—not necessary for installing LineageOS, but I recommend only purchasing SIM unlocked phones so the device’s network compatibility is not artificially limited.

For more information about the Pixel 3a, see the Pixel 3a Wikipedia page.

Computer requirements

A computer with the Android adb and fastboot utilities is required. On Debian 11 Bullseye, these can be installed by running apt install adb fastboot as root.

A USB port and a USB-C cable are also necessary.

Also download the LineageOS for microG files before starting—see Install LineageOS for microG, below.

Unlock the bootloader

To unlock the bootloader:

  1. Navigate to Settings > About phone and tap Build number multiple times until developer options are enabled.

  2. Navigate to Settings > Developer options and enable both OEM unlocking and USB debugging.

  3. Connect the phone to your computer and run adb -d reboot bootloader. The phone may ask whether to Allow USB debugging?—tap Allow. Run the command again if it times out while requesting permission. The phone should now be in Fastboot Mode.

  4. Check that the device is visible in fastboot mode by running fastboot devices. The device should be listed. Then run fastboot flashing unlock to unlock the bootloader. Use the volume keys on the phone to select Unlock the bootloader and then press the power button to confirm.

  5. Once the phone has finished resetting, press the power button (Start) to boot the phone again.

Update the stock firmware

Before beginning the process of setting up LineageOS for microG, the stock firmware should be updated. This is necessary because LineageOS cannot maintain and distribute all of the phone’s firmware, such as the modem firmware, but LineageOS does expect that firmware to be current (as published by Google—see Google’s Factory Images for Nexus and Pixel Devices).

To update the stock firmware, navigate on the phone to Settings > System > Advanced > System update. Repeatedly check for, install, and apply updates until there are no more updates available.

Install LineageOS for microG

In addition to the steps below, you can consult the LineageOS for microG Installation instructions as well as the Install LineageOS on sargo page on the LineageOS Wiki.

  1. Download the recovery image and installation package. See the LineageOS for microG sargo downloads listing. You need the latest *.zip and *.img files. I used these:

    $ sha256sum *
ccaac2391eeb4fddb7c045b18c814b9a9c50135e70e9c9fa9073b7f3f0d84d47  lineage-18.1-20210411-microG-sargo-recovery.img
005f6eb4549e782ed6e1a47f529bc4eab19098fb77c9abdd9803a589ce3d2294  lineage-18.1-20210411-microG-sargo.zip

  2. Enable USB debugging again as described in Unlock the bootloader (steps 1 and 2).

  3. Connect the phone to your computer and run adb -d reboot bootloader. Again the phone may ask whether to Allow USB debugging?—tap Allow. Run the command again if it times out while requesting permission. The phone should now be in Fastboot Mode.

  4. Flash Lineage Recovery on the phone by running fastboot flash boot lineage-18.1-20210411-microG-sargo-recovery.img (for example).

  5. Use the volume keys to select Recovery Mode and press the power button to confirm. The phone should boot into Lineage Recovery with a menu.

  6. Tap Factory reset and Format data/factory reset and finally confirm by tapping Format data. You can ignore any can't send spi message errors in the output. Once the format is complete, return to the main menu by tapping the back arrow.

  7. “Sideload” the installation package by tapping Apply update and Apply from ADB. The phone will wait to receive the package. On the computer, run adb -d sideload lineage-18.1-20210411-microG-sargo.zip (for example) to send the file to the phone. When this is finished, go back to the main menu, navigate to Advanced, and tap Reboot to recovery.

Install Magisk

Magisk can be installed by renaming the app APK and sideloading via Recovery.

  1. Download the Magisk v27.0 (or later stable release) APK to the computer. The file is available on the Magisk Releases page on GitHub.

  2. On the computer, change the Magisk APK file extension to .zip (for example, mv Magisk-v27.0.apk Magisk-v27.0.zip).

  3. From recovery, tap Apply update and Apply from ADB.

  4. Sideload the Magisk ZIP file:

    $ adb -d sideload Magisk-v27.0.zip

  5. When asked about failing signature verification, accept it by tapping Yes.

  6. Reboot the phone.

  7. Navigate to System > Advanced > Developer options and disable USB debugging.

  8. Open the Magisk app, open the settings (the gear icon at the top right), and tap Systemless hosts. This will add a Magisk module that allows modification of the hosts file (commonly used for ad blocking).

In this case, we are using Magisk to provide superuser/root access for apps that require it. Magisk will prompt you when an app requests root access. Apps with permission are listed in the Magisk app, on the Superuser page (look for the button at the bottom).

Magisk can also install modules to modify system partitions during the boot process. Modules are managed on the Modules page of the Magisk app. There are no modules that need to be installed for the purposes of this document.

System configuration

  1. Open the F-Droid app, navigate to Settings > Repositories, and enable the Guardian Project repository.

  2. In Settings, navigate to System > Advanced > Developer options. Disable USB debugging; you can enable it again later if necessary. Enable Local terminal for local shell access—look for Terminal in the app list and type su to get root access there if necessary.

  3. In Settings, navigate to System > Advanced > microG Settings > Location modules and enable both. If asked for permission, set it to Allow all the time by following the instructions given.

  4. Some GSF-dependent apps use Google’s Cloud Messaging (GCM) service to register for “push” notifications. Without cloud messaging, an app may that depends on it not receive messages promptly. Cloud messaging can be enabled in microG Settings: first enable Google device registration and then enable Cloud Messaging. If you have an app that you think uses cloud messaging but microG Cloud Messaging status shows On - 0 registered Apps, then try the following.

    1. Disable Cloud Messaging and then disable Google device registration. Reboot the phone.

    2. Enable Google device registration and reboot the phone.

    3. Enable Cloud Messaging and reboot the phone.

    See orestarod’s post on Reddit for some other things to try if that does not work.

Other suggestions

  • Backup and restoration of individual apps (including both app data and user data) can be done with the Neo Backup app, available on F-Droid. This app requires root. Unlike adb backup, Neo Backup does not arbitrarily refuse to backup some apps. Unlike SeedVault, any app can be restored anytime, rather than only during initial setup of the phone.

  • Adaway, available on F-Droid, can be set up to block ads system-wide. Choose Root based ad blocking.

  • The Aurora Store app, available on F-Droid, allows you to browse and install apps from the Google Play Store. Choose the Root installer method. You do not need to have/use a Google account; just select the Anonymous login. Because you do not want Aurora Store to replace microG with the standard Google Play services app from the Play Store, be sure to blacklist the com.google.android.gms app: tap Updates tab at the bottom, long tap the Google Play services app, and tap Add to Blacklist (in the Blacklist Manager, the app will be labeled as microG Services Core). Aurora Store will indicate when an app “requires GSF” (the Google Services Framework); these services are being provided by microG instead.

  • The Molly app, available on F-Droid, is an independent fork of Signal that is compatible with Signal and provides end-to-end encrypted messaging and calling on Android and iOS. Signal Desktop is also available for Linux, macOS, and Windows. If you have cloud messaging enabled but Molly has not registered, trigger a new attempt: in Molly, navigate to Settings > Privacy > Advanced, and disable and enable Signal messages and calls (you will have to receive an SMS message to re-register, so make sure you are able to receive an SMS message when you do this).

  • The SimpleX Chat app, available on F-Droid, is a fully decentralized, encrypted chat messenger that is superior to Signal/Molly.

  • Battery life (referring to battery aging, measured in months/years, not runtime measured in hours) can be significantly improved by using charge thresholds. Consider installing AccA, available on F-Droid. This is an installer and interface for the Advanced Charging Controller (ACC). Make sure Magisk is active before running AccA; it will require superuser privileges. AccA can automatically install ACC for you, likely as a Magisk module. For more information about improving battery life, see Battery University’s BU-808: How to Prolong Lithium-based Batteries.

Creating a system backup

A system backup (also called a NANDroid backup) can be made by temporarily booting TWRP on the phone.

  1. Determine the current Android version on the phone (Lineage for microG is based on LineageOS which is based on the Android Open Source Project). This can be found under Settings > About phone > Android version and should be either 11 or 12. For a LineageOS and AOSP version cross-reference, see the LineageOS version history on Wikipedia.

  2. Go to the TWRP for Google Pixel 3a page. Click on one of the “Primary” download links; for example, the Americas mirror is here. Download the latest image file that matches your currently installed version of Android. For example, twrp-3.7.0_12-0-sargo.img is for Android 12 (LineageOS 19).

  3. Connect the phone to the computer via USB and enable USB debugging as described in the Install Magisk section.

  4. Rename (or copy) the file to twrp.img.

  5. Turn on airplane mode. This is not strictly required, but it allows you to control when any remotely synchronizing apps are able to connect again after a restore.

  6. Reboot the phone to bootloader mode by running adb -d reboot bootloader.

  7. Temporarily boot the TWRP image by running fastboot boot twrp.img.

  8. Tap the Backup button to view a list of partitions that can be backed up.

  9. For each partition that you want to back up, run adb -d backup -f <partition.ab> --twrp --compress <partition>. The -f option specifies the backup path on the computer. For example, adb -d backup -f boot.ab --twrp --compress boot will back up the boot partition to boot.ab in the current directory.

    If you encounter createTarFork() process ended with ERROR: 255 while backing up the data partition, run adb -d shell while TWRP is active and check the recovery.log file on the phone (look in /data/media/0/TWRP/BACKUPS/). See createTarFork() process ended with ERROR: 255 when trying to back up data with multiple users on GitHub for more information.

  10. Reboot the phone, disable USB debugging, and turn off airplane mode.

Restoring a system backup

If you want to restore a system backup created by TWRP using the steps in the previous section, follow these steps.

  1. Boot TWRP as described in steps 1-6 of the previous section.

  2. Run adb -d restore --twrp <partition.ab> for each partition that you want to restore.

  3. Reboot the phone and make sure USB debugging is disabled.

Updating

System updates provided by the Lineage for microG project can be installed via the regular Lineage Updater mechanism at Settings > System > Updater. However, before rebooting, install Magisk again. This time, select the Install to Inactive Slot (After OTA) method. Reboot after the installation is finished. Magisk and any installed modules should persist if everything works correctly. If Magisk does fail to persist across the system update, reinstall it by enabling USB debugging, running adb -d reboot recovery, and following the instructions in the Install Magisk section.

Note that major upgrades may require manual action; in this case, follow the manual upgrade steps outlined in Upgrade LineageOS on sargo, using the microG files instead of standard LineageOS. Before rebooting (or after, it doesn’t matter), sideload Magisk again as described in the Install Magisk section.

Credits

  • Thanks to the microG Project developers who also publish builds of LineageOS for microG

  • Thanks to the LineageOS developers and maintainers

  • Thanks to orestarod for his post on Reddit

Changes

  • 2024-09-08: Update Magisk version.

  • 2024-03-11: In the Creating a system backup section, added the use of airplane mode.

  • 2024-03-11: Added -d option to all adb commands.

  • 2024-03-11: In the Other suggestions section, added Neo Backup replaced Signal with Molly, and added SimpleX Chat.

  • 2022-12-02: Added the Creating a system backup and Restoring a system backup sections

  • 2022-05-23: Added a step in Install Magisk for adding the Magisk hosts file module

  • 2022-02-12: Updated the AccA/ACC entry in Other suggestions (AccA can do the ACC installation itself)

  • 2022-02-12: Updated various details in the Install Magisk section for Magisk v24.1

  • 2022-02-12: Improved the Updating section by changing the Magisk installation method and adding details about major upgrades

  • 2021-12-13: Simplified Magisk installation and updating by using the sideload installation method

  • 2021-10-26: Extended the Updating section with explicit steps

  • 2021-09-05: Added the Updating section

  • 2021-06-22: Simplified steps for setting up cloud messaging

  • 2021-06-22: Added Signal instructions for re-registering cloud messaging

  • 2021-06-22: Added note about blacklisting the microG app in the Aurora Store

  • 2021-06-21: Changed order to unlock the bootloader first, then update stock firmware

  • 2021-06-10: Added more details about setting up cloud messaging