Flea is for Omarchy: omarchy and quickshell are hard dependencies, so it will not install on a
plain Arch box.
Flea installs as an Arch package, so pacman owns both ends: makepkg -si puts it on, pacman -Rns
takes it off, and pacman's own file list is what makes the second claim provable. There is no
install script here because there is nothing for one to do. The steps pacman cannot own are
per-user preferences, and they are subcommands of the binary: flea --default makes Flea your
default file manager, puts it in front of the other file managers for "Show in folder", and routes
the desktop's file chooser to it, and flea --picker does that last part alone. Both are described
below.
Flea is available only from the Omarchy Package Repository, as flea. It needs Omarchy, and the
AUR accepts only packages that work on a plain Arch install, so Flea has no AUR package.
omarchy pkg add flea
Omarchy's build host builds and signs each tagged release for x86_64 and aarch64, so nothing
compiles on your machine. omarchy update keeps it current: a release arrives a day or more after
it ships, once Omarchy has reviewed and built it. Omarchy refuses yay -Syu and pacman -Syu;
omarchy update is the update command.
Moving from the AUR. Earlier releases were also on the AUR as flea-bin, flea-git and a
source-built flea. To move from flea-bin or flea-git, run the interactive command and answer
y when pacman asks whether to remove the AUR package:
sudo pacman -S flea
omarchy pkg add flea cannot make that swap: it passes --noconfirm, pacman then answers its own
removal question with the default No, and the install stops at "unresolvable package conflicts".
The AUR's flea shares the repository package's name, so omarchy update replaces it with the
repository build at the next release. flea --default and flea --picker write per-user files, so
the move keeps them.
git clone https://github.com/thisisgm/flea.git
cd flea
mkdir -p ../flea-build
cp PKGBUILD ../flea-build/
pkgver=$(. ./PKGBUILD && echo "$pkgver")
git archive --prefix="flea-$pkgver/" -o "../flea-build/flea-v$pkgver.tar.gz" HEAD
(cd ../flea-build && makepkg -fCsi --skipchecksums)
The repository's PKGBUILD is the Omarchy Package Repository's recipe, the same text apart from the
release fields, so a local build is the build the repository makes. Its source is the release
tarball. git archive writes that tarball from the checkout under the same name into flea-build,
and makepkg uses a source file it finds beside the PKGBUILD instead of downloading one. The build
runs there and not in the clone because makepkg unpacks into a src/ beside the PKGBUILD, and the
clone's src/ is Flea's own code. -f builds again when the version has not changed, where makepkg
would otherwise install the package it already has, and -C empties the previous build's src/
first, so a file deleted since then is not packaged. --skipchecksums is needed because the
recipe's checksum is a placeholder that only a release replaces; the tarball is your own commit, so
git already vouches for it. -s pulls in anything missing from depends and makedepends, and
-i hands the finished package to pacman. check() runs the test suites, so a package that builds
is a package whose suites passed. The last commit is the source: git archive packages HEAD,
so commit an edit before you build it.
| Path | What it is |
|---|---|
/usr/bin/flea |
the binary, backend and launcher both |
/usr/share/flea/ui/ |
the Quickshell UI, which paths.rs looks for by boot/shell.qml |
/usr/share/flea/ui/Commons, /usr/share/flea/ui/Ui |
symlinks into /usr/share/omarchy/shell/, reached from QML as qs.Commons |
/usr/share/flea/i18n/<code>/flea.json |
the translation catalogs, one per Omarchy language, which src/i18n/mod.rs reads |
/usr/lib/flea/flea-portal |
the XDG portal backend, which answers org.freedesktop.impl.portal.FileChooser |
/usr/lib/flea/flea-filemanager1 |
the D-Bus service, which answers org.freedesktop.FileManager1 for "Show in folder" |
/usr/share/dbus-1/services/com.thisisgm.flea.FileManager1.service |
what D-Bus activates that with |
/usr/share/xdg-desktop-portal/portals/flea.portal |
what registers that backend with xdg-desktop-portal |
/usr/share/dbus-1/services/org.freedesktop.impl.portal.desktop.flea.service |
what D-Bus activates it with |
/usr/lib/flea/flea-gio-auth |
the mount helper, which answers one GIO mount password prompt |
/usr/lib/flea/flea-udisks |
the udisks helper, which the flasher runs to write an image to a drive |
/usr/share/applications/com.thisisgm.flea.desktop |
the desktop entry |
/usr/share/icons/hicolor/scalable/apps/com.thisisgm.flea.svg |
the icon |
/usr/share/libalpm/hooks/flea.hook |
the removal note, which prints the per-user undo commands below |
/usr/share/licenses/flea/LICENSE |
the licence |
The count is whatever the built archive declares, not a number written down here: the UI grows a file
whenever a component is added, so a figure pinned in this paragraph would be stale by the next commit.
packaging/flea-package-test reads the count out of the archive and fails if the fake root does not
hold exactly that many. The two symlinks are why omarchy is a hard dependency: they point into a
directory that package owns.
Pairing an iPhone also switches it to its tethering USB configuration, so iOS shows Personal Hotspot
as active while it is plugged in; Flea does not use that connection. To keep this machine from routing
through the phone, tell NetworkManager, which Omarchy runs, to leave that interface alone, for example in
/etc/NetworkManager/conf.d/90-ipheth-unmanaged.conf:
[keyfile]
unmanaged-devices=driver:iphethThen run sudo systemctl restart NetworkManager.
The window draws with Vulkan and falls back to OpenGL. A GPU with no Vulkan driver and an
OpenGL driver without storage buffers, such as Intel HD Graphics 2000 and 3000 (Sandy Bridge),
can use neither, so it needs Mesa's software Vulkan driver, the optional dependency
vulkan-swrast:
omarchy pkg add vulkan-swrast
The window then draws on the CPU. Without a usable driver, flea --gui exits with status 1 and
says why on stderr and in the journal, and in a desktop notification when it was not started from
a terminal. flea --tui in a terminal works on any GPU. The renderer fallback gives the order Flea tries drivers in.
sudo pacman -Rns flea
An older AUR install removes the same way under its own name, flea-bin or flea-git.
Everything above goes, including the directories the install created. The package carries no
.INSTALL scriptlet, so nothing is ever created outside the file list pacman tracks, and the
desktop and icon caches are re-indexed by
Arch's own update-desktop-database and gtk-update-icon-cache hooks, which fire on Remove as
well as on Install.
Removal also runs Flea's own flea.hook, before any file goes. It prints flea --default off and
flea --picker off, because what those two commands undo lives in each user's home, where pacman
never reaches. Run them before the removal; once Flea is gone, the two "What pacman -Rns flea
leaves behind" sections below name each file to delete by hand. Moving from an AUR package to
flea removes one package too, so the note appears then as well; its first line says it only
matters when Flea is leaving for good.
Installing registers Flea for inode/directory and for org.freedesktop.FileManager1; it makes
Flea the answer for neither, because another file manager is registered for both, and it does not
touch Omarchy's file-manager keys. All of those are per-user preferences, so pacman cannot own them, and
Omarchy's own default verbs (omarchy default browser, editor, terminal) set exactly this
kind of thing without a package's help. There is no omarchy default filemanager, and
/usr/share/omarchy/ is the package's to overwrite, so Flea carries the verb itself:
flea --default
It does every step below, each reported on its own line, and it is honest about state: run it twice
and the second run says every step it ran is already Flea's and rewrites nothing. It needs no root,
because every file it writes is yours, and it takes no argument, because Omarchy's default verbs
take one to name which program and here the program is Flea. The files it writes are
~/.config/mimeapps.list, ~/.local/share/dbus-1/services/org.freedesktop.FileManager1.service,
~/.config/hypr/bindings.lua and ~/.config/xdg-desktop-portal/portals.conf.
-
The
inode/directoryhandler.xdg-mime default com.thisisgm.flea.desktop inode/directory, the stock tool, which writes one line to~/.config/mimeapps.list. The line printed names the previous handler,org.gnome.Nautilus.desktopon a stock Omarchy, which comes from/usr/share/applications/mimeapps.list. Only that one type: the entry registers nothing else, and a file manager that takes image or archive types is a bad citizen. The answer is read back withxdg-mime query defaultrather than trusted, becausexdg-mime defaultexits 0 whatever it wrote. -
"Show in folder". Chromium, Firefox, Steam and everything else that reveals a downloaded file call
org.freedesktop.FileManager1on the session bus. Installing Flea registers for that name in/usr/share/dbus-1/services, but so do nautilus, dolphin, thunar and nemo, each in a file of its own in that same directory, and D-Bus keeps whichever registration it reads first. Omarchy ships nautilus inomarchy-base.packages, so a stock box always has a second claimant, and which one wins inside a directory is the bus's business: dbus-broker sorts it, dbus-daemon takes it in readdir order, and neither can be steered by installing a package. So this step writes one more registration, in the directory that is read before every system one:~/.local/share/dbus-1/services/org.freedesktop.FileManager1.service# Written by `flea --default`; `flea --default off` removes it. [D-BUS Service] Name=org.freedesktop.FileManager1 Exec=/usr/lib/flea/flea-filemanager1The first line is there because a user-level service file with no provenance is a bug nobody can trace;
dbus-brokeranddbus-daemonboth accept it, measured on this box. TheExecis copied out of the registration the package installed rather than written down by the command, so a box with nocom.thisisgm.flea.FileManager1.serviceinstalled has nothing to put in front and this step refuses instead of naming a path that is not there. -
Omarchy's two file-manager keys.
SUPER + SHIFT + FandSUPER + ALT + SHIFT + Fare bound to Nautilus in/usr/share/omarchy/default/hypr/bindings/applications.lua, whichomarchy updateoverwrites, so the override goes where the Omarchy manual says an override goes: appended to~/.config/hypr/bindings.lua, between two marker lines, in the manual's ownhl.unbindtheno.bindshape:-- flea --default: begin. Written by `flea --default`; `flea --default off` removes the block whole. hl.unbind("SUPER + SHIFT + F") o.bind("SUPER + SHIFT + F", "File manager", { launch = 'flea --gui' }) hl.unbind("SUPER + ALT + SHIFT + F") o.bind("SUPER + ALT + SHIFT + F", "File manager (cwd)", { launch = 'flea --gui "$(omarchy-cmd-terminal-cwd)"' }) -- flea --default: end.
The cwd key keeps its meaning:
omarchy-cmd-terminal-cwdis the helper Omarchy's own Nautilus binding reads the active terminal's directory with, and Flea's positional argument is a path. After writing,hyprctl reloadruns andhyprctl configerrorsis read; if the config no longer loads, the file is put back as it was and the command fails saying whatconfigerrorssaid. The output names what each key ran before, read offhyprctl binds. From outside the session, wherehyprctlcannot be reached, the block is still written and the output says to runhyprctl reloadyourself. -
The file chooser. Everything
flea --pickerdoes, described in the next section. A box updating from 0.1.3 has a Flea with no chooser routing, and one command should finish the job.This step is the skipped-not-failed one, and no other step is. It needs
flea.portal, which only the package installs. Run a binary you built withcargo buildon a box whose installed package predates the chooser, which is every box updating from 0.1.3, and the command printsflea: no file chooser service is installed, so Flea could not become the file chooserand carries on. On such a box the honest-about-state line above is a claim about the steps that ran alone: the chooser was never claimed, so a second run cannot say it is already Flea's. That box has no packagedcom.thisisgm.flea.FileManager1.serviceeither, and step 2 says so and fails rather than skipping, so the command exits 1 having done steps 1 and 3. With no Flea package installed at all, step 1 refuses first and nothing is written, becausecom.thisisgm.flea.desktopis the proof the package landed.
Run it from a terminal inside the session, so the keys and file dialogs take effect at once: there it also restarts xdg-desktop-portal, as described under the file chooser below.
Settings > About has the same switch, "Make Flea the default", directly under the File manager row.
Ticking it runs flea --default and unticking it runs flea --default off: the same commands, the
same steps, and the same four files. After either one goes through, the switch also runs
systemctl --user try-restart xdg-desktop-portal.service, so file dialogs follow at once instead of
at the next login; try-restart leaves a portal that is not running alone. If that restart fails
the switch still stands, and the line under it says "File dialogs follow after xdg-desktop-portal
restarts." The command makes the same restart itself only when its output is a terminal, so the
switch's run, whose output it reads, restarts nothing and the portal restarts once. The box is
ticked when xdg-mime query default inode/directory answers com.thisisgm.flea.desktop, and that
answer is read again after every run, so the box shows what the desktop will do rather than what was
clicked. The line under it says what happened: that
folders, Show in folder and file dialogs open Flea; that file dialogs were left out because the
package's portal files are missing (step 4's skip); or the first line flea printed when a step failed.
On a build with no Flea desktop entry installed the switch is greyed and asks you to install a
package first, which is step 1's refusal said before you press it. It stores nothing in Flea's
settings.
flea --default off
Removes Flea's inode/directory line from ~/.config/mimeapps.list, so the handler falls back to
whatever the system default is (Nautilus on stock Omarchy), deletes
~/.local/share/dbus-1/services/org.freedesktop.FileManager1.service and the two directories it
created when nothing else is in them, so "Show in folder" goes back to whichever packaged
registration D-Bus reads first, and removes the marked block from
~/.config/hypr/bindings.lua byte for byte, then reloads, and undoes the file-chooser step exactly
as flea --picker off does. Unticking "Make Flea the default" in Settings > About runs the same
command. If you had pinned another handler in
~/.config/mimeapps.list before running flea --default, the first run printed its id as
was <id>; xdg-mime default <id> inode/directory puts that pin back.
Everything the package installed goes, as above. The edits flea --default made are per-user state,
and pacman neither knows nor should know about them, so they stay. Its chooser edits are covered by
the next section:
inode/directory=com.thisisgm.flea.desktopin~/.config/mimeapps.list. Inert once the binary is gone:xdg-mime query defaultskips an entry whoseExecis not onPATH, and answeredorg.gnome.Nautilus.desktopwith that line in place when this was exercised without afleaonPATH. Still litter. Delete the line, or runxdg-mime default org.gnome.Nautilus.desktop inode/directory.- The block between
-- flea --default: beginand-- flea --default: endin~/.config/hypr/bindings.lua. With nofleaonPATHthe two keys would do nothing. Delete the block and runhyprctl reload. ~/.local/share/dbus-1/services/org.freedesktop.FileManager1.service. This one is not inert, and it is the reason to run the undo before the removal: it still names/usr/lib/flea/flea-filemanager1, which pacman has taken away, and D-Bus does not fall through to the next claimant when the first one will not start. Measured here with the file in place and no such binary, the call answersorg.freedesktop.DBus.Error.Spawn.ExecFailed: Failed to execute program, and the packaged registration behind it never runs. Its first line says it was written byflea --default; delete it, or runflea --default offwhile the binary is still there.
The clean order is flea --default off before sudo pacman -Rns flea, after which there is nothing
to do by hand. flea --default off leaves ~/.config/mimeapps.list in place even when it was the
one that created it, holding an empty [Default Applications] section: the file is the desktop's,
other tools write to it too, and an empty section is harmless.
Every application that asks the desktop to pick a file, from omarchy tailscale send to a Flatpak,
goes through the XDG portal: it calls org.freedesktop.portal.FileChooser, and xdg-desktop-portal
hands that to whichever backend the configuration prefers. On a stock Omarchy box that is
xdg-desktop-portal-gtk, which is why a GTK dialog appears in the middle of Omarchy. Installing Flea
registers a backend; it does not prefer it. That is a per-user preference, so:
flea --picker
writes one key to ~/.config/xdg-desktop-portal/portals.conf:
[preferred]
org.freedesktop.impl.portal.FileChooser=flea;gtk
If ~/.config/xdg-desktop-portal/hyprland-portals.conf exists, xdg-desktop-portal reads that file and
ignores portals.conf, so the same key goes there instead. A backend it replaces, such as the GNOME
portal's Nautilus chooser, is kept on a comment above Flea's line for flea --picker off to restore:
# flea replaced: org.freedesktop.impl.portal.FileChooser=gnome;gtk
org.freedesktop.impl.portal.FileChooser=flea;gtk
and it writes one more thing, an additive block in ~/.config/hypr/bindings.lua beside the one
flea --default writes:
-- flea --picker: begin. Written by `flea --picker`; `flea --picker off` removes the block whole.
o.window("com.thisisgm.flea.picker", { tag = "+floating-window" })
-- flea --picker: end.That is Omarchy's own treatment for a prompt, not a size Flea invented:
/usr/share/omarchy/default/hypr/apps/system.lua tags xdg-desktop-portal-gtk's windows the same
way, and Omarchy's tag rules are what then float, centre and size them. The picker carries its own
app id, com.thisisgm.flea.picker, so this rule reaches the chooser and never the file manager
window. As with the keys, the file is written, hyprctl reload runs, hyprctl configerrors is read,
and a config that no longer loads is put back as it was.
It writes no default= line, and that is the whole design. xdg-desktop-portal
collects every configuration file it can find into an ordered list, the user's first, and resolves each
interface through them in turn: an interface this file does not name falls through to the next file,
which on Omarchy is /usr/share/xdg-desktop-portal/hyprland-portals.conf and its default=hyprland;gtk.
So ScreenCast, Screenshot, GlobalShortcuts and InputCapture still resolve to hyprland, and Account,
Email and DynamicLauncher still resolve to gtk, exactly as before. gtk stays behind flea on Flea's
own line for the same reason: if flea.portal ever goes missing, there is still a chooser.
xdg-desktop-portal reads its configuration once, at startup, so a live session keeps the old routing
until it is restarted. Run at a terminal, flea --picker, flea --default and both off forms do
that themselves with systemctl --user try-restart xdg-desktop-portal.service, the Settings switch's
own restart, and say xdg-desktop-portal restarted if it was running, so file dialogs follow now.
With their output piped or redirected, as Settings runs them and as a script capturing them does,
they restart nothing, since the caller may own the restart, and a refused restart is reported the same
way: the line names the command to run instead:
systemctl --user restart xdg-desktop-portal
A claim refused before it wrote anything restarts nothing and prints neither line.
The picker that then opens is Flea: the same rows, icons, theme and keys as the window, with a check
box in front of every row a caller can receive. Space marks, Enter walks into a directory or submits
what is marked, Backspace climbs, Escape refuses. . shows and hides the directory's dotfiles, the
same re-read the window makes; a preset's toggleHidden chord does the same. Nothing marked and Enter
does nothing, because a chooser that sends on a stray keypress is worse than one that asks twice.
flea --picker off
puts back the backend a # flea replaced: comment names, or removes Flea's line when there is no
comment, in portals.conf and in any <desktop>-portals.conf beside it, and removes portals.conf
when Flea's line was all it held. It removes the Hyprland block byte for byte. Restart
xdg-desktop-portal again and the previous chooser is back.
~/.config/xdg-desktop-portal/portals.conf is per-user state like mimeapps.list above, so it stays.
With no flea.portal installed, xdg-desktop-portal logs that the requested backend does not exist and
takes the next name on the line, which is gtk, so the desktop keeps a working chooser either way.
The same goes for hyprland-portals.conf when Flea's line went there. The flea --picker block in
~/.config/hypr/bindings.lua stays too, inert with no Flea window to match: delete it and run
hyprctl reload. The clean order is flea --picker off before sudo pacman -Rns flea.
%f because Flea's positional argument is a path. A %u entry advertises that the program
understands URI schemes, and Flea's positional does not: only --select strips a file:// prefix
and percent-decodes. For a local directory the two field codes measure the same, both hand over one
decoded path, so the difference only shows on a remote URI, where %u would give Flea an
smb://host/share string to treat as a relative path.
--gui because a desktop entry should name the mode it means, not because the launch would
otherwise land somewhere else. Bare flea opens the window too, and reads no stdio to decide it, so
the flag changes nothing today: it is the contract that keeps this entry correct if bare ever stops
meaning the window. Launcher stdio is beside the point either way, and every launcher measured here
hands over none: glib routes the launch through the session bus, so the child's stdio is the user
manager's.
StartupWMClass matches the GPUI window's APP_ID, com.thisisgm.flea, set in
crates/flea-gui/src/window/mod.rs. The retained QML entry has the same AppId;
packaging/flea-package-test still compares that pragma with the desktop entry.
printf '%s\n' "$OMARCHY_SUDO_PASS" | packaging/flea-package-test
Builds the package, installs it into a fake root, checks the fake root holds exactly the file count
the archive declares, removes it, and checks nothing survives. Every write is inside a mktemp -d
the shared guard has cleared; pacman is confined by --root and --dbpath, and the one root
rm -rf runs on a path sandbox_require has just checked. Without a password on stdin the round
trip is skipped and the rest still runs.
Ask the box, and it names the file it is reading the answer out of:
journalctl --user -b | grep "duplicate name 'org.freedesktop.FileManager1'"Every line names a registration D-Bus threw away, so the one claimant that is not on that list is
the one answering. Run flea --default and Flea's own file is the one that is not on it, because
$XDG_DATA_HOME is read before /usr/share; run flea --default off and it goes back to whichever
packaged registration is read first. Removing the file manager you are not using works too, and is
the only thing that changes the answer for a user who never runs flea --default.