Beginners step-by-step guide to building your own firmware


Inspired by the Quick Image Building Guide I've written a guide which is meant to show any Windows or Debian/Ubuntu user exactly what to do in order to set up a system to build their own firmware. Let me know what you think:


Docs are always hard. But always good to have more. I found the quick start guide was adequately simple. But I like that yours goes into those cases where the target is not straight forward. And should be good for those running windows.

I really wish that the devs would accept that PR (pull-request) on github for xconfig. That would be a BIG improvement for the config stage. Much better than menuconfig by far. It will be more familiar to windows users too.


You could add that on windows 10 there is linux subsystem by default and users can use it to make it even simpler without that virtual OS stuff :slight_smile:


Thanks, I've added a notice about it.


@Per and @matemana2608 was just reading about postmarketos and they are saying that it's not possible to build under the win10 linux subsystem. Has LEDE build been tested under win10 linux subsystem?


@per, as one of the Windows users here I appreciate you taking a stab at this, but at least for this (dumb) Windows user I really do not understand the tool sets and not clear which one I am using here.

Let me try to frame things a bit. I think there are 2 basic tools, Image Builder and Toolchain. Not sure I got the names correct. One creates from a set of packages and the other from source code which I guess are all the pieces on github. I also think that I can do either of these for snapshot or based upon the the latest LEDE release version, which I would suspect, assuming my device is supported, to be the safest way to build and also offer a fixed set of packages to use if I want to add more stuff later. Unfortunately the docs do not explicitly state which tool is being used, at least not in terms I understand.

I am not sure which process this guide is focused on, when\how to install the Supplementary Files located at the bottom of these pages or what file is what.

Regarding the Quick Image Building Guide (I realize you did not author this) am I correct that this totally omits my point directly above?

Finally, why would I use one too over the other?


If all you want to do is customize an image quickly (add/remove packages, add files, modify default settings) -- you can use Image Builder. You can also use SDK in this case, but Image Builder is a simpler and quicker way to go.

If you want to patch drivers/packages or modify the compilation settings for a package -- you have to use SDK.


@Blarty_Runfaster: It seems to build just fine. I haven't actually tried the resulting firmware and I did get a few warnings the first time I tried building. I haven't seen the errors again in subsequent builds, even when I tried to recreate them by deleting everything and checking out again. It's extremely slow, though, particularly if the virus scanner is enabled.

@RangerZ: I haven't used the SDK and I don't know the specifics about it. The guide uses the image builder. If you follow the guide you'll get a release image, and if you skip the "git checkout" under section 2.1 you'll get the snapshot (also called trunk). I can empathize with your need to understand "everything", I'm kind of like that myself. However, I have tried to skip explaining alternatives most users don't needed to know about in order to build a firmware. I think the guide is a bit long already.


What is the difference between
git clone lede
cd lede
git checkout tag_name

git clone -b tag_name lede



I don't think there are any important differences in the resulting checkout. I just don't want to hard code a particular version in the documentation.


This is good info to add to the docs. That way someone will know what to expect if they try it.



I've given up getting this working by myself. I'm trying to configure image builder to make a default image for my wrt1900acs v1 routers. I've read all the reference material and have gotten the menu to come up but can't figure out how to add my hardware to the list. I'm running Debian and have done the git to checkout the latest image (18.06.1).

Any assistance on what I need to still do would be appreciated.



Something like this?;

apt install build-essential libncurses5-dev gawk git subversion libssl-dev gettext zlib1g-dev swig unzip time git curl wget
tar -xvf *mvbu*
cd open[TAB]
make help
make info
make PROFILE='linksys-wrt1200ac'


There's a description of how to find it under (I just added "selecting the router model" to make it clearer).

In your case you could google wrt 1900 acs wikidevi, which would find You'll notice it says CPU: Marvell 88F6820-A0 C160 @1.6GHz (Armada 385). You then need to look for it under Target System in menuconfig. The closest match is Marvell EBU Armada, so select it. Then go to Subtarget and you'll find that the closest match is Marvell Armada 37x/38x/XP. Last, select Target Profile, and you'll now find Linksys WRT1900ACS (Shelby). Exit and save, and you'll get a default image by running make.


Thank you for the assistance! This guide has been extremely valuable to my project. Thanks for taking the time to put it together.

I think it would also be helpful to articulate in the router selection section how to add router not included by default. I was trying to piece together how to do that from a couple guides and wasn't successful in adding a router model manually.

Also, it would be extremely helpful to have some detail about the various menu options. There's so many selections it's easy to get lost. For example, I'm still not clear on what the various menu option do under Global build settings. Is that how I select the default packages you mention in the guide?

My goal is to have a generic backup with a set of packages such as ddns and openvpn pre-configured when I deploy a new router. I'll be playing around with the menu settings to figure things out but thought I'd comment on the above from a novice POV.

Thanks again for the effort you put into this guide!


If you mean adding a router that is not currently supported by OpenWrt then that requires expert knowledge above my level. You need a fair amount of knowledge about both C and how programming hardware. There is a guide here:

Yes, there are a lot of options, too many for me to try to describe them all. However, I have updated a bit.

In particular I added this part:

The selectable software is in the submenues from “Base system” and downwards. Start by going to LuCI / Applications, as this section lists the LuCI packages for the most commonly used software. Selecting them will also include the required dependencies.

Thankyou for your feedback.


Success! I just got my first firmware compiled.

During the build I selected conflicting packages (wpad (full) & wpad (mesh) which killed my build. It would be helpful to state that imagebuilder doesn't have much in the way of package conflict management. For your first time, you will most likely have errors. Use "make -j1 V=s" to see what errors occur. Should they be conflicting packages, deselect the packages to generate a successful build.

Lastly, is there a way to incorporate my backup from the first router I configured into my firmware? Or should i just grab the config files like the guide you suggested I read indicates?

Thanks again, Mike


The files you need will be in the backup you made, but there will also be some files that it is better to exclude because they are hardware specific or they should be generated at first boot. You can use the backup as a starting point, but check every file and only include those that you are certain about.

The way I do it is to log into the router after having set it up and copy the files which have been changed by my edits under /overlay/upper/etc/. Check the time stamp, it makes it easy to see if they were generated during the first boot or by later changes.