Chipsailing CS9711 Fingerprint Scanner — Linux Driver Installer

One-command installer for the Chipsailing CS9711 USB fingerprint scanner on Linux.

Stock libfprint does not support this chip. This project automates the entire setup: detecting your distro, installing dependencies, cloning the community driver, applying patches, building, installing, and configuring PAM — so your fingerprint works for login, lock screen, and sudo.

To check if you have this device:

lsusb | grep 2541:0236

This USB fingerprint sensor can be connected in two ways:

Option 1: Directly to the PC — Plug the scanner into any USB port on your computer (front panel, rear I/O, USB hub connected to the PC). This always works.

Option 2: Via a keyboard's USB passthrough port — Many mechanical keyboards (e.g. Royal Kludge RK84) have a USB-A port on the back for plugging in peripherals like this scanner. This only works if the keyboard is connected to the PC via USB cable. If the keyboard is connected via Bluetooth or 2.4GHz wireless, the keyboard's USB port is dead — the scanner may light up (it gets power) but the PC cannot see it (no data connection).

If lsusb | grep 2541:0236 shows nothing, check your USB connection first.

Power note: the CS9711 is power-sensitive. On some machines it enumerates fine in a rear/direct port but fails to be detected behind an unpowered USB hub — the LED lights (it draws a little power) but the PC never sees the data device. If lsusb doesn't list it through a hub, plug it directly into the PC or use a hub with its own power supply.

Every distro above is container build-verified (v2.0.0, 2026-05-30) — and bleeding-edge branches (Fedora Rawhide/F45, Debian sid, Ubuntu devel) build clean too. See COMPAT-CHECKLIST.md.

The .desktop file ships with a bundled SVG icon (referenced by absolute path), so the launcher entry renders correctly on every freedesktop-compliant DE — KDE Plasma, GNOME, Cinnamon (Mint), MATE, XFCE — without depending on the user's icon theme.

The installer auto-detects your distro and uses the right package manager.

⚠️ Only run this if you have the Chipsailing CS9711 (lsusb shows 2541:0236). The installer builds a CS9711-only libfprint into /usr/local, which takes precedence over your system libfprint. If your machine has a different fingerprint reader (most laptops — Goodix, Synaptics, ELAN, etc.), running this will shadow the driver that reader needs and stop it working. The installer refuses to proceed if the CS9711 isn't detected (override with CS9711_FORCE=1). ./uninstall.sh fully restores your stock libfprint.

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 installer will:

1. Detect your Linux distro and package manager
2. Install all build dependencies
3. Clone the archeYR/libfprint-CS9711 community driver
4. Apply the 1500ms retry delay patch (see below)
5. Build and install the patched libfprint
6. Configure PAM for fingerprint auth
7. Verify the scanner is detected

Then enroll your fingerprint:

fprintd-enroll          # 15 touches required
fprintd-verify          # test it

For the full experience — driver install, enrollment, and graphical manager:

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

# Step 1: Install driver (builds from source, configures PAM)
./install.sh

# Step 2: Enroll your fingerprint (15 touches)
fprintd-enroll
fprintd-verify

# Step 3: Install GUI manager (adds desktop shortcut)
./setup-gui.sh

# Step 4: Launch — or search "CS9711" in your app menu
python3 cs9711-manager.py

After setup, you can manage everything from the GUI — enrollment, retry delay, PAM settings, and driver maintenance.

Pre-built .deb packages are available in Releases, or build your own:

# Install build dependencies first
sudo apt install -y git meson ninja-build libfprint-2-dev libglib2.0-dev \
  libgusb-dev libpixman-1-dev libcairo2-dev libssl-dev libopencv-dev \
  doctest-dev gobject-introspection libgirepository1.0-dev fprintd libpam-fprintd

# Build the .deb
chmod +x packaging/deb/build-deb.sh
./packaging/deb/build-deb.sh

# Install it
sudo apt install ./cs9711-fingerprint_1.0.0_amd64.deb

Remove: sudo apt remove cs9711-fingerprint

# Build the RPM
chmod +x packaging/rpm/build-rpm.sh
./packaging/rpm/build-rpm.sh

# Install (Fedora/RHEL)
sudo dnf install ~/rpmbuild/RPMS/x86_64/cs9711-fingerprint-1.0.0-1.*.rpm

# Install (openSUSE)
sudo zypper install ~/rpmbuild/RPMS/x86_64/cs9711-fingerprint-1.0.0-1.*.rpm

cd packaging/arch
makepkg -si

Or use the helper script:

chmod +x packaging/arch/build-arch.sh
./packaging/arch/build-arch.sh

When your package manager updates libfprint, it may overwrite the patched library. Just run:

./reinstall.sh

This rebuilds from the existing local source — no re-download needed.

An update guard installed by install.sh watches for this automatically on apt, dnf and pacman systems and restores the patched library from a root-owned cache after each transaction.

The driver links against your distro's OpenCV. When a distro moves to a new OpenCV major version, the old libraries disappear and the driver can no longer load — fprintd reports no device while lsusb still shows the scanner. A cache restore cannot fix that (the cached copy was built against the same vanished libraries), so since v2.1.0:

• the guard detects the unloadable state, logs which libraries vanished, and the GUI's Driver status row names them and points at Maintenance → Rebuild Driver;
• the pacman/dnf hooks also fire on opencv transactions;
• the build resolves OpenCV as opencv4 → opencv5 → opencv → CMake's OpenCV, so the rebuild links against whatever your distro now ships.

One ./reinstall.sh (or the GUI Rebuild button) after the OpenCV upgrade puts everything back.

The upstream driver uses a 250ms delay between scan retries. This is too fast — the scanner burns through all retry attempts before you can reposition your finger.

This project patches CS9711_DEFAULT_RESET_SLEEP from 250 to 1500 (milliseconds), giving you a comfortable pause between scans.

The patch is in patches/cs9711-retry-delay-1500ms.patch.

Since v2.0.2, fingerprint is wired per service, not globally: each auth location (login screen, lock screen, sudo, polkit) gets the pam_fprintd line in its own PAM service file, tagged # cs9711-managed, and the GUI's four switches control them independently. Nothing is ever written to the shared common-auth/system-auth stack — which also means the tool works the same on Arch/CachyOS, where /etc/pam.d/common-auth does not exist at all (v2.1.0 fixed “Apply PAM Settings” accordingly, issue #1).

The line is only ever added as sufficient, with the full vendor stack preserved — password authentication can never be locked out, and every change is reversible (toggling off removes only the managed line/override).

Defaults:

• max-tries=7 — 7 fingerprint attempts before falling back to password (default is 1)
• timeout=30 — 30-second window for all attempts (default is 10)

“Apply PAM Settings” in the GUI re-stamps these options onto every location that is currently enabled.

• Lock screen unlock via fingerprint
• sudo authentication (fingerprint prompt before password)
• Login screen fingerprint auth
• All via libpam-fprintd

A GTK4 graphical manager is included for easy configuration:

./setup-gui.sh       # Install GUI dependencies + desktop shortcut
python3 cs9711-manager.py   # Launch

Or search "CS9711" or "Fingerprint Manager" in your app launcher after setup.

The GUI lets you:

• See at a glance whether fingerprint is working — scanner, driver and enrolled fingers in one status card
• Enroll/delete/verify fingerprints with visual progress
• Adjust retry delay (250ms–3000ms slider)
• Set PAM max attempts and timeout
• Turn fingerprint on or off independently for login, lock screen, sudo and polkit
• Rebuild/install/uninstall the driver
• Configure GNOME Keyring auto-unlock

Adaptive layout (since v2.2.0). The window lays out as two columns when there is room — workflow on the left, configuration and upkeep on the right — and collapses to a single vertical column below 880sp. That means it fits a wide desktop window on KDE Plasma, GNOME or Cinnamon, and equally a half-tiled or narrow/mobile-style window, without the endless scrolling of earlier versions. Styling uses no hardcoded colours, so it follows your theme in both light and dark.

If a system update strands the driver, the GUI says so directly — a banner across the top names the missing libraries and offers the rebuild, rather than leaving you to guess at a USB fault.

By default, GNOME Keyring requires your password to unlock (fingerprint login skips it). To set an empty keyring password so it auto-unlocks:

python3 helpers/set-empty-keyring-password.py

KWallet has the same problem in reverse: it is opened by a PAM module that captures your login password, so a fingerprint login short-circuits past it and the wallet — and everything that depends on it, such as browser saved passwords — stays locked. autokdewallet by @Himalian solves this properly with a TPM-secured wallet password that unlocks automatically at login, fingerprint included. Recommended from a working Fedora 44 KDE setup by @popy2k14 in #1.

.
├── install.sh                   # Universal installer (auto-detects distro)
├── reinstall.sh                 # Quick rebuild (after system updates)
├── uninstall.sh                 # Remove driver, restore stock libfprint
├── cs9711-manager.py            # GTK4 GUI manager
├── setup-gui.sh                 # GUI dependency installer + desktop shortcut
├── cs9711-manager.desktop       # Desktop entry template
├── patches/
│   └── cs9711-retry-delay-1500ms.patch
├── helpers/
│   └── set-empty-keyring-password.py
├── packaging/
│   ├── deb/
│   │   └── build-deb.sh        # Build .deb package
│   ├── rpm/
│   │   ├── build-rpm.sh        # Build RPM package
│   │   └── cs9711-fingerprint.spec
│   └── arch/
│       ├── build-arch.sh       # Build Arch package
│       └── PKGBUILD
├── VERSION                      # Current version number
├── CHANGELOG.md                 # Version history and release notes
├── LICENSE
└── README.md

fprintd-enroll                        # Enroll default finger (right index)
fprintd-enroll -f left-index-finger   # Enroll specific finger
fprintd-list $(whoami)                # List enrolled fingers
fprintd-verify                        # Test fingerprint
fprintd-delete $(whoami)              # Delete all enrolled fingerprints
lsusb | grep 2541                     # Check if scanner is connected

• Community driver: archeYR/libfprint-CS9711 (maintained fork, originally by ddlsmurf)

Installer vs driver: this repo is the installer / setup layer. The driver and its fingerprint matching (e.g. verify-no-match) live upstream in archeYR/libfprint-CS9711 — report matching/driver issues there. After installing, re-enroll for a clean template: fprintd-delete $(whoami) && fprintd-enroll.

• Retry delay patch & Linux integration: mmhfarooque

See CHANGELOG.md for full version history and release notes.

The libfprint driver is licensed under LGPL-2.1 (same as upstream libfprint). The installer scripts in this repo are MIT licensed.