You can build ProtonAOSP yourself, whether it’s for adding changes to an officially-supported device or porting it to a new device.
You’ll need a reasonably capable computer to avoid running into issues:
- 16+ GB of RAM
- 400+ GB of free SSD storage
Prepare your system
Follow Google’s environment setup instructions to prepare your Linux build environment for building Android.
You can only build on Linux. If you’re on Windows or macOS, create a Linux virtual machine before proceeding.
Keep in mind that Android’s shell setup script only supports
Download the source code
If you don’t have the source code already, see Download to get a copy before building.
Create a device tree
If your device isn’t officially supported by ProtonAOSP, you’ll need to create a device tree that works with AOSP.
This is out-of-scope for our documentation, so you will need to seek other resources for help. Good luck!
On devices with a Qualcomm SoC, most device trees for other custom ROMs won’t work with ProtonAOSP because they depend on open-source code from Qualcomm (CAF) that isn’t part of AOSP. ProtonAOSP doesn’t include most of the infrastructure necessary to build CAF parts, so you will need to adapt the device tree to work with pure AOSP.
Google Pixel devices
Pixel devices are a special case because Google provides AOSP device trees that mostly work out-of-the-box. However, you still need to make some changes in order to get a satisfactory result. The ideal changes are device-specific, but you can use the official device trees as reference material for adapting other Pixel trees.
You can generally test Google’s device trees with no modifications if you remove
json-c from it, but your mileage may vary. Keep in mind that you need to prefix the device codename with
aosp_ when building with unmodified AOSP trees, e.g.
Build the OS
To compile a development (
eng) build for debugging:
# Load shell helpers
# Replace $DEVICE with your device's codename
# Start the actual build
Once you’re ready to use the build yourself or ship it to users, you can do a production (
Run this command before building if you want to include Google services:
Flash the build
For quick testing, we recommend simply flashing the built images directly with fastboot. For example, on a device with dynamic partitions and boot image v3:
# Flash boot-critical partitions first
fastboot flash boot out/target/product/$DEVICE/boot.img
fastboot flash dtbo out/target/product/$DEVICE/dtbo.img
fastboot flash vendor_boot out/target/product/$DEVICE/vendor_boot.img
fastboot flash --disable-verity --disable-verification vbmeta out/target/product/$DEVICE/vbmeta.img
# Reboot to userspace fastbootd
fastboot reboot fastboot
# Flash the rest of the system
fastboot flash system out/target/product/$DEVICE/system.img
fastboot flash system_ext out/target/product/$DEVICE/system_ext.img
fastboot flash product out/target/product/$DEVICE/product.img
fastboot flash vendor out/target/product/$DEVICE/vendor.img
Make sure you wipe data before booting ProtonAOSP for the first time:
Packaging for release
Flashing the built images directly works for testing, but it’s not very convenient for end users. You’ll want to package them in a format that users can flash before releasing the build.
For Pixel devices, the most natural packaging format is factory images. This is how Google primarily distributes the stock OS. To build a package of factory images:
# Build target files package
# Build packaging tools
# Convert target files to images zip
python2 out/soong/host/linux-x86/bin/img_from_target_files \
# Convert images zip to factory images
The factory images package can be found in
Some devices, such as the Pixel 4 series (coral and flame), name their factory images directory differently. For example:
The most common way to package custom ROMs is to build full OTA packages:
The flashable OTA package can be found in