Building a single package

Useful if you want to upgrade a package without reflashing the router.

If you would like to apply an out-of-tree patch to, backport a single patch to, or even manually edit the source code of a package, then instead see the instructions for working with patches.

Follow the Build system usage up to the point when you make menuconfig. In here, select the target platform, then tick the package you want to build, and also its dependencies. If the package isn't ticked, the below commands will succeed without actually building the package. If you don't know the dependencies, you can ask the router. Let's assume we want to build nano:

# opkg info nano
Package: nano
Version: 2.2.5-1
Depends: libncurses
Provides:
Status: install user installed
Architecture: ar71xx
Installed-Time: 1300757537
 
# apk info --depends nano
nano-8.7.1-r2 depends on:
libc
libncurses6

The Depends: line is what we're interested into. The same information can also be found in the Packages file from the package repository.

Now issue the following commands:

make tools/install
make toolchain/install

The next step is building the dependencies. Back to our nano example:

make package/ncurses/compile

To build the host version of ncurses (that's used by make menuconfig below, for example):

make package/ncurses/host/compile

And finally, you get to build the package:

make package/nano/compile
make package/index

Done! You will find your coveted package in the bin/ directory.

If you get errors about not finding opkg in the staging directory, compile and install package/base-files.

If you get errors that the package is not found, make sure you're typing the package directory name, not the package name listed in the Makefile (which may be different when a single Makefile builds multiple packages).

The problem we face when using the Latest snapshot, is that opkg quickly becomes incompatible with the snapshot as it moves forward in time. The idea is to use the feeds script with -a flag to prep all possible packages. Then when you want to install packages down the road, you go into make menuconfig, set the packages you want as modules <M>. Then do make package/compile to compile them as IPK files to the bin directory. Then you can scp them to the router /tmp for instance, and opkg install them. Sometimes opkg complains about MD5 mismatch with remote, or kernel version mismatch. Use opkg override flags if you must, E.G. --force-depends and/or --force-checksum.

One way or another, you'll need the toolchain first. make package/[kernel-module] will not build modules, only package them. If they weren't built previously then you'll only get empty module packages. Instead:

make menuconfig

In the menuconfig, select your module such that an <M> appears, save and exit.

make target/linux/compile
make package/kernel/linux/compile

The resulting ipk will be in the bin/targets/[target]/[subtarget]/packages directory. You can scp it to the router and use opkg install.

You can always just rebuild everything.

make defconfig download clean world

You have forked the repository for one of the packages included in OpenWrt.
You have created your own branch for a pull request.
You have committed some changes.
Now you want to build a package that includes your changes and test it in your OpenWrt installation.

Follow Build system usage, with the following specifics:

• git checkout the correct version tag for your OpenWrt installation.
• Update and install the feeds.
• See [[:docs:guide-developer:toolchain:use-buildsystem#official_config]|Official Config] and get the .config file for your OpenWrt installation.
• Do make menuconfig, and configure 'Target Profile' for your OpenWrt installation, and Save to .config.
• Do make defconfig, make download, make clean and make world as described.

Assuming you want to build a package named PACKAGE. In the openwrt repository, the Makefile for the package is package/CATEGORY/PACKAGE/Makefile.

Looking at the original settings in the package/CATEGORY/PACKAGE/Makefile, for example:

PKG_SOURCE_URL=$(PROJECT_GIT)/project/PACKAGE.git
PKG_SOURCE_PROTO:=git
PKG_SOURCE_DATE:=2025-12-02
PKG_SOURCE_VERSION:=66127cd76c5d0bd46d5a90302cc6110f53a4e2f8
PKG_MIRROR_HASH:=ff23a9825aeac8da14a7142e985d598043c0287a463279f24863c580622bf18d
PKG_ABI_VERSION:=20250120

Change the following:

• set PKG_SOURCE_URL to the git URL of your fork.
• set PKG_SOURCE_DATE to the date of your commit.
• set PKG_SOURCE_VERSION to the commit hash of your commit. A branch name does not work. Make sure that your code is compatible with the original PKG_SOURCE_VERSION if required.
• comment out PKG_MIRROR_HASH for now, by placing a # in front of it.
• if necessary, change PKG_ABI_VERSION. If for example you changed the external interface of a shared library, and it is no longer 'binary compatible' with the applications that use it, for example because one of the callable functions has an additional argument, you need to update it and probably also build packages for all applications that use it.

Now you can build your package with:

make packages/CATEGORY/PACKAGE/{clean,compile}

Some packages build multiple .apk files, look at the package Makefile you edited to see which.

You can find the .apk file(s) somewhere in the bin directory.

find bin -name '*.apk'

Copy the .apk file(s) to your router, then

apk --allow-untrusted add PACKAGE.apk