OpenRazer: three layers between a Python script and a Razer keyboard

driver/, daemon/ and pylib/: three layers over one DBus interface

The project's opening sentence names its three parts: kernel drivers, DBus services and Python bindings to interact with the DBus interface. The tree gives each one its own directory:

driver/
daemon/
pylib/
examples/

The split is the design. A Python script never touches the hardware. It asks the user space service, and the service is what the kernel module answers. That is also why a fault can sit in one of three places: the module that did not load, the daemon that is not running, or the binding call in your own script. C is the repository's primary language, which fits the shape: the part that has to behave under a live USB bus is the driver, and everything above it is a program that talks to a socket.

The Makefile opens with a warning against running its install targets

OpenRazer's Makefile begins with a block of comment lines saying it is not supposed to be used outside of certain usecases like compiling the driver ("make driver") in this repository or installing the files as part of distribution packaging. It asks you never to run the install targets manually unless you really know what you are doing, and sends you to the wiki build instructions instead. The variables under that warning are what a packager overrides:

PREFIX?=/usr
UDEV_PREFIX?=$(PREFIX)
DESTDIR?=/
DKMS_NAME?=openrazer-driver
DKMS_VER?=3.12.1

Every one of them uses the ?= form, so a distribution recipe can set them from the environment or the command line without editing a tracked file. The consequence for an end user is blunt. Running make here by hand is not the supported path, and the Makefile points you to the build instructions in the wiki instead.

KERNELDIR and MODULEDIR decide where the module lands in your kernel tree

Two defaults decide how the driver is built and where it lands. KERNELDIR?=/lib/modules/$(shell uname -r)/build points the build at the headers of the kernel you are running right now, and DRIVERDIR?=$(shell pwd)/driver is the module source tree inside the checkout. Installation is pinned the same way, with MODULEDIR?=/lib/modules/$(shell uname -r)/kernel/drivers/hid, so the module is written into the HID driver directory of the running kernel rather than somewhere generic. The default target does nothing except call driver, and that target runs

$(MAKE) -C $(KERNELDIR) M=$(DRIVERDIR) modules

against your kernel build directory. Two consequences follow for anyone tracking this over time. A kernel upgrade changes uname -r, so the module has to be rebuilt or reinstalled to survive it.

DKMS_VER still reads 3.12.1 while the newest release tag is v3.12.4

The Makefile pins DKMS_VER to 3.12.1. The releases sit further ahead: v3.12.4 published 2026-07-04, v3.12.3 on 2026-05-21 and v3.12.2 on 2026-04-18. Nothing in the tree explains the gap and nothing forces the two to agree, because .bumpversion.cfg sits at the root as the project's version bump configuration while this Makefile default was left where it was. The mismatch matters in one direction only. The version string a packaging recipe compares against its rebuild rules can trail the release you have installed, which means a stale module is a failure mode nobody warns you about. If your distribution builds OpenRazer itself, you inherit whatever that distribution pins. If you compile from a checkout, compare the Makefile's DKMS_VER with the tag you downloaded before you file anything.

The device table follows master, not the packages your distribution ships

The device list is generated from the branch you happen to be reading, and the warning arrives before the first table: the list holds the latest devices supported on this branch, usually master, and these might not be released yet. The remedy is named in the same breath, check the stable branch for what should be available in the packages for your distribution. The tables are also explicit about what support means here. A device called fully feature supported has all available USB controllable functions for that product made available by the library, which is a much stronger claim than switching a light on. Entries pair a model name with a USB VID:PID: | Device | USB VID:PID | | --- | --- | | Razer BlackWidow Chroma | 1532:0203 | | Razer Huntsman Elite | 1532:0226 | | Razer Cynosa Chroma Pro | 1532:022C | | Razer Blade 15 Studio Edition (2019) | 1532:024D | The table continues well past these entries, and anything listed only on master has to be checked against the stable branch before you buy into it.

One vendor ID, 1532, and the lsusb line that identifies your hardware

Every Razer product shares USB VID 1532, so identifying hardware reduces to printing the pair that follows it:

lsusb | grep '1532:'

The output is one line per device, in the shape the README shows:

Bus 003 Device 005: ID 1532:0203 Razer USA, Ltd

Read that as an address rather than a description. 1532 is Razer, 0203 is the product, and 0203 in this sample is the BlackWidow Chroma from the table above. The pair is what a script needs and what a bug report should carry, and it is also how you check a device against the supported list before spending an evening on effects the hardware does not have. Notice what the line does not contain: no serial number, no firmware revision, no port path. Two identical keyboards produce two identical lines, so per device configuration cannot be keyed on this output alone.

Five distributions get official packages, seven get community builds

Packaging is split into two tiers. Official packages exist for Debian, Fedora, Mageia, openSUSE and Ubuntu, each with its own anchor on the project site: openrazer.github.io/#debian, then #fedora, #mageia, #opensuse and #ubuntu. Community supported packages are listed separately for Alpine Linux, Arch Linux, Gentoo, NixOS, Slackware, Solus and Void Linux. Nothing else separates the two groups. There is no version guarantee attached to the first list, no support policy, and no statement about which components each recipe carries. So the real difference is who maintains the packaging, and a reader on Arch or NixOS should expect their own distribution's notes to be the authority rather than a page here. The repository carries debian/ and install_files/ for exactly that work.

Eight example scripts and five front ends sit on the same DBus interface

The examples directory names eight scripts, and the filenames describe the range the Python layer is meant to reach: advanced_effect.py, basic_effect.py, change_on_screensaver.py, cpu_temperature.py, custom_starlight.py, custom_zones.py, dock_chroma_battery_daemon.py and list_devices.py. Read as a capability list, that covers lighting basics and advanced effects, per zone configuration, custom Starlight lighting, reacting to a screen saver event, reacting to CPU temperature, polling a dock's Chroma battery state from a small daemon, and enumerating what is attached right now. Each is a script to adapt rather than an API reference, and no invocation is given for any of them. Above that layer sit the applications the README calls complementary: Polychromatic, a graphical management tool and tray applet; RazerGenie, a Qt application for configuring devices; razerCommander, a simple GUI written in Gtk3; Snake, a stylised tool and tray applet written in Java; and Chroma Feedback, which turns a Razer keyboard, mouse or headphone into an extreme feedback device.

Editorial conclusion

OpenRazer earns its place on a Linux machine that owns Razer hardware and wants per zone lighting, reactions to screen saver events and device enumeration without writing HID code by hand. Prefer it when your distribution sits in the official tier, and accept it with eyes open when it is a community recipe, since the two tiers are documented as labels and nothing more. Do not expect a supported from source install: the Makefile explicitly tells you not to run its install targets, and the real steps live in the wiki. Before you start, confirm which tier your distribution falls into, check whether your product ID is on the stable branch rather than only on master, and read the Troubleshooting page about secure boot if your machine enforces it. The last push to master was 2026-10-05 and the newest release tag is v3.12.4.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. openrazer/openrazer on GitHub
3. Project website
4. README
5. Releases