4. First steps

The first thing to know about Keypirinha is that you can use almost all of its features by using your keyboard only. Keep that in mind!

4.1. Start Keypirinha

Keypirinha is a resident application, it directly goes to background when it is started.

You can check application is running by looking for its icon in the system tray’s notification area. It is located next to the system clock on your desktop, usually in the lower-right corner of your main monitor.

|project|'s icon in the system's tray


This k icon also indicates any activity from the plugins (e.g. cataloging, suggesting, executing, …) by turning green. Color is restored to normal as soon as plugins have finished their jobs.

4.2. Open the LaunchBox

Once Keypirinha is running, press Ctrl+Win+K (by default) to show the LaunchBox

|project|'s main dialog


Many former Launchy users change the default hotkey to Alt+Space

4.5. Associate a Keyword to an Item

This is one of the coolest search feature of Keypirinha.

Still with our example, if you happen to launch your Firefox browser a lot, you probably want to keep the number of keystrokes that are required to search and launch it to a minimum.

Keypirinha implicitly associates a keyword with a particular item once this item is executed using any of the provided action .

In the last section, we typed the search term F (or f, search is case- insensitive), before executing Firefox. Keypirinha recorded that information so every time your search term will be f, the Firefox item will be pushed up to the top of the results list.


Association is done at execution time, that is, when you actually launch the item.


You may want to associate f with an other item later. In that case, just type f and select this other item before executing it. Keypirinha will change the association implicitly.

4.6. Specify arguments

In Keypirinha, some items accept or require arguments.

Once you typed your search term and selected the desired item, hit the Tab key (see also the space_as_tab setting).

Back to our example, Firefox currently accepts the -preferences command line option so let’s try typing this one and execute our item.


4.7. Actions

Items may have several associated actions.

Search and select the Firefox item again.


By default, the number of actions available for the selected item are displayed at the right side: here 8 actions. Hit the Ctrl+Enter to visualize these actions (or the Tab key until you reach the actions list).

Because this particular Firefox item is a file, a *.lnk file in this example, the following actions are made available:


Select the one you want and press Enter to execute.

4.8. Maximize the LaunchBox

Alt+X (or Win+Up) toggles between normal and maximized state.

You may need to temporarily extend the size of the LaunchBox sometimes in order to see the full content of some items in the results list. You can do that by either pressing Alt+X or Win+Up (toggle).


This feature does not impact the geometry you manually setup in case your geometry setting is persistent. Hit Alt+X again and your previous position and size will be restored. CAUTION: If you are in persistent geometry, do not reposition/resize the window while being in maximized mode or you will loose your previous geometry.

4.10. Drag and Drop

The LaunchBox allows drag-and-drop operations.

For example, a file from Windows Explorer can be dropped to the search box to insert its full path.

Also, items in the results list can be dragged out. The effect of the resulting drop depends on the type of item and the destination application:

  • The actual file pointed at by a FILE item will be copied to the drop destination.

  • The text content of the URL, CMDLINE, EXPRESSION and ERROR items will be copied to the drop destination. For example:

    • a URL item dropped to your web browser’s window will usually open this URL

    • a CMDLINE item dropped to a text editor will insert the CMDLINE itself


Like in Windows Explorer, you can drag out FILE items using either the left mouse button to have a regular behavior, or the right mouse button to invoke a contextual menu at drop destination that allows you to choose the desired drop effect.

4.11. Clear the history

It is possible to clear the history of every executed items by executing the Clear History item that can always be found in the Catalog. It can be done from application’s main contextual menu as well (right click on the LaunchBox).

If you just want to erase a single item from the history, just search for it, select it and press Ctrl+Del. A message dialog will ask you to confirm the operation.

It is also possible to delete every reference to a specific package from the history by selecting a result item from this package, then clicking the Remove parent package from History action from its contextual menu.
Note that no keyboard shortcut is provided here as it is assumed to be rarely used and to avoid any mistake.


By clearing the full history, the score subsystem is also reset and you will also loose the internal dictionary of the keywords you associated with items, that is described in the Associate a Keyword to an Item section.

4.12. Configuration

See the Configuration section for more info.

4.13. GUI Theming

It is possibe to tweak Keypirinha’s GUI, see Theming for more info.

4.14. Plugins

Some plugins, called packages in Keypirinha, are shipped with Keypirinha and are available out of the box. See Shipped Packages.

Also, some Keypirinha users kindly shared the packages they developed to the community. You may find them useful. See Third-Party Packages.

4.15. Customize your Catalog

Read the Customize your Catalog chapter to discover how you can gain full control over what will be referenced in Keypirinha’s database and consequently, in search results.

4.16. Extending Keypirinha

Despite its apparent simplicity, Keypirinha is a generic tool that is able to welcome a very wide range of features not offered yet by the official bundled plugins. An API allows to extend Keypirinha’s features to make them fit your needs.

See the Extending Keypirinha (API) section for more info.