Installation and startup
Luciole needs a Wayland session with EGL/OpenGL ES support. Neither the Noctalia shell nor a particular compositor is required.
Prefer a distribution package when one is available; it provides the simplest installation and upgrade path. Otherwise, build from source as described below. Package maintainers will find dependencies and install layout in PACKAGING.md.
Arch Linux
Section titled “Arch Linux”luciole-git is available in the AUR and builds the latest development version. Install it with an AUR helper such as paru or yay:
paru -S luciole-git# oryay -S luciole-gitOptional helpers for video, PDF and archive support and network locations are listed as optional dependencies; see optional features.
Build from source
Section titled “Build from source”Luciole builds with just, Meson and a C++23 compiler (GCC 13+ or Clang 16+).
Arch Linux dependencies
Section titled “Arch Linux dependencies”Build and library dependencies:
sudo pacman -S --needed base-devel meson just \ wayland wayland-protocols libglvnd \ glib2 freetype2 fontconfig cairo pango harfbuzz libxkbcommon \ gdk-pixbuf2 glycin librsvg libpng libarchive xz acl \ tomlplusplus nlohmann-json stbRuntime services and optional helpers:
sudo pacman -S --needed shared-mime-info gsettings-desktop-schemas dconf \ adwaita-icon-theme gvfs gvfs-smb gvfs-dnssd glib-networking \ ffmpeg ffmpegthumbnailer poppler 7zip xdg-terminal-execGVfs provides Trash and network locations; the remaining helpers enable media and PDF thumbnails, encrypted 7z archives and terminal actions. See optional features.
Fedora dependencies
Section titled “Fedora dependencies”Build and library dependencies:
sudo dnf install gcc-c++ meson just \ wayland-devel wayland-protocols-devel libglvnd-devel \ glib2-devel freetype-devel fontconfig-devel cairo-devel pango-devel harfbuzz-devel libxkbcommon-devel \ gdk-pixbuf2-devel glycin-devel librsvg2-devel libpng-devel libarchive-devel xz-devel libacl-devel \ tomlplusplus-devel json-devel stb_image_resize2-develRuntime services and optional helpers:
sudo dnf install shared-mime-info gsettings-desktop-schemas dconf \ adwaita-icon-theme gvfs gvfs-smb glib-networking \ ffmpeg-free ffmpegthumbnailer poppler-utils 7zip xdg-terminal-execFedora’s ffmpeg-free omits some patent-encumbered codecs; the ffmpeg package from RPM Fusion gives thumbnails for more video formats.
Other distributions
Section titled “Other distributions”Install the development packages listed in PACKAGING.md.
Build and install
Section titled “Build and install”git clone https://github.com/noctalia-dev/luciole.gitcd luciolejust build releasesudo just install releaseThis installs under /usr/local; use just configure release /usr before building to choose another prefix. To uninstall, run sudo ninja -C build-release uninstall from the same checkout.
The flake provides a package and a pinned development environment:
nix build github:noctalia-dev/luciole./result/bin/lucioleIt also exports NixOS, Home Manager and hjem modules. Home Manager and hjem can supply programs.luciole.settings as a declarative base; GUI preferences remain separate. See configuration and Nix packaging.
Development builds
Section titled “Development builds”Inside the source directory, just run release builds and starts Luciole using the source tree’s assets, without installing. Do not reuse that asset override in an installed launcher. just lists every recipe, and CONTRIBUTING.md covers checks and code style.
Start Luciole
Section titled “Start Luciole”lucioleluciole /path/to/folderluciole 'file:///path/to/folder'Without an argument, Luciole opens Home. Supply one directory path or URI to start elsewhere. Remote locations require the corresponding installed GIO/GVfs backend and an already mounted/authenticated location. Luciole’s own connect-to-server and credential dialogs are not implemented yet.
Every window runs in one Luciole process. Starting luciole while it is already running opens a new window in that process, so additional windows cost far less memory than separate instances. A relative path names a folder under the directory where the command ran. The process exits when its last window closes.
Use luciole --help for command syntax and luciole --version for the version and build revision. These commands do not open a window. Bash, Zsh and Fish completions are installed with Luciole; luciole completions bash also prints the Bash completion script.
Installing Luciole does not automatically make it the default file manager.
Optional features
Section titled “Optional features”Image format coverage depends on installed Glycin loaders. Video/audio thumbnails and metadata need FFmpeg; PDF thumbnails and metadata need Poppler utilities. Encrypted 7z input needs a system 7-Zip executable. Terminal actions need xdg-terminal-exec and a suitable terminal. Trash and mounted network locations need the appropriate GIO/GVfs services. Missing helpers leave ordinary local browsing available; Packaging lists the full requirements.