Configuration

Where the config lives

  • Linux: ~/.config/nicotine/config.toml
  • Windows: %APPDATA%\nicotine\config.toml

It's created automatically on first run. Nicotine detects your display resolution (via xrandr on Linux, or the Win32 metrics on Windows, falling back to 1920x1080) and writes sensible defaults. Most options are also exposed in the config panel, where edits apply live and save automatically. You can edit the TOML by hand too.

  • Rewrite a fresh default file: nicotine init-config
  • Override the config directory: set the NICOTINE_CONFIG_DIR environment variable.

Display and window layout

  • display_width, display_height: your screen resolution (auto-detected).
  • panel_height: pixels of taskbar or panel height to leave room for. Default 0.
  • eve_width, eve_height: the size each EVE client is set to by nicotine stack. The defaults are about 54% of the display width, and the full display height.

Mouse cycling

  • enable_mouse_buttons: Linux default true, Windows default false.
  • forward_button, backward_button: button codes. On Linux (evdev), 276 is side button 9 and 275 is side button 8. On Windows, 2 is XBUTTON2 and 1 is XBUTTON1.
  • mouse_device_name: optional exact evdev device name (Linux). Highest priority.
  • mouse_device_path: optional device path such as /dev/input/event3 (Linux).

Device selection priority is name, then path, then autodetect.

Keyboard cycling

  • enable_keyboard_buttons: Linux default false, Windows default true.
  • forward_key, backward_key: on Linux (evdev), 15 is Tab. On Windows (virtual-key), 0x7A is F11 and 0x79 is F10.
  • modifier_key: optional modifier held with the backward key (for example, evdev 42 is Left Shift). Default unset.
  • keyboard_device_path: optional /dev/input/eventX (Linux) if autodetection grabs the wrong device.

Previews and display

  • show_previews: spawn preview windows. Default true. Set false for a headless, daemon-only setup.
  • display_mode: "Previews" or "List". Default "Previews".
  • preview_width, preview_height: preview size in pixels. Defaults are 320 by 180.
  • preview_opacity: 10 to 100 (Windows DWM previews). Default 100.
  • hide_active_preview: hide the preview of the client you're currently looking at. Default false.
  • constrain_aspect: lock previews to one aspect ratio and show a single size slider in the panel. Default false.
  • positions_locked: disable dragging on previews and the list window. Default false.
  • toggle_previews_key, toggle_previews_modifier: optional hotkey to toggle preview visibility. Default unbound.

Behavior

  • minimize_inactive: minimize each client as you cycle away from it (saves GPU and CPU). Default false.

Cycle order and per-character hotkeys

  • characters: an ordered list of character names (the text after EVE - in a client's title). Empty means the window-manager order is used. This defines the target numbers for nicotine switch N.
characters = ["Main Character", "Alt One", "Alt Two"]
  • [character_hotkeys."Name"]: a jump-to-character hotkey, with vk (a key code) and an optional modifier. Keyed by character name so bindings survive reorders and renames. The config panel writes these for you.
[character_hotkeys."Main Character"]
vk = 59          # F1 on Linux (evdev)
modifier = 42    # optional: Left Shift

Key codes

Linux uses evdev codes; Windows uses Win32 virtual-key codes, so the same physical key has a different number on each OS. The config panel captures keys for you, so you rarely need to look them up. A few common ones:

  • Linux (evdev): 15 is Tab, 42 is Left Shift.
  • Windows (VK): 0x79 is F10, 0x7A is F11.

Find Linux codes with sudo evtest: pick the device, press the key, and read the code.

Privacy and telemetry

Official release builds send a single anonymous launch ping when the daemon starts: a random per-install UUID plus the product name, version, and OS. That's all. No character names, hotkeys, IP logging, or behavioral data ever leave your machine. The ping is compiled in only for official releases, so building from source disables it entirely. Separately, the app checks the GitHub releases API on launch to show a "new version available" note in the panel.