Google Pixel 3a (google-sargo)/Installation guide

🚧	This page is a work-in-progress. Some information contained within may be inaccurate or incomplete. In particular: The instructions on this guide have not been verified to work. Expect to need other resources to use this guide.

Pre-installation

In this section, you will obtain two partition images comprising a full installation of postmarketOS and prepare your device to be flashed with them.

Read through

Read the pre-installation and installation sections fully before taking any steps. One of the worst things that can happen is being left with no working OS on your device, postmarketOS or otherwise, and no volunteers immediately available on the Matrix and IRC channels. Plan ahead, fully understand the instructions, and decide on the details of your desired installation first.

Back up your data

Your data will be wiped when you lock or unlock your bootloader, and when you install to the userdata partition. Back up any important data somewhere safe.

Additionally, if you wish to use your device regardless of whether you perform a successful installation, be prepared to reinstall your current operating system.

Allow bootloader unlocking

If you already have a custom ROM installed with the bootloader unlocked, skip this section.

On Android, go to the About phone page in the Settings app. Click on the build number 7 times to enable developer settings. You will be prompted for your PIN or password.

In the Settings main page, go to System, then Developer options. Enable OEM unlocking.

No unlock codes are needed to enable unlocking on this device.

Obtain an installation

A complete installation for this device can be created with pmbootstrap.

Building your own images with pmbootstrap

The pmbootstrap program can be used to create a custom installation when there are no pre-built images to fit your needs. You may wish to install a different UI, boot from netboot, test unfinished features, or install to a testing-category device.

See Pmbootstrap for instructions on how to set up pmbootstrap and prepare an installation for your device. You will be prompted for your sudo password.

Enter flashing mode

Hold down the power button and select Power off to power off the device. Then press Power and Volume Down at the same time to enter flashing mode.

In flashing mode, connect to your device with a USB cable.

Unlock the bootloader

If you already have a custom ROM installed with the bootloader unlocked, skip this section.

Before flashing anything, you need to unlock the bootloader with this command:

$ fastboot flashing unlock

Follow the prompts on your device's screen to complete the operation. This will erase your data.

Choose a target partition

The boot image must always be flashed to the boot partition.

By default, pmbootstrap installs the rootfs image for your device to the userdata partition. The rootfs can be installed to various places, depending on your needs:

The system dynamic partition

This is a small partition which normally stores read-only system components for an Android-like OS. It is not intended for user data, but can be used for a dual-boot installation.

This partition needs to be flashed in fastbootd instead of the bootloader fastboot. Run this command while in the bootloader to enter fastbootd:

$ fastboot reboot fastboot

The system partition

This is a small partition which normally contains dynamic partitions like system, vendor, etc.

You cannot use pmbootstrap's built-in flasher for this partition. If you have a rootfs image from pmbootstrap, run:

$ pmbootstrap export

Then use the /tmp/postmarketOS-export/google-sargo.img and /tmp/postmarketOS-export/boot.img images as prebuilt images.

To flash to this partition, add the --force option to fastboot when flashing the rootfs image further down.

The userdata partition

This uses the majority of your device's internal storage and is normally used to store files for the user on an Android-like OS. Choose this partition if you want to use most of your device's storage.

Choose a target slot

Flashing both images to mismatched slots will not prevent postmarketOS from booting, but will limit your opportunities to dual-boot. Before flashing anything, choose the slot that you wish to install to.

If you wish to dual-boot, you should select the opposite slot of the current one, so that you can continue running the most up-to-date version of your Android-like OS.

For example, if the current slot in the flashing interface is b:

$ fastboot getvar current-slot
current-slot: b
Finished. Total time: 0.013s

flash postmarketOS to slot a:

$ fastboot set_active a

Installation

In this section, you will install postmarketOS on your device.

Erase the DTBO

The device tree overlay, or DTBO, supplements the kernel's device tree. Android installs this by default.

Thanks to a hack in the kernel fork, you do not need to erase the DTBO partition.

Keeping the DTBO comes with a few side effects. Instead of seeing "Google Pixel 3a" as the machine name, you might see something like "Google Inc. MSM sdm670 S4 PVT v1.0".

You can erase it with the following command:

$ fastboot erase dtbo

Flash the installation

Flashing a pre-built installation

You can flash a pre-built installation with fastboot.

$ fastboot flash system_a 19700101-0000-postmarketOS-v23.06-phosh-0.1-google-sargo.img
$ fastboot flash boot_a 19700101-0000-postmarketOS-v23.06-phosh-0.1-google-sargo-boot.img

Flashing an installation created with pmbootstrap

There is a built-in flashing utility included in pmbootstrap. Flash with:

$ pmbootstrap flasher flash_rootfs # You can flash to the default partition
$ pmbootstrap flasher flash_rootfs --partition system # or to a custom partition like system

Finally, flash the kernel:

$ pmbootstrap flasher flash_kernel

Launch the installation

On the device, navigate to the Start option with the volume keys, then press the Power button.

Alternatively, you may run this command:

$ fastboot reboot

Recovering from a faulty connection

You should ideally have a reliable USB connection.

If your cable disconnects while flashing, reconnect it and set your active slot again.

$ fastboot set_active a

Then, try to flash the same partition again and continue.

Maintenance

Updating

As with other distros, keep your system up-to-date with the apk package manager.

Keeping your installation on a dual-boot setup

Android updates normally make use of both slots to apply updates seamlessly, but you may have postmarketOS installed on one of them.

If you have an Android-like OS installed that publishes regular updates that you want to apply, back up your installation before applying these updates.

Reboot to your Android-like OS, apply the update, and reboot again to complete it.

Then restore your postmarketOS installation on the opposite slot:

$ fastboot flash system_b postmarketOS-rootfs.img
$ fastboot flash boot_b postmarketOS-boot.img

This will change the slot of your installation, so keep track of it.