Ulauncher Overview
Relevant source files
The following files were used as context for generating this wiki page:
Ulauncher is a fast, feature-rich application launcher for Linux, developed in Python using the GTK+ framework. Its primary purpose is to provide users with a highly extensible search interface to launch applications, browse files, perform calculations, and trigger custom scripts via extensions.
The system is designed around a decoupled architecture where the UI layer, core logic, and external extensions communicate through an event bus and IPC mechanisms. This allows for rapid query processing while maintaining a responsive interface.
Sources: README.md:14-16, ulauncher/ui/preferences/views/about.py:45-48
System Architecture
Ulauncher's codebase is organized into four primary domains to ensure modularity and separation of concerns.
| Component | Responsibility |
|---|---|
| API | Handles extension-side IPC clients and shared types for external processes. |
| Modes | Contains query handlers for specific domains (Apps, Files, Extensions, Calculator). |
| UI | Manages GTK components, windowing logic, and user input. |
| Utils | Shared utilities for the EventBus, timers, and socket communication. |
Sources: CONTRIBUTING.md:129-135, ulauncher/ui/app.py:16-25
Component Relationship
The following diagram illustrates how the core application coordinates between the CLI, the UI, and the underlying query modes.
The application uses a multi-process architecture for extensions to prevent external scripts from blocking the main UI thread.
Sources: CONTRIBUTING.md:154-157, ulauncher/core.py:42-50, ulauncher/ui/app.py:53-65
Core Logic and Query Handling
The UlauncherCore class serves as the central engine for processing user input. It manages the lifecycle of "triggers" and delegates searches to various specialized Mode implementations.
Query Processing Flow
When a user types into the input field, the following sequence occurs:
Keyword vs. Non-Keyword Matching
- Keyword Match: If the first word of a query matches a registered keyword (e.g.,
gfor Google search), the core delegates the remaining string to that specific mode. - Search Triggers: If no keyword is identified, the core performs a fuzzy search across all active triggers (Applications, Shortcuts, etc.) and returns results exceeding a minimum score (default 50).
Sources: ulauncher/core.py:95-120, ulauncher/core.py:126-133
User Interface Layer
The UI is built using GTK3 and revolves around the UlauncherApp (a Gtk.Application subclass) and UlauncherWindow (a Gtk.ApplicationWindow subclass).
Window Structure
The UlauncherWindow is a decorated-less window designed to appear in the center of the screen or on specific monitors. Its widget hierarchy is structured for theming and focus management:
- Frame: Positioning container.
- Shadow Container: Provides space for CSS-based window shadows.
- Theme Root: The base for CSS styling classes (e.g.,
.app). - Prompt: Contains the
Gtk.Entryfor input and the preferences button. - Results Scroller: A
Gtk.ScrolledWindowthat renders dynamicResultWidgetitems.
Sources: ulauncher/ui/ulauncher_window.py:73-118, ulauncher/ui/ulauncher_window.py:339-354
Theming and Styling
Styles are applied via Gtk.CssProvider. The application supports custom themes loaded from the user's configuration paths.
Sources: ulauncher/ui/ulauncher_window.py:284-295, data/preferences.css:1-25
Command Line Interface (CLI)
The CLI allows interacting with the background process and managing extensions without opening the main window.
| Command | Alias | Description |
|---|---|---|
start | - | Starts the Ulauncher background process. |
show | - | Opens the launcher window (optionally with a query). |
toggle | - | Toggles the launcher window visibility. |
install | i | Installs an extension from a Git URL or local path. |
uninstall | rm | Removes an installed extension by ID. |
upgrade | up | Upgrades extensions to their latest versions. |
Sources: ulauncher/cli/init.py:125-185
Extension System
Extensions are standalone processes that communicate with the main Ulauncher process via Unix socket pairs using a JSON-line protocol.
Manifest Configuration
Every extension must provide a manifest.json defining its metadata and behavior.
# Key fields in ExtensionManifest
required_fields = ["api_version", "authors", "name", "icon", "triggers"]
Sources: ulauncher/modes/extensions/extension_manifest.py:85-88
Lifecycle and IPC
- Discovery: Extensions are loaded from
~/.config/ulauncher/extensions. - Subprocess: Ulauncher creates a socket pair and passes one file descriptor (FD) to the extension process via the
SOCKETPAIR_FDenvironment variable. - Events: The
Clientclass in the extension API listens for events (likeQueryEvent) and sends responses (likeSetHtmlActionorRenderResultListAction).
Sources: ulauncher/api/client/Client.py:38-55, CONTRIBUTING.md:154-157
Summary
Ulauncher operates as a centralized hub for Linux desktop productivity. By decoupling its search logic into a Mode system and offloading extended functionality to isolated extension processes, it maintains high performance. The integration of GTK allows for a native look and feel, while the robust CLI and IPC mechanisms facilitate a flexible development environment for contributors.
Sources: README.md:18-22, CONTRIBUTING.md:128-140