Get Started


Packaging statusopen in new window



Onagre uses the pop-launcheropen in new window backend, you will need to install it according to your distribution (for arch users there is and AUR package). Alternatively we maintain a fork of pop-launcher called onagre-launcheropen in new window which is retro-compatible with the pop-launcher API while removing all PopOs specifics.

Plugin dependencies:

If you want to use the default calculator plugin you will need Qalculateopen in new window installed.

Building from source

If there is no Onagre package available for your linux distribution, you can build it from source with cargoopen in new window.

Latest stable release:

cargo install --git --tag 1.0.0

Latest upstream:

cargo install --git


1. Key bindings:

Arrow up/downChange selection
TabAutocomplete (in files mode)
EscQuit without launching
EnterLaunch selection

Onagre has three distinct modes: desktop entries, history and plugin. By default, it will start in the history mode which will display the most previously used desktop entries.

2. Plugins:

To use a plugin mode simply match its regex when typing your query.

For instance the file plugin will match ^(/|~).*, typing ~/ would enable the plugin and start the file navigation.

Plugin with no prefix are enabled by default, there entry will be mixed in the search results.


To get help about a plugin usage, just type "?" in Onagre to display the bundled help plugin.

Default plugins:

HistoryDisplay the most used desktop entries on start
PopLauncherSearch for desktop entries
PulseControl PulseAudio devices and volume
ScriptShell scripts as launcher options$HOME/.local/share/pop-launcher/scripts
TerminalTerminal or background commands'run '
WebWeb search'ddg ', 'g', ...$HOME/.local/share/pop-launcher/plugins/web/config.ron
FilesFind files using fd/find'find '
RecentRecently-opened document search'recent '
CalcCalculator with unit conversion (uses Qalculate! expressions)'= '
HelpList available pop-launcher modes'?'

Configuration and Theming

Onagre will look for a theme file in $XDG_CONFIG_DIR/onagre/theme.scss and will fall back to the default theme if none is found or if your theme contains syntax errors. To ensure your theme is correctly formatted run onagre from the terminal.

A .scss extension is used for configuration in order to get syntax highlighting, but only a small subset of scss is supported along with some custom properties prefixed with --.



.onagre {
  background: #d6d6d6;
  color: #000000;
  --icon-theme: "Papirus";
  --font-family: "DejaVuSans";
  --icon-size: 24;
  border-radius: 8%;
  border-color: #d6d6d6;
  border-width: 4px;
  padding: 5px;

  .container {
    .rows {
      --height: fill-portion 6;
      .row {
        --width: 392;

        .icon {
          padding-top: 4px;

        .category-icon {
          padding-left: 5px;
          --icon-size: 11;

        .title {
          font-size: 18px;

        .description {
          font-size: 12px;

      .row-selected {
        --width: 392;
        border-radius: 8%;
        background:  #c0c0c0;

        .icon {
          padding-top: 4px;

        .category-icon {
          padding-left: 5px;
          --icon-size: 11;

        .title {
          font-size: 20px;

        .description {
          font-size: 12px;

    .search {
      border-radius: 5%;
      background: #ffffff;
      --height: fill-portion 1;
      padding: 4px;
      .input {
        font-size: 20px;

    .scrollable {
      width: 2px;
      border-radius: 5%;
      background: #c0c0c0;
      .scroller {
        width: 4px;
        color: #a1a1a1;

See Theming -> Reference a detailed explanation of each available property.


Launch Onagre in a specific mode

You can prefill the input query using the --mode flag. This can be usefull to create a quick shortcut to a specific plugin.


onagre --mode "run "


Note that you need to provide the match query corresponding to the plugin configuration, for most plugin a whitespace is expected after the prefix keyword.


Depending on your desktop environment, screen size, DPI scale it could be usefull to resize onagre without editing your whole theme file. To do so use the --scale flag.

onagre --scale 1.2

Launch Onagre with an alternate theme

You can provide a custom location for Onagre theme:

onagre --theme "/home/me/my_custom_theme.scss"


pop-launcher plugins can reside in any of these directories:

  • User-local plugins: ~/.local/share/pop-launcher/plugins/{plugin}/
  • System-wide installation: /etc/pop-launcher/plugins/{plugin}/
  • Distribution packaging: /usr/lib/pop-launcher/plugins/{plugin}/

Every plugin directory is composed of an executable, meant to be called by pop-launcher backend, and a config file.

Configure existing plugin

Plugin configurations are written with the Rusty Object Notationopen in new window format (aka .ron).

For instance, you might customize the default find plugin by editing its config file (/usr/lib/pop-launcher/plugins/find/plugin.ron):

    // Title of the plugin displayed in the `help` plugin (`?`).
    name: "File search",
    // Description of the plugin displayed in the `help` plugin 
    description: "Syntax: find <filename>\nExample: find my-document.odt",
    query: (
        // Regex which will activate the plugin when matching search input.
        regex: "^(find )+",
        // Syntax example displayed in the `help` plugin.
        help: "find ",
        // Should this plugin mix it's results with the default desktop entry results. 
        isolate: true,
    // Path of the executable plugin, relative the the plugin directory (you probably don't want to edit this)
    bin: (path: "find"),
    // The icon displayed 
    icon: Name("system-file-manager")


Some plugins may require additional configuration files. For instance, the web plugin needs a config.ron file which allow you to configure custom shorthand for web search.


The following example add the qw shorthand to make a web search using Qwant search engine.

        matches: [ "qw" ],
        queries: [ (name: "Qwant", query: "" )]
    // ..

Install plugins

A variety of plugins are available for Onagre, offering extended functionality and customization options. You can explore both community maintained and official plugins on the awesome-pop-launcheropen in new window repository.

The installation process can vary but most of the time plugin maintainers provide a makefile or a justfile. It often boils down to copying the plugin executable and configuration to ~/.local/share/pop-launcher/plugins/{plugin}/.

Write your own plugin

Since pop-launcher works with JSON IPC over stdin and stdout pipes, you can write your plugin in any language.

To get started I would suggest looking at a simple example, such as the emoji pluginopen in new window written in Python by pbuiopen in new window.

If you want to build more complex stuff, you might want to take a look at this blog postopen in new window about writing a Stackoverflow plugin with Rust and the official onagre-launcher-toolkitopen in new window crate.

Please if you write your own plugin send a PR to awesome-pop-launcheropen in new window 😊 !