Getting the Chipsailing CS9711 USB Fingerprint Reader Working on Linux

I bought one of those cheap USB fingerprint dongles — the kind that promise Windows Hello-style login for any PC. Plugged it into Linux, the little sensor lit up... and nothing else happened. No login prompt, no fprintd detection, nothing.

If you've landed here, you probably have the same chip: the Chipsailing CS9711 (USB ID 2541:0236). It's also the sensor built into the GPD Win Max 2. The bad news: stock libfprint — the library every Linux fingerprint stack is built on — has no driver for it. The good news: there's a working community driver, and I've packaged the entire setup into one command.

Why it doesn't "just work"

libfprint supports a long list of fingerprint readers, but the CS9711 isn't one of them. The chip is a Match-on-Host device: it does no processing on-device, no encryption — it just streams raw pixel data over USB and lets your PC do all the matching in software.

That means a driver has to be written specifically for it. archeYR maintains a fork of libfprint that adds exactly this (originally started by ddlsmurf). It works well — but installing it by hand is a chore:

1. Install a pile of build dependencies
2. Clone the fork
3. Patch the source
4. Compile libfprint from scratch with Meson/Ninja
5. Install it so it shadows your system copy
6. Wire up PAM for login, lock screen and sudo
7. Re-enroll and hope you got the PAM config right

I did this once manually, then a system update overwrote libfprint and silently broke it. So I automated the whole thing.

The installer

github.com/mmhfarooque/chipsailing-cs9711-fingerprint-linux

It auto-detects your distro, installs the right dependencies, clones and patches the driver, builds it, and configures PAM — so your fingerprint works for login, lock screen and sudo.

Step 0 — confirm you actually have this chip

bash
lsusb | grep 2541:0236

If that prints a line, you're in the right place. If it's blank, it's almost always the USB connection (see the gotchas below) — not a software problem.

▎ ⚠️ Only run this installer if lsusb shows 2541:0236. It builds a CS9711-only libfprint into /usr/local, which takes precedence over your system libfprint. If your machine has a different reader — most laptops use Goodix, Synaptics or ELAN — this will shadow the driver that reader needs and stop it working. The installer refuses to run unless it detects the CS9711, and ./uninstall.sh fully restores your stock libfprint.

Step 1 — install

git clone https://github.com/mmhfarooque/chipsailing-cs9711-fingerprint-linux.git
cd chipsailing-cs9711-fingerprint-linux
chmod +x install.sh setup-gui.sh
./install.sh

The script detects your distro and package manager, installs build dependencies, clones archeYR/libfprint-CS9711, applies the retry-delay patch (more on that below), builds and installs the patched libfprint, and configures PAM.

Step 2 — enroll your fingerprint

fprintd-enroll   # 15 touches for this sensor
fprintd-verify   # test it

That's it — lock your screen and tap the sensor.

Optional — the GUI manager

There's a GTK4 app if you'd rather not live in the terminal:

./setup-gui.sh
python3 cs9711-manager.py

It shows up as "CS9711" in your app launcher and lets you enroll/delete fingers, adjust the retry delay with a slider, tune PAM attempts/timeout, and rebuild or uninstall the driver.

Supported distros

Every one of these is container build-verified:

- Ubuntu / Kubuntu / Debian — Ubuntu 24.04 and 26.04 LTS, Debian 12 / 13 (apt)
- Linux Mint / Pop!_OS — Mint 21/22, Pop 22.04+ (apt)
- Fedora / RHEL — Fedora 44 (+ Rawhide), RHEL 9+ (dnf)
- Arch / Manjaro / EndeavourOS — rolling (pacman)
- openSUSE — Tumbleweed, Leap 15.5+ (zypper)

Pre-built .deb, RPM and Arch packages are on the Releases page if you'd rather not build.

Two gotchas that cost me hours

1. The USB connection is fussy. The CS9711 is power-sensitive. If lsusb shows nothing:

- It can fail behind an unpowered USB hub — the LED lights (it draws a little power) but the data device never enumerates. Use a powered hub or a direct port.
- If you plugged it into a keyboard's USB passthrough port, that only carries data when the keyboard itself is connected by cable. On Bluetooth or 2.4 GHz wireless, the passthrough port is dead — power only.

2. The default retry delay is too aggressive. Upstream retries a failed scan every 250 ms, which burns through all your attempts before you can even reposition your finger. The installer patches CS9711_DEFAULT_RESET_SLEEP from 250 to 1500 ms, which makes enrollment and verification far more forgiving. You can tune it further in the GUI (250–3000 ms).

Surviving system updates

When your package manager updates libfprint, it can overwrite the patched library and quietly break fingerprint auth. The fix is one command — it rebuilds from the local source without re-downloading anything:

./reinstall.sh

A note on security

This is fine for personal convenience, not for high-security setups. The CS9711 does no on-device matching and no encryption — fingerprint pixel data travels over the USB wire in plaintext, and all matching happens in software on the host. Treat it as a convenience unlock, not a hardened authentication device.

Credits

The actual driver and fingerprint matching are archeYR/libfprint-CS9711's work (originally by ddlsmurf) — all credit for the hard part goes there. My repo is the installer / setup layer on top: distro detection, packaging, PAM config, the retry-delay patch and the GUI. If you hit a matching issue (verify-no-match), that belongs upstream; for installer problems, open an issue on my repo.

- Installer: https://github.com/mmhfarooque/chipsailing-cs9711-fingerprint-linux
- Driver (upstream): https://github.com/archeYR/libfprint-CS9711

If this saved you the manual build, a ⭐ on the repo helps other CS9711 owners find it.