FAQ
Answers to commonly asked questions.
Vicinae is not packaged for my distribution. How should I install it?
Use the script to install the AppImage version, which should work fine on most systems. Don't forget to follow the quickstart guide for your environment once you are done installing.
Do not install the AppImage directly.
How to set a keyboard shortcut to open vicinae?
Vicinae doesn't support global shortcuts at the moment. You should use whatever is the preferred way to set global shortcuts for your environment. If there is a quickstart guide for your environment, this is probably explained there.
How to set a keyboard shortcut to open a specific command?
You can use deeplinks like so:
vicinae vicinae://launch/clipboard/history
How you bind this to a proper keyboard shortcut is different in every environment. Please refer to your desktop environment's documentation.
How to focus the app window instead of opening a new one?
You can change the default action that is executed for a given application from the settings window. Search for the Applications group and the option should be there.
How to use custom app launcher?
App launchers such as uwsm should be detected automatically. If that is not the case, you can specify a custom app launcher in the settings.
Some of my apps do not launch or are in a weird state
In 99% of cases this is an environment variable issue. See item below.
Vicinae doesn't pass X environment variable to my apps
Apps launched by vicinae inherit from the parent's environment without any modification. This probably means the environment variable that is missing is not properly injected in vicinae's environment when started. If using the systemd user service, you need to make sure the service is started with the right set of environment variables.
How to center the launcher window
If you have centering issues, you are probably on Gnome Wayland. The window should be explicitly centered using a tool such as Gnome Tweaks, or you can try the command below:
gsettings set org.gnome.mutter center-new-windows true
How to blur the launcher window
Blur needs to be supported by your compositor. In such case, you should have a way to add a rule that will apply blur to the vicinae window. The class or scope you need is vicinae.
This documentation contains quickstart guides for every major compositor. If blur can be done, be it natively or through some kind of extension, it is likely documented on these pages.
How to apply scaling
It is possible to enable window scaling for Vicinae by setting the QT_SCALE_FACTOR environment variable to an appropriate value:
QT_SCALE_FACTOR=1.5 vicinae server
It is not recommended to set this value globally as it will force scaling for every QT app. If you need desktop-wide scaling you probably want your Wayland compositor to handle this for you. Only use this if you only need the Vicinae window to scale up or down.
Scrolling is too fast/slow
You can override the QT_QUICK_FLICKABLE_WHEEL_DECELERATION environment variable and set it to a lower value (e.g 5000) to increase scrolling velocity.
QT_QUICK_FLICKABLE_WHEEL_DECELERATION=5000 vicinae server
Starting with v0.20.4, vicinae sets this value to a slightly lower default if the environment variable is not specified.
The vicinae window takes a long time to appear
Make sure you are not running the unextracted AppImage directly every time you want to call vicinae toggle. You should probably use the script to automatically extract the AppImage components.
How can I extend vicinae?
Three main ways, from least to most customizable:
How to set which terminal to use to launch terminal apps
Since version v0.20.8 vicinae implements the xdg-terminal-exec spec
so you should set your default terminal in ~/.config/xdg-terminals.list:
~/.config/xdg-terminals.list
kitty.desktop
The name of the entry must match the name of the desktop file. You can get it from the vicinae root search by using the "Copy App ID" action on an application entry.
How to force the vicinae window to show in fullscreen mode?
This usually happens on niri where the top layer shell layer is displayed behind fullscreen applications.
You can fix this by changing the layer shell layer to overlay in the configuration file (see vicinae config default)
vicinae uses top instead of overlay for various reasons. On some environments, some IME popups end up being shown behind the vicinae window if it's
set to overlay.
If this happens in an environment where layer shell is not a thing, then it's probably another issue.
Emojis do not load
This is a known issue when using the AppImage build (typically through the script installation). The TLDR is that QT does not recognize some fonts as emoji fonts. A fix is to try installing another emoji font and see if vicinae automatically picks it up. More complicated workarounds are also discussed in the previously mentionned issue.
How to deal with read-only configuration?
Vicinae expects the main settings.json file to be readable AND writable since it will write configuration changes to it when things are edited from the GUI.
For now, the only solution is to use the imports key in this file to import your read-only config from there.
See the configuration page.
How to clear navigation queue/state when the window is closed?
There is an option called pop_to_root_on_close you can configure that does exactly this.
How to disable the main window animation?
vicinae doesn't play any animation when showing or hiding its window, this is probably your compositor's doing.
Raycast-like native AI integration when?
This is currently in development.
vicinae's memory usage is too high
top/htop/btop is not a correct way to measure memory usage.
If you think you have found a real memory leak, try to confirm it using heaptrack or valgrind before reporting it as a bug.
When vicinae is run as a systemd service, some system monitors will include the memory consumption of apps launched with vicinae to its own independant memory usage.