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://extensions/vicinae/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.

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:

• dmenu mode
• script commands
• Typescript SDK

How to set which terminal to use to launch terminal apps

As there is no standardized way to set a default terminal emulator on a Linux desktop system, Vicinae honors the x-scheme-handler/terminal as some other launchers do.

To set your default terminal in this way, run:

xdg-mime default {desktop_file_name}.desktop x-scheme-handler/terminal

Where {desktop_file_name} is the name of the desktop file your application maps to.

For example, to set the default terminal to Alacritty:

xdg-mime default Alacritty.desktop x-scheme-handler/terminal

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.

Vicinae uses a lot of RAM

We are currently investigating excessive ram usage under specific situations. If you are seeing this on the latest version of vicinae please contribute to this issue.