Skip to main content
The first full build takes approximately 30 to 90 minutes on modern hardware, depending on:
  • CPU speed and number of cores (the build uses parallel compilation)
  • Whether the toolchain needs to be compiled from scratch (it does on the first run)
  • Network speed for downloading source archives
  • Disk I/O speed
A typical 8-core machine can complete a full build in 30–45 minutes. Subsequent builds that only recompile changed packages are much faster (seconds to a few minutes).To maximize build speed:
# Use all available CPU cores
make -j$(nproc)
This error almost always means you have not run the feed setup steps. After a fresh clone, you must install the packages from the configured feeds:
./scripts/feeds update -a
./scripts/feeds install -a
Then run make menuconfig to select your target and packages, and rebuild.Other possible causes:
  • A package dependency references a package that is not installed from any feed
  • A package name was changed and your .config references the old name (run make defconfig to clean it up)
Run make menuconfig and navigate to the package category. Packages have three states:
KeyStateMeaning
yBuilt-inPackage is compiled into the firmware image
mModulePackage is compiled as a .ipk but not included in the image
n / spaceExcludedPackage is not built
Press y on a package to include it in the firmware. Press m to build it as an installable package only.Alternatively, set it in a minimal config file:
CONFIG_PACKAGE_curl=y
No, not directly. OpenWrt requires a case-sensitive filesystem and a POSIX-compatible build environment, which Windows does not provide natively.Supported options:
  • WSL2 (Windows Subsystem for Linux 2): Install Ubuntu or Debian from the Microsoft Store. Make sure to work inside the WSL2 filesystem (e.g., ~/openwrt), not inside /mnt/c/ (which is a case-insensitive NTFS mount).
  • Linux VM: Use VirtualBox, VMware, or Hyper-V with a Linux guest.
  • Native Linux: The recommended approach.
  • macOS: Supported with Homebrew dependencies, but requires a case-sensitive volume.
Building on /mnt/c/ or any NTFS path under WSL will fail. Always use the native Linux filesystem inside WSL2.
Use the package-specific compile target:
# Recompile a single package
make package/curl/compile V=s

# Clean and recompile
make package/curl/{clean,compile} V=s

# Recompile and re-create the .ipk
make package/curl/compile package/index V=s
To rebuild the final image after recompiling packages:
make target/install
make package/index
The sysupgrade command reads /etc/sysupgrade.conf to determine which files to back up before flashing and restore afterward.Add files or directories to preserve:
# /etc/sysupgrade.conf
/etc/config/
/etc/dropbear/
/etc/opkg/customfeeds.conf
/root/.ssh/
During a sysupgrade, these files are archived to RAM, the new firmware is flashed, and the files are restored to the overlay.
Files in /etc/config/ are preserved by default. Only add extra paths for files outside the standard config location.
Image TypeUsed ForCharacteristics
factoryFirst installation from the device’s original vendor firmwareOften includes a vendor-specific header, checksum, or partition layout required by the vendor’s bootloader or web UI
sysupgradeUpgrading an existing OpenWrt installationSimpler format; just kernel + rootfs in the layout expected by the OpenWrt sysupgrade script
Using the wrong image type will typically result in a failed or bricked flash. Always use:
  • factory image when flashing from the vendor’s stock firmware for the first time
  • sysupgrade image when upgrading from an existing OpenWrt installation
SSH (via Dropbear) is enabled by default on the LAN interface in a standard OpenWrt installation.To connect:
ssh root@192.168.1.1
On a fresh install, there is no password for the root account. You will be prompted to set one via the web interface (LuCI) or via the CLI:
passwd
If SSH is not accessible:
  • Verify you are connected to the LAN port (not WAN)
  • Check that the firewall is not blocking port 22 on the LAN
  • Ensure Dropbear is running: /etc/init.d/dropbear status
To reset OpenWrt to its defaults (clearing the overlay partition):
# Reset and reboot in one step
firstboot && reboot

# Or: just wipe the overlay without rebooting immediately
firstboot
firstboot calls jffs2reset (or the equivalent for your filesystem) which marks the overlay for erasure. On the next boot, the device starts fresh from the read-only SquashFS base.
All installed packages, configuration changes, and added files will be lost. Make sure to back up /etc/config/ first if needed.
Alternatively, use the hardware reset button if your device supports it (typically hold for 10 seconds during boot, behavior varies by device).
By default, the build outputs to the terminal with minimal verbosity. To capture detailed logs:
# Verbose output showing all commands
make V=s 2>&1 | tee build.log

# Verbose output for a single package
make package/curl/compile V=s 2>&1 | tee curl-build.log
The V=s flag enables verbose mode showing every command executed. The 2>&1 redirects stderr (where most build errors appear) to stdout so tee can capture both.If CONFIG_BUILD_LOG=y is set in .config, per-package logs are automatically saved to logs/ in the build root.To find the specific error in a long log:
grep -i 'error:' build.log | head -20