How to Install LineageOS on the OnePlus One with Linux

September 27, 2017

I've recently acquired a OnePlus One and I wanted to run a free and open source operating system on the device. Lineage OS is an Android operating system with additional privacy and usability features added. It also lacks Google's proprietary software and services, which makes it a good candidate for users who don't want Google services spying on their personal information.

However, most tutorials for this hacking and installation process are written for Microsoft Windows. So I've decided to use this as an opportunity to write a walk-through for this process targetted for GNU/Linux users (specifically, users of Debian and Ubuntu). The specific version I'm using while writing this is Ubuntu Linux 17.04.1. This tutorial will walk you through gathering the required tools, unlocking the bootloader, installing LineageOS, and a bit more.

Installing the required tools on Ubuntu Linux (17.04)

You'll need a user shell so open a terminal window if using a desktop environment.

We'll first update our repositories to make sure we have the latest software versions available:

sudo apt-get update

Now we'll install some tools from the Android SDK Platform that we'll need to access the partitions on our phone.

sudo apt-get install android-tools-adb android-tools-fastboot

Next, lets check to see if abd is installed and running by executing its version printing function:

adb version

The output should read something such as: Android Debug Bridge version 1.0.32

Next, we'll need to enable developer options and USB debugging on the OnePlus One. To do this, unplug your phone from USB and go to your Android settings. Scroll to the bottom and find the menu option "About phone" or "About devices". Tap the build number 7 times. This should unlock the Developer options. Now go to to the main settings list again and locate the entry "Developer options". Tap that entry to enter. Then, locate the "Update Cyanogen recovery" entry and disable it. Next, locate the "USB debugging" entry and enable it. Re-connect your phone to USB and check to see if adb can see the device by running:

adb devices -l

On the phone, you should be prompted to accept the connection from the computer. Allow this connection on your phone. The command in adb should now show your device and its unique ID. If you can see this, you are ready for the next step.

Unlock the Bootloader

Note: The next steps will wipe your data and reset your phone. So backup any data you want to save now! This warning was requested by readers.

Reboot your device into the bootloader mode with the command:

adb reboot bootloader

Now, we will unlock the bootloader and erase the stock firmware:

sudo fastboot oem unlock

The phone will reboot, erase the stock bootloader, and start back up into android. Let it load through the boot process and start up, this may take awhile. In the mean time, you can download additional required files.

Download Team Win Recovery Project (TWRP)

You can download the latest TWRP image for the OnePlus One (codename, bacon) from the project's official repository. TWRP is an Android Recovery Software. It provides an environment for you to interact with the system software on the phone.

Download Lineage OS

You can download the latest version of Lineage OS the OnePlus One from their official bacon respository.

Download Lineage OS Extras

Download any extras you may need for Lineage OS:

Note: Personally, I'd recommend against using Gapps if you can avoid it. Once it is flashed onto the device it is extremely hard to remove without completely re-wiping your device and installing the system from a fresh image. If you need an "app" software repository, I'd recommend trying F-Droid (I will show you how to install it at the end of the tutorial). F-Droid has a much safer set of applications that are more respectful of your personal data and privacy. The majority of the software available in F-Droid's repositories are either free or open source. Google's Play Store contains a lot of proprietary (closed source code) software that are known to collect and sell massive amount of personal data and telemetry such as location, contacts, calendar, usage data, and usually much more. Many of the free apps will contain malicious advertisements that can track you as well.

Back on topic, In most cases, these files will now be saved in the Downloads folder of your user folder.

Flash Recovery onto the Phone

Once your device is done setting up Android again (after the bootloader unlock), you can skip through the introduction menus. Then go back into the settings menu and re-enable the developer options in the menu, go into the developer options, disable "Update Cyanogen recovery" and enable "Android Debugging". Make sure the phone is still connected to your computer with a USB cable. When prompted by your phone, re-allow access from your computer.

To avoid confusion with other downloaded files, rename the twrp image file to "recovery.img".

In terminal change the working directory into your Downloads folder or where ever you saved the other files to:

cd ~/Downloads

We will now upload the new recovery software onto the phone after putting the phone back into recovery mode:

adb reboot bootloader

sudo fastboot flash recovery recovery.img

fastboot will upload the TWRP image to the recovery partition. Allow it to finish. You know it has finished when it displays "finished. total time: ...."

Now, reboot the device:

sudo fastboot reboot

The phone will boot into Android. Once has booted up, you can reboot into recovery by holding the power button + volume down buttons. Once the phone starts up, you can release the power button and only continue to hold down the volume down button on the device. This should bring you into TWRP. It's OK if you miss telling it to launch into recovery at this point. Just let it boot into the OS, then reboot and try to launch it into recovery by holding the power + volume down buttons at boot.

Welcome to TWRP

Swipe to enable modifications. Do not keep your system partition in read-only. We will be writing to this partition.

Backup Stock Operating System

First, lets make a backup of the stock CyanogenOS that comes with the OnePlus One. I recommend you archive this somewhere on the device or on a hard drive just in case you ever need to restore the phone to stock.

Select the "Backup" menu entry. Select a name I prefer "$date - CyanogenOS Stock". Select all the partitions to backup (cache is optional and probably unnecessary) then swipe to start the backup process. It should take a few minutes then vibrate when its completed. Then, go back to the main menu of TWRP.

Wipe the device

I'm not sure if this is necessary as flashing Lineage OS may overwrite the partitions but its safer to be sure and just wipe the partitions. The partitions we will wipe are: Dalvik, System, Data, and Cache. DO NOT wipe Internal Storage as that is what we have just used to store our backup. If you need to wipe the internal storage, make sure you copy the backup and other files over first. In my guide, I have my internal storage already cleaned up of any personal files. Slide the slider to being the wipe process. It should complete quickly. Go back to the main menu.

Install Lineage OS

Once at the TWRP main menu, copy the main Lineage OS zip file to your internal storage on the device. You can use the USB connection or something like an OTG (on the go) USB cable + thumb-drive. Also, move any of the Lineage add-ons that you downloaded into this folder too. I have put my linage zip in my Download folder on the phone for now. You can keep these in a folder on the device to have as a backup. You may come in handy in the future if you ever need to re-flash the system. so I'd recommend archiving them somewhere.

We will now install LineageOS and our add-ons. Select the "Install" entry in the main menu. Go to the "Download" folder (usually /sdcard/Download). The main "lineage" .zip file that you downloaded and moved. Verify that you have selected the right file. Then swipe to confirm the flash. The phone will begin to unpack and flash the system partition with Lineage OS. If you did not wipe the Dalivk / ART cache before in the wiping section of this guide, you should do this now.

Note: this following setup of flashing the addonSU binary is optional.

If you want to apply the superuser / root function to your phone (only do this if you know what this does), you can do so now by going back to the main menu, selecting "Install" and doing the same process we just did except this time select the "addonsu" .zip file. You can follow this process to install "opengapps" as well.

You can now reboot the device from the menus (Reboot --> System). TWRP will offer to install a TWRP App. You do not need this. It is optional. I've unchecked both options and then pressed the "Do Not Install" button. TWRP will offer this almost every time you use the TWRP menu. It's obnoxious. Your device will now reboot into Lineage OS. Congratulations, you have completed the process!

Troubleshooting

If you encountered an error, its likely that the files that you downloaded were corrupt or did not download properly. Try downloading them again and retrying.

If you get stuck in a boot loop, try going back to TWRP and flashing an older version of Lineage OS.

Installing F-Droid

You will need to have mobile data or a wifi connection to do this. Otherwise you will need to download the F-droid APK from your computer and transfer it via USB to your phone's internal storage first.

To install the app repository, F-Droid, simply go through the intro Lineage OS menus on first boot. Once you reach the home-screen / desktop. You can open up your phone's web browser and go to F-Droid's Homepage. Then select the Download F-Droid button on their site. Allow the browser to access storage, then select the download option. Your phone will download the APK file. Once it is downloaded, select it from the phone's drop down menu / notification slide down menu. You will be prompted that you need to enable unknown sources before you can install this. Click the settings option and you will be taken to your settings menu. Find the "Unknown sources" option and enable it. You will be prompted about the risk in doing this, press OK. Unknown sources should be enabled now. Press the home key, open your app drawer, and select "Files". Then select "Downloads", then Select the FDroid.apk. Press "Install". Your phone will install F-droid. When its done, press "done". Press the home button and open the app drawer again. Open the "settings" app and go to the "Security" section. Locate "Unknown source" and disable this option. Now, go back to your app drawer and locate F-Droid. It will open. You need to press the refresh button in the top right (looks like a circle arrow) and F-Droid will update its repositories and show the apps you can install.

Thank you for reading! Enjoy Lineage OS.