A lightweight tool to map and manage macros for Razer Naga and other devices on Linux.
✅ Works on Wayland and X11
✅ Supports Ubuntu, its flavors, and most other distros (with dependencies installed)
✅ Includes per-app auto profiles
Want support for another device? Just add the files and configure with naga vendor or contact me.
Run this one-liner to install with git :
{ command -v git >/dev/null 2>&1 || sudo apt install git -y; } && git clone https://github.com/lostallmymoney/Razer_Mouse_Linux.git ~/Razer_Mouse_Linux-master && cd ~/Razer_Mouse_Linux-master && sh install.sh
Or without git :
{ { command -v unzip && command -v wget; } >/dev/null 2>&1 || sudo apt install unzip wget -y; } && cd ~ && rm -f ~/Razer_Mouse_Linux.zip && wget https://codeload.github.com/lostallmymoney/Razer_Mouse_Linux/zip/refs/heads/master -O ~/Razer_Mouse_Linux.zip && unzip -o ~/Razer_Mouse_Linux.zip -d ~ && rm -f ~/Razer_Mouse_Linux.zip && cd ~/Razer_Mouse_Linux-master && sh install.sh
Run this to update (git install overwrite) :
{ command -v git >/dev/null 2>&1 || sudo apt install git -y; } && cd ~ && rm -rf ~/Razer_Mouse_Linux-master && git clone https://github.com/lostallmymoney/Razer_Mouse_Linux.git ~/Razer_Mouse_Linux-master && cd ~/Razer_Mouse_Linux-master && sh install.sh
Or, clone the repo and run:
sh install.shThen configure:
naga editIf wayland or X11 aren't properly detected or if you want to manually install them you can :
sh install.sh X11sh install.sh waylandThe Naga service uses a udev rule based on USB vendor ID. By default it is set to Razer (1532), but it can be changed for other devices using :
naga vendorTested & confirmed 99% compatible with:
- Naga Epic (pre-2014) - (thanks unknown early contributor)
- Naga (RZ01-0028) – (thanks khornem)
- Naga Chroma – (thanks felipeacsi)
- Naga Molten – (thanks noobxgockel)
- Naga 2012 (RZ01-0058) – (thanks violet-fish, brianfreytag)
- Naga Chroma – (thanks ipsod)
- Naga Trinity – (thanks haringsrob, ws141)
- Naga Pro Wireless – (thanks Stibax)
- Naga V2 – (thanks ibarrick)
- Naga Left-Handed – (thanks Izaya-San)
- Naga X – (thanks bgrabow)
- Naga HyperSpeed – (thanks khornem) (Bluetooth files still unknown, USB working)
- Naga 2014 –
- Naga Epic Chroma –
On theses systems : Ubuntu, Manjaro, Linux Mint, CentOS, ArchLinux, and more..
Disclaimer: Make sure to have at least 2MB of free RAM to run this daemon seamlessly.
| Command | Description |
|---|---|
naga start |
Starts the daemon |
naga stop |
Stops the daemon |
naga kill |
Kills the daemon |
naga enable |
Enables the daemon |
naga disable |
Disables the daemon |
naga edit ($EDITOR) |
Edits config and monitors saves, restarting the daemon after each change. Examples: naga edit or naga edit vim |
naga settings ($EDITOR) |
Edits Naga settings and monitors saves, restarting the daemon after each change. Examples: naga settings or naga settings vim |
naga debug |
Show logs (realtime, pass args to override journalctl) |
naga fix |
Restart USB services |
naga uninstall |
Remove the tool completely |
naga |
Show help |
naga serviceHelper ($CONFIG) |
Manual config switching (requires udev rule + disabled service) |
Easily map keys with:
naga editsudo apt install g++ nano pkexec procps wget gnome-shell-extension-prefs golang-gosudo apt install libx11-dev xdotool xinput g++ libxtst-dev libxmu-dev nano pkexec procpsIf something fails to compile on your distro → install equivalents of these packages.
The configuration file is stored in ~/.naga/keyMapWayland.txt or ~/.naga/keyMapX11.txt.
Naga settings are stored in ~/.naga/nagaSettings.txt.
Notifications use notify-send by default:
nagaNotifyCommand=notify-send -a Naga "$notifyOptions" "$notifyStatus: $profileName"
Set notification_enabled=false to disable notifications, set notification_disappear=false to disable transient notifications, change notification_timeout to control the timeout in milliseconds, set notification_icon to an icon file path, or set notification_icon_base64 to base64-encoded icon data. notification_icon_gzip_base64 is populated during installation from the razer_mouse_linux_default_icon asset in src/nagaAssets.txt. The configured path takes precedence, followed by the base64 setting and then the gzip-base64 setting. Encoded icons are written to ~/.naga/naga-notification-icon.svg at daemon startup. The icon is omitted when all icon settings are empty.
nagaNotifyCommand accepts any executable followed by its arguments. For example:
nagaNotifyCommand=anyOtherNotificationUtility --option 1 --option 2 "$notifyStatus: $profileName"
The supported substitutions are $notifyOptions, $notifyStatus (Profile or Unlocked), and $profileName. $notifyOptions expands to the configured timeout, dismiss behavior, and optional icon arguments. To keep a settings variable literal, escape its dollar sign, for example \$profileName.
Basic syntax:
config=<configName>
<keyNumber> - <option>=<command>
<keyNumber> - <option>=<command>
<keyNumber> - <option>=<command>
<keyNumber>: 1–14 (12 keypad buttons + 2 top buttons)<option>: action type (see full list below)<command>: string, key, or shell command
Profiles can be selected automatically from the focused window class. Add one or more window matches at the top level of a profile, before its indented key bindings:
# Exact match: case-sensitive and matches the whole window class
config=TerminalProfile
configWindow=org.gnome.Ptyxis
1 - key=Ctrl+Alt+T
# Wildcard matches are case-insensitive; '*' matches any number of characters
# and '?' matches exactly one character.
configWindowExpr=Minecraft*
8 - chmap=MinecraftProfile
config=MinecraftProfile
configWindowExpr=Minecraft*
1 - key=1
2 - key=2
8 - unlockChmap=Minecraft*
# Multiple matches can share a profile.
config=MusicProfile
configWindowExpr=*spotify*
configWindowExpr=*ytmusic*
1 - key=XF86AudioPlay
2 - key=XF86AudioNextThe active window class is checked when focus changes. configWindow= uses an
exact match; configWindowExpr= uses the wildcard rules above. An automatic
window entry can switch to a separate profile with chmap=<profileName>.
unlockChmap=<same-window-match> must be used on the origin profile to
return control to automatic matching. Use the full wildcard expression when
applicable.
On Wayland, window classes come from the Focus Class Fetcher GNOME extension, installed automatically (optional — per-window profiles are skipped if it's missing).
Looking for higher-level building blocks? Check out Functions, Loops & Contexts.
chmap– Switch to another configchmapOnRelease– Switch config on key releaseunlockChmap– Unlocks auto window-based configssleep/sleepOnRelease– Put system to sleeprandomSleep/randomSleepOnRelease– Sleep for a random duration (0 to N ms, where N is the argument)string/stringOnRelease– Type a literal stringkey– Press + release a keykeyPressOnPress– Hold key on button presskeyReleaseOnRelease– Release key on button releasekeyPressOnRelease– Hold key on button releasekeyReleaseOnPress– Release key on button presskeyClick– Press key once on presskeyClickOnRelease– Press key once on releaserun– Run a shell command asynchronously *see multilinerun2– Run a shell command synchronouslyrunOnRelease– Run command on release asynchronouslyrunOnRelease2– Run command on release synchronouslyuserRun– Run a shell command asynchronously as the useruserRun2– Run a shell command synchronously as the useruserRunOnRelease– Run a shell command asynchronously as the user on releaseuserRun2OnRelease– Run a shell command synchronously as the user on releaserunAndWrite– Run a command and write its output live to screenrunAndWrite2– Same as above, synchronousrunAndWriteOnRelease– Run a command and write its output live to screen on releaserunAndWriteOnRelease2– Same as above, synchronousfunction/functionOnRelease– Call a predefined functionloop– Start/stop a predefined loop inline (synchronous)loop2– Start a predefined loop in a detached thread (asynchronous)- Wayland-only
dotool/dotoolOnRelease– Send the full command string directly to the nagaDotool pipe see DoTool man page - Wayland-only
click– Press mouse click (left | center | right) - Wayland-only
clickOnRelease– Press mouse click (left | center | right) on release - X11-only
xdotoolType/xdotoolTypeRelease– Type a string via xdotool (fallback) - X11-only
specialKey– Press + release a special key - X11-only
setWorkspace– Switch workspace (via xdotool) - X11-only
mousePosition– Move mouse to<x> <y>position
Special single-character press/release actions (faster than xdotool, but no ctrl/media support yet):
- X11-only
specialPressOnPress - X11-only
specialPressOnRelease - X11-only
specialReleaseOnPress - X11-only
specialReleaseOnRelease
👉 For valid Wayland key names, see Wayland input_event_codes (remove KEY_ prefix).
👉 For valid X11 key names, see X11 keysym list (remove XK_ prefix).
If nothing is provided after =, the run commands switch into multi-lines mode. All indented lines that follow are grouped into a single script and executed together as one shell command, allowing full multi-lines shell syntax.
For Bash-specific features, use bash -c "..." since run executes using /bin/sh by default.
# Default config
config=defaultConfig
1 - key=XF86AudioPlay
3 - chmap=WoWConfig
4 - run=notify-send 'Button #4' 'Pressed'
# Custom WoW profile
config=WoWConfig
1 - run=sh ~/hacks.sh
2 - chmap=defaultConfig📌 Notes:
- If
~/.naga/keyMap*.txtis missing, the daemon won’t start (installer copies an example). - Multiple actions per key are allowed; they run sequentially or async depending on choice.
- Use
naga editornaga settingsto edit protected files. The command keeps monitoring the file while the editor is open and restarts the daemon after each detected save.
- Uses systemd for service management
- Adds persistence lines to
~/.profileand sudoers
These advanced building blocks let you share logic, create repeatable sequences, and keep large configs tidy.
- Define reusable combos once with
function=<name>. - Only press-phase actions are recorded; call them from a config using
function=<name>orfunctionRelease=<name>. - Functions can call other functions (nesting is allowed) for modular setups.
Compatible press-phase actions (usable in both functions and loops):
function(invoke another function)loop/loop2(nested loops with the arguments=start,=stop, or negative numbers for fixed repeated loops=-3.)chmapsleeprunrun2userRunuserRun2runandwriterunandwrite2unlockChmapkeypressOnPresskeyReleaseOnPresskeyClickstring- Wayland-only
click - X11-only
specialPressOnPress - X11-only
specialReleaseOnPress
Example:
function=prepStandup
run=notify-send "Stand-up" "Time to share updates"
sleep=150
key=Super+N
sleep=120
string=Standup notes ready!
function=toggleMic
key=XF86AudioMicMute
# Press to prep workspace, release to mute/unmute the mic
4 - function=prepStandup
4 - functionOnRelease=toggleMic- Wrap repeating sequences with
loop=<name>. - Bind them in configs via
loop=<name>(runs inline) orloop2=<name>(runs in a detached thread). -
- Optional arguments let you control behavior:
loop=myLoop=start(default) begins the loop.loop=myLoop=stopstops it manually (auto-added on key release unless you pass a negative count).loop=myLoop=5runs exactly 5 cycles;loop=myLoop=-3runs 3 cycles without waiting for stop.loop=myLoop=startOnReleasebegins loop on key release.loop=myLoop=stopOnReleasestops loop on key release.loop=myLoop=toggletoggles the loop on/off with each press.loop=myLoop=toggleOnReleasetoggles the loop on/off with each release.
- Optional arguments let you control behavior:
- Only one instance per loop: Each loop can have only one running instance at a time. Starting a loop while it's already running will stop the old instance and start a new one.
- Loops can include other loops: Inside a
loop=orloop2=definition, you can call other loops usingloop=anotherLoop=start,loop=anotherLoop=stop, or negative numbers likeloop=anotherLoop=-5(for fixed-count loops without auto-stop). You can also have a plain loop or loop2 inside a loop or loop2, all nested loops will stop with their mother loop. - All press-phase actions compatible with functions are also compatible with loops, including nested
loop/loop2calls.
Example:
loop=burstRotation
key=Ctrl+1
sleep=150
key=Ctrl+2
loop=autoFarm
loop=burstRotation=-2
sleep=500
3 - loop=burstRotation # hold to spam the rotation
4 - loop2=burstRotation=5 # run 5 cycles in background
5 - loop=autoFarm # nested loop example- Use
context=<name>to store shared lines (they can reference other contexts). - Inside a config, drop
context=<name>and every line stored in that context is injected in place. - Great for repeating key layouts across multiple profiles or layering optional behaviors.
Example:
context=mediaOverlay
1 - key=XF86AudioPlay
2 - key=XF86AudioNext
context=focusShortcuts
context=mediaOverlay
3 - key=Super+Left
4 - key=Super+Right
config=focusMode
context=focusShortcuts
5 - run=notify-send "Focus mode engaged"naga uninstall