# cilynx/rtl88x2bu: an out-of-tree driver that tells you when to stop using it

> This is an updated version of Realtek's 5.6.1.6 WiFi source for RTL88x2BU USB adapters, with compatibility reported on kernels from 5.4 through 7.2. Its own README documents the migration to the mainline rtw88 driver and states that as of Linux v6.16 the maintainer no longer uses this driver.

**cilynx/rtl88x2bu** — rtl88x2bu driver updated for current kernels.

- Repository: https://github.com/cilynx/rtl88x2bu
- Website: http://www.wolfteck.com/2018/02/22/wsky_1200mbps_wireless_usb_wifi_adapter/
- Stars: 1,755 · Forks: 329
- Language: C
- License: GPL-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/cilynx-rtl88x2bu

## The README already tells you to migrate

Most kernel driver READMEs exist to help you install. This one leads with an exit plan. It states that rtw88x2bu support was added to the mainline Linux kernel a few versions ago, around 6.4, and that the repository will be maintained until either comments on issue 270 convince the maintainers the mainline driver works well, or the two contributors agree that silence means nobody still uses this and they archive it.

There is a second note that changes how you should read everything else. As of Linux v6.16 the maintainer is no longer using the driver, because of stability problems with either the dongle or the driver. They switched to a new adapter supported by the mainline kernel and cannot detect subtle issues themselves anymore.

The repository is not archived and the last push was on 2026-08-31, so the code still builds. But a driver whose author has stopped running the hardware is a different proposition from one that is actively chasing kernel changes, and that is the judgement to make before you install it.

The code itself is Realtek's 5.6.1.6 source, found bundled with the Cudy WU1200 AC1200 High Gain USB Wi-Fi Adapter and downloadable from Cudy's site, updated to compile against current kernels.

## Building is make, loading is insmod, and the system may freeze

The direct route is two commands. Build the module, then load it for the current session only:

```shell
make
insmod 88x2bu.ko
```

That gives you a working adapter without touching the system's persistent configuration, which is the right way to find out whether the driver works for you at all.

The README carries a warning that your system may freeze instantaneously, and advises saving work first. That is worth taking literally: an out-of-tree WiFi driver doing DMA against a chip whose firmware and reference design vary between dongles is exactly the situation where a bad interaction surfaces as a hard reset rather than an error message.

The Makefile confirms what kind of code this is. It is the Realtek vendor tree, not a distro package: a Kconfig full of per-chip CONFIG_ toggles, the RTL8822B chip selected and every other variant switched off, USB_HCI enabled with PCI, SDIO and GSPI disabled, and a long list of compiler warning suppressions including -Wno-array-bounds and -Wno-stringop-overread. Those suppressions are there to get vendor code past kernel warnings, not because the warnings are spurious.

## DKMS registration is a Makefile edit away

To have the driver present at boot, the README points at a script named deploy.sh that registers the module in DKMS for all kernels, for a specific kernel, or for the currently active one. It advises consulting --help and reading the script before running it, and notes that registering a kernel module in DKMS is a major intervention.

The Raspberry Pi section shows the manual equivalent, which is useful even on other hardware because it makes the DKMS sequence explicit. After installing prerequisites with git dnsmasq hostapd bc build-essential dkms raspberrypi-kernel-headers, the version is read out of dkms.conf and the tree is copied into place:

```bash
VER=$(sed -n 's/\PACKAGE_VERSION="\(.*\)"/\1/p' dkms.conf)
sudo rsync -rvhP ./ /usr/src/rtl88x2bu-${VER}
sudo dkms add -m rtl88x2bu -v ${VER}
sudo dkms build -m rtl88x2bu -v ${VER} # Takes ~3-minutes on a 3B+
sudo dkms install -m rtl88x2bu -v ${VER}
```

The Raspberry Pi also needs the architecture switched, since the Makefile defaults to x86:

```shell
sed -i 's/I386_PC = y/I386_PC = n/' Makefile
sed -i 's/ARM_RPI = n/ARM_RPI = y/' Makefile
```

The comment says the DKMS build takes about three minutes on a Pi 3B or later. That is the real cost of this route: every kernel update rebuilds the module before the machine has WiFi.

## Kernel support is not monotonic

The compatibility list is longer than most, which is misleading on its own. Builds are confirmed on Linux 5.4.0-91-generic under Linux Mint 20.2, on 5.15.89 under Manjaro, on 5.19 under Ubuntu 22.4, on 6.1.0-9-amd64 under Debian Bookworm, self-compiled across 6.1 to 6.12 on Debian and Ubuntu 22.04, on 6.10.3 through 6.12.10 and on 6.13.0 under Debian Trixie, and on 6.17.0 through 7.2 under Cachy OS with a clang and lld toolchain.

Then the caveat that matters most, stated separately: the fixes for Linux v7.2 broke compatibility with v6.14 and older. The scope was large enough that conditional compilation was rejected, and users on 6.14 or older are pointed at an older commit, fc158d1f71b9e5dfcd1fccaf4d28725b65086e3b.

So the newest branch drops the oldest kernels rather than carrying them behind ifdefs. That is an unusual and honest choice, and it means you cannot just take whatever is on the branch; you pick a commit that matches your kernel.

There is also a known problem set: the maintainer has had issues with the driver on Debian Testing across several kernel versions, tracked in issue 280.

## Blacklist rtw88 first, or it wins the race

From Linux 5.18 some distributions ship experimental RTW88 USB support that includes RTW88x2BU. The README says to try it, and to fall back to this driver only if it does not work or is unstable.

The catch is loading order. The in-kernel module has a higher priority than an external one, so if you install this driver without doing anything about the conflict, the kernel can bind the dongle to rtw88 while your carefully installed module sits unused.

The diagnostic is lsmod. rtw88_core, rtw88_usb or any name starting with rtw88_ means the in-kernel driver has the device; 88x2bu means this repository does.

To take the device back, write a blacklist file and reboot:

```shell
echo "blacklist rtw88_8822bu" | sudo tee /etc/modprobe.d/rtw8822bu.conf
```

The README flags that this replaces any existing .conf file of that name. Note the reboot: module blacklists take effect at load, so you cannot undo it with a live unload.

## Two failure modes with documented fixes

The most common error is Unknown symbol in module, and the README gives two causes. The first is that cfg80211 is not loaded, fixed by loading it:

```shell
sudo modprobe cfg80211
```

The second is stale copies of the driver left in system directories. The reported fix removes them:

```shell
sudo dkms remove rtl88x2bu/5.8.7.4 --all
find /lib/modules -name cfg80211.ko -ls
sudo rm -f /lib/modules/*/updates/net/wireless/cfg80211.ko
```

Read that second block twice before running it. The last line deletes cfg80211.ko, which is not this project's file but a core kernel module, and the README itself calls this a drastic measure that may prevent other external WiFi adapters from working. Issue 249 has the fuller discussion.

The other blocker is Secure Boot, which refuses to load an unsigned module. mokutil --sb-state tells you whether it is active. If it is, your options are disabling it in BIOS or UEFI, or following the module signing procedure in issue 210. There is no third option, so this is the first thing to check before spending time on DKMS.

## How this compares to the alternatives

There are two real alternatives, and both are better if they work.

The first is the in-kernel rtw88 driver, which is what the maintainer moved to. The README describes support as experimental and potentially unstable, which is why this repository remains a fallback. The maintainer switched to a new dongle supported by the mainline kernel.

The second is different hardware. A USB adapter whose chipset already has stable in-kernel support removes the entire problem, at a purchase cost. For a desktop or a Pi that is being set up once and left alone, that is usually the shorter path than maintaining an out-of-tree module across kernel updates.

This repository earns its place in the narrower case: an adapter you already own, a kernel where rtw88 does not work, and a willingness to accept a frozen-system warning and a DKMS rebuild on every kernel bump.

## Conclusion

Use this driver only if lsmod shows rtw88 is unstable on your kernel and you have checked the issues the README points at. Before installing anything, run lsmod to see whether your distribution's in-kernel driver already handles the dongle, because it loads with higher priority and silently wins if you do not blacklist it. Then decide on Secure Boot, since an unsigned module will not load there, and pin a commit rather than tracking the branch, because the v7.2 fixes broke compatibility with v6.14 and older.

## FAQ

### How do I install the cilynx/rtl88x2bu driver?

For a quick test, build it with make and load it with insmod 88x2bu.ko, which does not persist. For a permanent install, use the deploy.sh script to register the module in DKMS for all kernels, a specific kernel, or the currently active one.

### Do I still need this driver now that the kernel supports rtw88x2bu?

Mainline support for rtw88x2bu was added around Linux 6.4, and from 5.18 some distributions ship experimental RTW88 USB support. The README says to try that first and only fall back to this repository if it is unstable. The maintainer themselves switched adapters and stopped using this driver as of Linux v6.16.

### How do I make rtw88 stop taking my USB adapter?

Check lsmod first. Then write a blacklist file with echo "blacklist rtw88_8822bu" | sudo tee /etc/modprobe.d/rtw8822bu.conf and reboot, because the in-kernel module has a higher loading priority than this external driver. Note that the command replaces any existing file with that name.

### Which Linux kernels does this rtl88x2bu build support?

Builds are confirmed from 5.4.0-91-generic through 7.2 across Mint, Manjaro, Ubuntu, Debian and Cachy OS. The v7.2 fixes broke compatibility with v6.14 and older, so on those kernels use an older commit such as fc158d1f71b9e5dfcd1fccaf4d28725b65086e3b.

### Why does my module fail with Unknown symbol in module?

The README names two likely causes: cfg80211 not being present in the kernel, fixed with sudo modprobe cfg80211, or old deployments of the driver still sitting in system directories. The removal commands it suggests delete cfg80211.ko, which the README itself calls a drastic measure.

## Sources

- [cilynx/rtl88x2bu on GitHub](https://github.com/cilynx/rtl88x2bu)
- [Issues](https://github.com/cilynx/rtl88x2bu/issues)
- [License: GPL-2.0](https://github.com/cilynx/rtl88x2bu/blob/5.8.7.1_35809.20191129_COEX20191120-7777/LICENSE)
- [Project website](http://www.wolfteck.com/2018/02/22/wsky_1200mbps_wireless_usb_wifi_adapter/)
- [README](https://github.com/cilynx/rtl88x2bu/blob/5.8.7.1_35809.20191129_COEX20191120-7777/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cilynx-rtl88x2bu