Skip to content
JSa25Public

About

Lightweight mouse app for Razer mice on Windows without needing Synapse: button remapping, per-game profiles, DPI, polling rate, power saving and RGB lighting. Unofficial; not affiliated with Razer.

Topics

Resources

Stars

24 stars

Watchers

1 watching

Forks

Repository files navigation

FreeRazer

A small Windows app for remapping the buttons of Razer mice without Razer Synapse. Make profiles, link them to games, and the right one goes onto the mouse when a game is in focus. The mouse keeps the last profile in its own memory, so nothing has to run for it to work.

Unofficial. This project is not made, endorsed or supported by Razer Inc. "Razer" and mouse model names are trademarks of their owners and are used here only to say which hardware this works with. No Razer code, artwork or logo is included.

Supported mice

Supported mice (118)

Names and USB product IDs from OpenRazer.

Mouse USB product ID
Abyssus 1800 0x0020
Abyssus 2000 0x005E
Abyssus Elite (D.Va Edition) 0x006A
Abyssus Essential 0x006B
Abyssus V2 0x005B
Abyssus 0x0042
Atheris (Receiver) 0x0062
Basilisk Essential 0x0065
Basilisk Mobile (Receiver) 0x00D4
Basilisk Mobile (Wired) 0x00D3
Basilisk Ultimate (Receiver) 0x0088
Basilisk Ultimate 0x0086
Basilisk V2 0x0085
Basilisk V3 35K 0x00CB
Basilisk V3 Pro (Wired) 0x00AA
Basilisk V3 Pro (Wireless) 0x00AB
Basilisk V3 Pro 35K (Wired) 0x00CC
Basilisk V3 Pro 35K (Wireless) 0x00CD
Basilisk V3 Pro 35K Phantom Green Edition (Wired) 0x00D6
Basilisk V3 Pro 35K Phantom Green Edition (Wireless) 0x00D7
Basilisk V3 X HyperSpeed 0x00B9
Basilisk V3 0x0099
Basilisk X HyperSpeed 0x0083
Basilisk 0x0064
Cobra HyperSpeed Receiver 0x00DB
Cobra HyperSpeed 0x00DA
Cobra Pro (Wired) 0x00AF
Cobra Pro (Wireless) 0x00B0
Cobra 0x00A3
DeathAdder 1800 0x0038
DeathAdder 2000 0x004F
DeathAdder 2013 0x0037
DeathAdder 3.5G Black 0x0029
DeathAdder 3.5G 0x0016
DeathAdder 3500 0x0054
DeathAdder Chroma 0x0043
DeathAdder Elite 0x005C
DeathAdder Essential (2021) 0x0098
DeathAdder Essential (White Edition) 0x0071
DeathAdder Essential 0x006E
DeathAdder V2 Lite 0x00A1
DeathAdder V2 Mini 0x008C
DeathAdder V2 Pro (Wired) 0x007C
DeathAdder V2 Pro (Wireless) 0x007D
DeathAdder V2 X HyperSpeed 0x009C
DeathAdder V2 0x0084
DeathAdder V3 HyperSpeed (Wired) 0x00C4
DeathAdder V3 HyperSpeed (Wireless) 0x00C5
DeathAdder V3 Pro (Wired) 0x00B6
DeathAdder V3 Pro (Wired) 0x00C2
DeathAdder V3 Pro (Wireless) 0x00B7
DeathAdder V3 Pro (Wireless) 0x00C3
DeathAdder V3 0x00B2
DeathAdder V4 Pro (Wired) 0x00BE
DeathAdder V4 Pro (Wireless) 0x00BF
Diamondback Chroma 0x004C
HyperPolling Wireless Dongle 0x00B3
Imperator 2012 0x002F
Lancehead (Wired) 0x0059
Lancehead (Wireless) 0x005A
Lancehead Tournament Edition 0x0060
Lancehead Wireless (Receiver) 0x006F
Lancehead Wireless (Wired) 0x0070
Mamba 2012 (Wired) 0x0024
Mamba 2012 (Wireless) 0x0025
Mamba Chroma (Wired) 0x0044
Mamba Chroma (Wireless) 0x0045
Mamba Elite 0x006C
Mamba Tournament Edition 0x0046
Mamba Wireless (Receiver) 0x0072
Mamba Wireless (Wired) 0x0073
Naga 2012 0x002E
Naga 2014 0x0040
Naga Chroma 0x0053
Naga Epic Chroma (Wired) 0x003E
Naga Epic Chroma (Wireless) 0x003F
Naga Epic 0x001F
Naga Hex (Red) 0x0036
Naga Hex V2 0x0050
Naga Hex 0x0041
Naga Left Handed Edition 2020 0x008D
Naga Pro (Wired) 0x008F
Naga Pro (Wireless) 0x0090
Naga Trinity 0x0067
Naga V2 HyperSpeed (Receiver) 0x00B4
Naga V2 Pro (Wired) 0x00A7
Naga V2 Pro (Wireless) 0x00A8
Naga X 0x0096
Naga 0x0015
Orochi (Wired) 0x0048
Orochi 2011 0x0013
Orochi 2013 0x0039
Orochi V2 (Bluetooth) 0x0095
Orochi V2 (Receiver) 0x0094
Ouroboros 0x0032
Pro Click (Receiver) 0x0077
Pro Click (Wired) 0x0080
Pro Click Mini (Receiver) 0x009A
Pro Click V2 (Wired) 0x00D0
Pro Click V2 (Wireless) 0x00D1
Pro Click V2 Vertical Edition (Wired) 0x00C7
Pro Click V2 Vertical Edition (Wireless) 0x00C8
Taipan 0x0034
Viper 8KHz 0x0091
Viper Mini SE (Wired) 0x009E
Viper Mini SE (Wireless) 0x009F
Viper Mini 0x008A
Viper Ultimate (Wired) 0x007A
Viper Ultimate (Wireless) 0x007B
Viper V2 Pro (Wired) 0x00A5
Viper V2 Pro (Wireless) 0x00A6
Viper V3 HyperSpeed 0x00B8
Viper V3 Pro (Wired) 0x00C0
Viper V3 Pro (Wireless) 0x00C1
Viper V3 Pro SE (Wired) 0x00DE
Viper V3 Pro SE (Wireless) 0x00DF
Viper V4 Pro 0x00E6
Viper 0x0078

Mouse not listed? Here's how to get it added.

The app only reads and sets button bindings, DPI, polling rate, power saving (sleep timer, low power level) and lighting; it never touches firmware. What it may change on each mouse comes from its mouse database, see How mice are supported.

Features

  • Remap any button except left click (so you can't lock yourself out): other mouse buttons, keys, key combos such as Ctrl + S, or DPI cycle.
  • Record a key or combo by pressing it.
  • Profiles per game: link a game's .exe and turn on auto-switch.
  • Sensitivity (DPI), polling rate, sleep timer and low power mode.
  • Lighting on mice that support it: off, static, breathing or rainbow, any color (picker with hex and RGB) and brightness.
  • More than one Razer mouse plugged in? Pick which one to set up from the header.
  • Lives in the system tray; can start with Windows.
  • Problems are written to %APPDATA%\FreeRazer\error.log (Settings > Open error log), and the window says when one happens.
  • Profiles are stored in %APPDATA%\FreeRazer\profiles.json. A profiles.json from an older version next to the app is copied there on first start (the old file is left as a backup).

Works alongside Razer Synapse, for example if you keep Synapse for a Razer keyboard. Synapse leaves the mouse alone in the background, but opening the mouse in Synapse's window writes Synapse's own settings to it; FreeRazer notices within 30 seconds and puts yours back.

Running from source

Needs Windows and Python 3.13.

py -3.13 -m pip install hidapi pystray pillow
pyw -3.13 freerazer.pyw

Command line (py -3.13 razer_switch.py ...):

Command What it does
(none) / list list profiles
apply NAME put a profile on the mouse
show print what the mouse has on each button
auto switch profiles by focused program
probe read-only report for adding a new mouse
test offline self-check (no mouse needed)

Building, installing and releasing

You need Python 3.13 with hidapi pystray pillow pyinstaller, and Inno Setup 6:

py -3.13 -m pip install hidapi pystray pillow pyinstaller
winget install JRSoftware.InnoSetup

Build the app, its installer and the installer's checksum (all land in dist\):

powershell -ExecutionPolicy Bypass -File build.ps1

build.ps1 reads the version from APP_VERSION in freerazer.pyw, runs the self-check, builds FreeRazer.exe with PyInstaller and then FreeRazerSetup.exe with Inno Setup. The exe leaves out modules the app never loads, which keeps it around 12 MB instead of 31 MB. Each excluded module was checked against a run that used every feature. Do not exclude bz2, lzma, decimal, PIL.ImageFont or PIL._imagingft: the tray icon and the drawing code need them.

Installing: run FreeRazerSetup.exe. It installs for the current user only (no admin) into %LOCALAPPDATA%\Programs\FreeRazer, adds a Start menu entry so Windows search finds it, and lists it under Settings > Apps > Installed apps, where Uninstall removes it again. Running a newer Setup upgrades in place.

Releasing an update: bump APP_VERSION and push, then run the Release workflow from the Actions tab with the release notes. It builds the installer on GitHub from the code in the repo and publishes it.

Installed copies check GitHub Releases at most once a day (or when you click Check for updates in Settings or the tray menu) and ask before updating; the pop-up never appears while a linked game is in focus. On Update now they download FreeRazerSetup.exe, check it against the published .sha256, and install it silently.

How mice are supported

Settings (DPI, polling rate, power saving, lighting) come from the mouse database, devices.json, which tools/gen_devices.py builds from OpenRazer's driver. A mouse gets a setting only where OpenRazer's driver sends it the same command FreeRazer sends, with the transaction ID the driver uses for it. Settings > Update mouse database downloads the newest devices.json from this repo, so new mice work without a new version. The file is checked in full before it is used.

Buttons aren't in OpenRazer, so they're checked on the mouse itself. When a mouse connects, FreeRazer reads its usual buttons (right click, scroll click and up/down, the two side buttons). Each one that answers with its own factory action is a real button and can be remapped from then on. One that answers with anything else (already remapped in Synapse, say) stays as it is; resetting the mouse to factory settings in Synapse unlocks it. Button IDs that aren't real buttons answer with leftover memory, which never spells out a factory action, so nothing is ever written to them.

Mouse not listed?

For a Razer mouse that isn't in the supported mice list. The list comes from OpenRazer, so once OpenRazer supports a new mouse it reaches FreeRazer by itself within a week. To get one added sooner, or one OpenRazer doesn't have, you need the mouse and a few minutes. Nothing is written to the mouse.

  1. Close Razer Synapse.
  2. In FreeRazer, go to Settings > Mouse database and press Copy mouse report. It takes about 10 seconds. (From source: py -3.13 razer_switch.py probe.)
  3. Open an issue titled with your mouse's name (for example "Add Basilisk V3 Pro") and paste the whole report. Also list the physical buttons your mouse has (for example: 2 side buttons, DPI button on top) and, if you know them, what each does at factory settings.

The same works for a mouse that is listed but is missing buttons, such as a Naga's side grid.

Learn buttons (Settings > Mouse database, or Ctrl+K) adds missing buttons yourself, no issue needed. Reset the mouse to factory settings in Synapse, close Synapse, then press each button. FreeRazer reads what every button ID does, and each press shows which ID did it. Add new buttons puts them under the picture as More buttons, where they can be changed like any other. Send to GitHub opens a filled-in issue in your browser; press Submit and the buttons can be added for everyone with that mouse. Buttons that only change DPI or the profile on the mouse send nothing to Windows, so they can't be found this way.

What the report contains: the USB product IDs of your Razer devices, which transaction ID the mouse answers to, and what the mouse returns for button IDs 1 to 127.

From that, a new entry goes into DEVICES. The same report also adds buttons beyond the usual ones (a Naga's side grid, say); they show under the picture as More buttons. A hand-made entry looks like this:

{'name': 'Viper V4 Pro', 'pids': (0x00E6,), 'txn': 0x1F, 'verified': True, 'drawing': 'viper-v4-pro',
 'features': {'battery', 'dpi', 'stages', 'poll', 'sleep', 'low_power'},
 'buttons': {1: ('Left Click', 'mouse:left'), 2: ('Right Click', 'mouse:right'), ...}}

To rebuild the database from a newer OpenRazer: py -3.13 tools/gen_devices.py razermouse_driver.c razermouse_driver.h mouse.py (the first two from openrazer/driver/, the third from openrazer/daemon/openrazer_daemon/hardware/), then commit devices.json.

Mice without their own drawing get a generic one ('drawing': 'generic').

Credits

FreeRazer stands on the work of the OpenRazer project, the open-source Razer driver for Linux. The supported mice list, the mouse database (devices.json) and the lighting commands all come from what OpenRazer's contributors worked out. FreeRazer contains none of OpenRazer's code: tools/gen_devices.py reads their driver source and keeps only the facts (device IDs, names, which command each mouse takes). OpenRazer is licensed GPL-2.0. If you use Linux, use OpenRazer.

Built with help from AI (Claude by Anthropic).

FreeRazer is not affiliated with or endorsed by Razer or the OpenRazer project.

Licence

MIT, see LICENSE.

About

Lightweight mouse app for Razer mice on Windows without needing Synapse: button remapping, per-game profiles, DPI, polling rate, power saving and RGB lighting. Unofficial; not affiliated with Razer.

Topics

Resources

Stars

24 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages