This is the WebUSB-based installer for GrapheneOS and is the recommended approach for most users. The command-line installation guide is the more traditional approach to installing GrapheneOS.
If you have trouble with the installation process, ask for help on the official GrapheneOS chat channel. There are almost always people around willing to help with it. Before asking for help, make an attempt to follow the guide on your own and then ask for help with anything you get stuck on.
You should have at least 2GB of free memory available and 8GB of free storage space.
You need a USB cable for attaching the device to a laptop or desktop. Whenever possible, use the high quality standards compliant USB-C cable packaged with the device. If your computer doesn't have any USB-C ports, you'll need a high quality USB-C to USB-A cable. You should avoid using a USB hub such as the front panel on a desktop computer case. Connect directly to a rear port on a desktop or the ports on a laptop. Many widely distributed USB cables and hubs are broken and are the most common source of issues for installing GrapheneOS.
Installing from an OS in a virtual machine is not recommended. USB passthrough is often not reliable. To rule out these problems, install from an OS running on bare metal. Virtual machines are also often configured to have overly limited memory and storage space.
Officially supported operating systems for the web install method:
- Windows 10
- macOS Big Sur
- Arch Linux
- Debian 10 (buster)
- Ubuntu 20.04 LTS
- Ubuntu 20.10
- Google Android on GrapheneOS-supported devices
Make sure your operating system is up-to-date before proceeding.
Officially supported browsers for the web install method:
- Chromium (outside Ubuntu, since they ship a broken Snap package without working WebUSB)
- Vanadium (GrapheneOS)
- Google Chrome
- Microsoft Edge
Make sure your browser is up-to-date before proceeding.
Do not use Incognito or other private browsing modes. These modes usually prevent the web installer from having enough storage space to extract the downloaded release.
You need one of the officially supported devices. To make sure that the device can be unlocked to install GrapheneOS, avoid carrier variants of the devices. Carrier variants of Pixels use the same stock OS and firmware with a non-zero carrier id flashed onto the persist partition in the factory. The carrier id activates carrier-specific configuration in the stock OS including disabling carrier and bootloader unlocking. The carrier may be able to remotely disable this, but their support staff may not be aware and they probably won't do it. Get a carrier agnostic device to avoid the risk and potential hassle. If you CAN figure out a way to unlock a carrier device, it isn't a problem as GrapheneOS can just ignore the carrier id and the hardware is the same.
It's best practice to update the device before installing GrapheneOS to have the latest firmware for connecting the phone to the computer and performing the early flashing process. Either way, GrapheneOS flashes the latest firmware early in the installation process.
Enabling OEM unlocking
OEM unlocking needs to be enabled from within the operating system.
Enable the developer options menu by going to Settings ➔ About phone and repeatedly pressing the build number menu entry until developer mode is enabled.
Next, go to Settings ➔ System ➔ Advanced ➔ Developer options and toggle on the 'Enable OEM unlocking' setting. This requires internet access on devices with Google Play services as part of Factory Reset Protection (FRP) for anti-theft protection.
Flashing as non-root
On traditional Linux distributions, USB devices cannot be used as non-root without udev rules for each type of device. This is not an issue for other platforms.
On Arch Linux, install the
android-udev package. On Debian and Ubuntu, install the
Booting into the bootloader interface
You need to boot your phone into the bootloader interface. To do this, you need to hold the volume down button while the phone boots.
The easiest approach is to reboot the phone and begin holding the volume down button until it boots up into the bootloader interface.
Alternatively, turn off the phone, then boot it up while holding the volume down button during the boot process. You can either boot it with the power button or by plugging it in as required in the next section.
Connecting the phone
Connect the phone to the computer. On Linux, you'll need to do this again if you didn't have the udev rules set up when you connected it.
On Windows, you may need to install a driver for fastboot now: In Windows Update, click Check for updates. After that there might be a link "View optional updates." Download and install any driver updates. If there are no optional updates, simply continue with the installation instructions.
Unlocking the bootloader
Unlock the bootloader to allow flashing the OS and firmware:
The command needs to be confirmed on the device and will wipe all data. Use one of the volume keys to switch the selection to accepting it and the power button to confirm.
Obtaining factory images
You need to obtain the GrapheneOS factory images for your device to proceed with the installation process.
Press the button below to start the download:
Flashing factory images
The initial install will be performed by flashing the factory images. This will replace the existing OS installation and wipe all the existing data.
Wait for the flashing process to complete. It will automatically handle flashing the firmware, rebooting into the bootloader interface, flashing the core OS, rebooting into the userspace fastboot mode, flashing the rest of the OS and finally rebooting back into the bootloader interface. Avoid interacting with the device until the flashing script is finished and the device is back at the bootloader interface. Then, proceed to locking the bootloader before using the device as locking wipes the data again.
Locking the bootloader
Locking the bootloader is important as it enables full verified boot. It also prevents using fastboot to flash, format or erase partitions. Verified boot will detect modifications to any of the OS partitions and it will prevent reading any modified / corrupted data. If changes are detected, error correction data is used to attempt to obtain the original data at which point it's verified again which makes verified boot robust to non-malicious corruption.
In the bootloader interface, set it to locked:
The command needs to be confirmed on the device and will wipe all data. Use one of the volume buttons to switch the selection to accepting it and the power button to confirm.
You've now successfully installed GrapheneOS and can boot it. Pressing the power button with the default Start option selected in the bootloader interface will boot the OS.
Disabling OEM unlocking
OEM unlocking can be disabled again in the developer settings menu within the operating system after booting it up again.
After disabling OEM unlocking, we recommend disabling developer options as a whole for a device that's not being used for app or OS development.
Verified boot authenticates and validates the firmware images and OS from the hardware root of trust. Since GrapheneOS supports full verified boot, the OS images are entirely verified. However, it's possible that the computer you used to flash the OS was compromised, leading to flashing a malicious verified boot public key and images. To detect this kind of attack, you can use the Auditor app included in GrapheneOS in the Auditee mode and verify it with another Android device in the Auditor mode.
The Auditor app works best once it's already paired with a device and has pinned a persistent hardware-backed key and the attestation certificate chain. However, it can still provide a bit of security for the initial verification via the attestation root. Ideally, you should also do this before connecting the device to the network, so an attacker can't proxy to another device (which stops being possible after the initial verification). Further protection against proxying the initial pairing will be provided in the future via optional support for ID attestation to include the serial number in the hardware verified information to allow checking against the one on the box / displayed in the bootloader. See the Auditor tutorial for a guide.
After the initial verification, which results in pairing, performing verification against between the same Auditor and Auditee (as long as the app data hasn't been cleared) will provide strong validation of the identity and integrity of the device. That makes it best to get the pairing done right after installation. You can also consider setting up the optional remote attestation service.
Replacing GrapheneOS with the stock OS
Installation of the stock OS via the stock factory images is similar to the process described above but with Google's web flashing tool. However, before locking, there's an additional step to fully revert the device to a clean factory state.
The GrapheneOS factory images flash a non-stock Android Verified Boot key which needs to be erased to fully revert back to a stock device state. After flashing the stock factory images and before locking the bootloader, you should erase the custom Android Verified Boot key to untrust it:
Please look through the usage guide and FAQ for more information. If you have further questions not covered by the site, join the official GrapheneOS chat channels and ask the questions in the appropriate channel.