ImmortalWrt: an OpenWrt fork for mainland China users, and what it changes

What ImmortalWrt solves that upstream OpenWrt does not

OpenWrt is a general-purpose router distribution. ImmortalWrt is a fork of it, and the README is explicit about the trade: "Compared to upstream, we allow to use (non-upstreamable) modifications/hacks to provide better feature/performance/support." That single sentence explains most of the project's character. Upstream OpenWrt rejects patches that are not maintainable or not general, so packages that depend on non-upstreamable changes never land there. ImmortalWrt accepts them. The README also states the fork carries more packages ported, more devices supported, default optimized profiles, and localization modifications for mainland China users. The intended audience follows from that: someone in mainland China who wants a router firmware that already includes the package set and defaults they would otherwise assemble by hand. If you are outside that audience and you are happy with upstream's package list, the fork's main selling point does not apply to you.

How the tree is organized and how a firmware image is produced

The repository is a buildroot-style tree, not an application. The top level holds target/, toolchain/, tools/, package/, include/, scripts/, config/ and feeds.conf.default. The root Makefile sets TOPDIR, forces LC_ALL to C, LANG to C and TZ to UTC, and errors out immediately if the path to the tree contains a space. It then branches on OPENWRT_BUILD. On the first pass it includes include/toplevel.mk, which is the user-facing entry point; on the second pass it includes target/Makefile, package/Makefile, tools/Makefile and toolchain/Makefile, and wires the stamp dependencies so the toolchain compiles before targets, and targets compile before packages. That is the data flow: feeds define where packages come from, menuconfig writes a .config, and make walks tools, toolchain, target and package in that order, cross-compiling the kernel and the selected applications for the chosen target. The final images land in the build output for the target you selected. Nothing in the README describes a release branch scheme, so the branch you clone determines what you get.

Installing ImmortalWrt firmware without building it

Most users should not compile anything. The README points at the ImmortalWrt Firmware Selector at https://firmware-selector.immortalwrt.org/ and says built images are available for many architectures with a package selection for use as a WiFi home router. The selector is also the documented way to find a factory image for migrating from a vendor stock firmware. Once the device is running, the README gives the default login address as http://192.168.1.1 or http://immortalwrt.lan, with username root and password none. The README says to follow the Info link on the selector page for install instructions per device, and it does not reproduce those steps itself. Treat the password as a first-boot default to change, not a security posture.

# default access after flashing, per the README
# http://192.168.1.1  or  http://immortalwrt.lan
# username: root
# password: none

Building your own image from source

Building is supported on GNU/Linux, BSD or macOS with a case sensitive filesystem. The README prefers Debian 11 on AMD64 with at least 4GB RAM and 25GB of free disk. There are two documented ways to install dependencies on Debian or Ubuntu: a long explicit apt install list, or a one-liner that pipes a remote script into bash. Both are in the README, and the second one runs code from build-scripts.immortalwrt.org as root, which is a decision the reader should make deliberately. The quickstart is five commands plus make. Note the clone flags: single branch and a blobless filter, so the checkout is not a full history.

# Method 2 from the README, run as your normal user with sudo rights
sudo bash -c 'bash <(curl -s https://build-scripts.immortalwrt.org/init_build_environment.sh)'

After dependencies are in place, the README's quickstart is:

git clone -b <branch> --single-branch --filter=blob:none https://github.com/immortalwrt/immortalwrt
cd immortalwrt
./scripts/feeds update -a
./scripts/feeds install -a
make menuconfig
make

The feeds step pulls package definitions from feeds.conf.default and symlinks them into package/feeds/. menuconfig selects the toolchain, target system and firmware packages. The final make downloads sources, builds the cross-compile toolchain, then cross-compiles the kernel and the chosen applications. Expect this to take a long time and to fail on missing host tools before it succeeds.

Where ImmortalWrt is the wrong choice

The README is candid about host constraints, and they are real limits. Cygwin is unsupported because it lacks a case sensitive filesystem. WSL requires removing Windows folders from PATH, and the README links to OpenWrt's WSL setup page rather than documenting it here. macOS as a build host is "not recommended" with "No warranty at all." Non-AMD64 CPUs may compile but need "more hacks" and carry no warranty. Paths must not contain spaces or non-ASCII characters. Beyond the build host, the fork's core premise is a limitation for some users: accepting non-upstreamable hacks means patches you rely on may never be reviewed by upstream maintainers, and the README documents no rollback procedure, no release cadence and no versioning scheme. If your requirement is a firmware whose every patch has passed upstream review, this is the wrong tree. If you need a documented downgrade path, the README does not give you one.

ImmortalWrt vs OpenWrt: the actual difference

The difference is not a rewritten core. ImmortalWrt is a fork of OpenWrt, uses the same buildroot layout, the same feeds mechanism, the same opkg package manager (the README states all packages are installed via opkg), and points its documentation at openwrt.org. The divergence is in what is allowed into the tree and what ships by default: more ported packages, more supported devices, optimized profiles and mainland China localization. Upstream OpenWrt optimizes for patches that can be maintained generally; ImmortalWrt optimizes for features that work for its users even when upstream would reject them. That also means the package repositories are separate: the README lists immortalwrt/luci and immortalwrt/packages as the places to look for the web interface and ported packages, and it points at OpenWrt's routing and video repositories for those categories. If you are choosing between them, the practical question is whether the extra packages and device support matter more than upstream's review process.

Licence and the upgrade bill

The README states ImmortalWrt is licensed under GPL-2.0-only, and the root Makefile carries an SPDX-License-Identifier of GPL-2.0-only with a 2007 OpenWrt copyright line. Note that the repository metadata reports the licence as NOASSERTION while the README and the Makefile header both say GPL-2.0-only; if you redistribute firmware or patches, read the COPYING file and the LICENSES/ directory rather than trusting the metadata field. GPL-2.0-only means derivative distributions carry source obligations, but this is not legal advice. On upgrade cost, the README says nothing about supported upgrade paths, sysupgrade behaviour or configuration migration. The last push to the repository was on 2026-09-21, so the tree is moving, but movement is not the same as a documented upgrade contract. Budget for re-flashing and reconfiguring rather than assuming in-place upgrades are described.

Editorial conclusion

Adopt ImmortalWrt if you are in mainland China, your device appears in the Firmware Selector, and you want the extra ported packages without patching upstream yourself. Do not adopt it if you need upstream OpenWrt's review guarantees, a documented release cadence, or the ability to use Cygwin, macOS or a Windows filesystem with spaces in the path. Before flashing, verify three things: that your exact model is supported and a factory image exists, that you have a recovery path back to the stock firmware, and that you are willing to track a fork whose README documents no versioning or rollback policy. The default login is the first thing to confirm, because the README states password none for root.

Frequently asked questions

Official sources

1. immortalwrt/immortalwrt on GitHub
2. Issues
3. Project website
4. README