FAQ

Startup and Logs

Wox does not start. Where should I look first?

Open the core log:

Platform	Core log
Windows	%USERPROFILE%\.wox\log\wox.log
macOS	~/.wox/log/wox.log
Linux	~/.wox/log/wox.log

Start with the newest core log. If the UI opens but a plugin fails, check the plugin-specific log directory under the same Wox data folder.

How do I reset Wox?

Quit Wox, then remove the Wox data directory:

Platform	Data directory
Windows	%USERPROFILE%\.wox
macOS	~/.wox
Linux	~/.wox

This removes settings, installed plugins, plugin data, cache, and logs.

Search

Why is an app, file, or bookmark missing?

• App search may need a few seconds after installing a new app.
• File search only returns paths inside configured roots and readable by Wox.
• Browser bookmarks are read from supported browser profiles; browser sync can delay updates.
• Open the related plugin settings and confirm the plugin is enabled.

Why are results noisy?

Use an explicit keyword when you want one plugin. For example, f report searches files and cb report searches clipboard history. Global queries intentionally let multiple plugins answer.

Plugins

How do I install a downloaded .wox plugin?

Double-click the .wox file. Wox opens the plugin installer so you can confirm Install, Upgrade, Reinstall, or Downgrade. You can also select the file and invoke Wox, which uses the same installer.

On Windows and Linux, start Wox once after installing or updating so it can register the .wox file association.

Plugin installation failed. What should I check?

1. Confirm network access to the plugin store and release host.
2. Check whether the plugin requires Node.js or Python.
3. Open the Wox log directory and inspect the newest core and plugin-host logs.
4. Try wpm again after restarting Wox if a runtime host was just installed.

How do I update plugins?

Run wpm, select the plugin, and use the update action when one is available. You can also manage installed plugins from Plugin Manager settings.

File Search

Does Wox require Everything?

No. Wox has its own File plugin. On Windows it can enable Fast Indexing, which uses the same NTFS MFT and USN journal technique as Everything and can index whole volumes instead of walking every folder. macOS and Linux keep the regular root-based index.

Install Everything only if you also want to use Everything outside Wox. Fast Index setup is in File Search.

Why does file search ask for permissions on macOS?

macOS may block access to Desktop, Documents, Downloads, removable drives, or other protected locations. Grant Wox file access in System Settings -> Privacy & Security if search status or logs report permission errors.

Customization

How do I change the theme?

Run theme in Wox or open Settings -> Theme.

How do I change the hotkey?

Open Settings -> General and edit the hotkey field. Query hotkeys, tray queries, and the selection hotkey are on the same page. See Hotkeys.

Where did Explorer go?

File Explorer Search was renamed to Quick Jump. The trigger is now jump. Open Wox in File Explorer, Finder, or an open/save dialog and type to navigate. Details are in the Quick Jump guide.

How do I report a problem?

Query feedback to export diagnostics, review crash reports, clear logs, or open a GitHub issue. You can also query doctor for common setup checks.

Wayland

How do I use double-modifier hotkeys or CapsLock combos on Wayland?

On Wayland, Wox cannot globally intercept raw key events through the display server like it does on X11. To enable double-modifier hotkeys (such as ctrl+ctrl, shift+shift) and CapsLock-combo hotkeys (such as capslock+a), Wox reads keyboard events directly from the Linux evdev interface.

The permissions required depend on which hotkey styles you want to use:

Double-modifier hotkeys (e.g. ctrl+ctrl) — requires input group only

This grants read access to /dev/input/event* devices. Wox passively listens to keyboard events without grabbing or remapping the keyboard.

sudo usermod -aG input $USER

Log out and back in, then restart Wox.

CapsLock combo hotkeys (e.g. capslock+a) — input group required, uinput group recommended

CapsLock combos need the input group (evdev read access) to detect the combo. The uinput group is not required to register or trigger the hotkey — it is only used to restore CapsLock state and delete the stray combo character after the combo fires.

When CapsLock is used as a combo prefix, the system toggles the caps lock state because Wox cannot consume the raw event on Wayland. Wox undoes this toggle by injecting a CapsLock key event through a temporary uinput virtual keyboard. Without uinput, the hotkey still fires, but the caps lock LED may be left toggled and an extra character may be typed into the focused field.

To enable full CapsLock restoration, add yourself to the uinput group:

getent group uinput >/dev/null || sudo groupadd -r uinput
sudo usermod -aG input,uinput "$USER"

Then ensure /dev/uinput is group-writable. Many stock distros ship /dev/uinput as crw------- root:root, so group membership alone is not enough — you also need a udev rule:

echo 'KERNEL=="uinput", MODE="0660", GROUP="uinput"' | sudo tee /etc/udev/rules.d/80-uinput.rules
sudo udevadm control --reload-rules

Next, load the uinput kernel module and apply the device permissions. The presence of /dev/uinput alone does not mean the module is loaded:

sudo modprobe uinput
sudo udevadm trigger --action=change /sys/class/misc/uinput
sudo udevadm settle

Enable automatic loading at boot so the device remains available after a restart:

echo uinput | sudo tee /etc/modules-load.d/uinput.conf

Log out of your desktop session and back in to apply the new group membership, then verify:

id -nG
ls -l /dev/uinput
test -w /dev/uinput && echo "uinput writable"

id -nG should include input and uinput, the device should show crw-rw---- root uinput, and the last command should print uinput writable. Then restart Wox so it checks permissions again.

If a command fails:

• udevadm trigger reports No such device: run sudo modprobe uinput first. Check that /sys/class/misc/uinput exists before retrying the udev trigger command above. Creating a group or writing a rule does not load the module.
• modprobe reports Module uinput not found: check whether your current kernel provides the module. If you recently upgraded your kernel, reboot into the new kernel and retry.
• The device still belongs to root:root or lacks group write permission: check the saved udev rule, reload the rules, trigger the device event, and wait for udevadm settle to finish.
• Device permissions are correct but it is still not writable: run id -nG without a username to check the current session's groups. Opening a new terminal may not apply newly added groups; log out of the desktop and back in. Changing only device permissions does not require logging out, but Wox still needs to be restarted.

After setup, when CapsLock is pressed alone, it toggles caps lock normally. When CapsLock is used as a combo prefix, the system's caps lock toggle is automatically undone. Regular combination hotkeys (like ctrl+space) continue to work via the org.freedesktop.portal.GlobalShortcuts portal regardless of this setting.

Note: The system setup above requires sudo, but Wox itself runs as a regular user without an extra system daemon. For CapsLock combos, Wox reads evdev events passively and uses uinput to restore CapsLock state and delete the stray combo character. Without uinput, the hotkey still fires, but these recovery operations cannot complete.

How do I disable the Wox window animation on Wayland?

On Wayland, Wox renders its main window as a layer-shell surface (namespace gtk-layer-shell) on the overlay layer, not as a regular XDG toplevel. As a result, compositor animation rules that target application windows (by app id or window class) do not apply to Wox. To remove the open/close/resize transition animation, configure a layer rule that targets the gtk-layer-shell namespace.

Hyprland

Add a layer_rule to ~/.config/hypr/hyprland.conf (or the equivalent Lua config):

layerrule noanim, gtk-layer-shell

With the Lua config (hyprland.lua):

hl.layer_rule({
    name    = "wox-no-anim",
    match   = { namespace = "gtk-layer-shell" },
    no_anim = true,
})

Hyprland hot-reloads the config, so the change takes effect immediately. If Wox was already visible, toggle it once so the layer surface is recreated with the new rule.

Other compositors

Look for the equivalent layer-surface animation option in your compositor's documentation and target the gtk-layer-shell namespace. Wox does not control compositor-side animations from within the application.