xdg-desktop-portal backend for choosing files with your favorite file chooser. By default, it will use the yazi file manager, but this is customizable. Based on xdg-desktop-portal-wlr (xdpw).
Install the required packages for your distribution.
On apt-based systems:
sudo apt install xdg-desktop-portal build-essential ninja-build meson libinih-dev libsystemd-dev scdoc
On Alpine/postmarketOS:
sudo apk add meson ninja-build clang cmake pkgconfig inih-dev basu-dev scdoc xdg-desktop-portal
On Arch, either use the available AUR package, or use the following:
sudo pacman -S xdg-desktop-portal libinih ninja meson scdoc git
git clone https://github.com/hunkyburrito/xdg-desktop-portal-termfilechooser
cd xdg-desktop-portal-termfilechooser
meson build
ninja -C build
ninja -C build install # run with superuser privileges
On Alpine/postmarketOS, copy the configs to the right place:
mkdir -p ~/.config/xdg-desktop-portal-termfilechooser/
sudo cp ~/Downloads/xdg-desktop-portal-termfilechooser/contrib/config ~/.config/xdg-desktop-portal-termfilechooser/
sudo cp ~/Downloads/xdg-desktop-portal-termfilechooser/contrib/yazi-wrapper.sh ~/.config/xdg-desktop-portal-termfilechooser/
sudo cp ~/Downloads/xdg-desktop-portal-termfilechooser/termfilechooser.portal /usr/share/xdg-desktop-portal/portals/
On Debian and Arch, move the termfilechooser.portal file:
sudo mv /usr/local/share/xdg-desktop-portal/portals/termfilechooser.portal /usr/share/xdg-desktop-portal/portals/
By default, the contents of the contrib folder are placed in /usr/local/share/xdg-desktop-portal-termfilechooser/.
Copy the config to ~/.config/xdg-desktop-portal-termfilechooser and edit it to set your preferred wrapper and default directory.
Wrappers specified within the cmd key in the config are searched for in order of the following directories unless the full path is specified.
$XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/usr/local/share/xdg-desktop-portal-termfilechooser/usr/share/xdg-desktop-portal-termfilechooser- Any other directory in your
$PATH
The main options for customizing how the filepicker is launched (in recommended order) are:
- Editing the
envkey in theconfig - Prepending your environment variables in the
cmdkey in theconfig - Exporting a global
TERMCMDenvironment variable - Creating/Editing your own wrapper file
Note: Setting environment variables in the config with env does not require you to quote the entire value. See example below.
### $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/config ###
[filechooser]
cmd=yazi-wrapper.sh
default_dir=$HOME/Downloads
env=TERMCMD=foot -T "terminal filechooser"
VARIABLE2=VALUE2
OR
### $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/config ###
[filechooser]
cmd=yazi-wrapper.sh
default_dir=$HOME/Downloads
env=TERMCMD=foot -T "terminal filechooser"
env=VARIABLE2=VALUE2
Environment variables that unset values are also allowed. (e.g. env=VARIABLE=)
Note: Setting environment variables by prepending requires proper quoting and necessary escaping. See example below.
### $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/config ###
[filechooser]
cmd=TERMCMD='foot -T "terminal filechooser"' yazi-wrapper.sh
default_dir=$HOME/Downloads
Note: Setting TERMCMD globally requires proper quoting and necessary escaping. See example below.
### $HOME/.profile, .bashrc, or equivalent ###
# use foot intead of kitty
export TERMCMD='foot -T "terminal filechooser"'cp /usr/local/share/xdg-desktop-portal-termfilechooser/yazi-wrapper.sh $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/yazi-wrapper.sh
### $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/config ###
[filechooser]
# prioritizes `yazi-wrapper.sh` in `$XDG_CONFIG_HOME` dir over `/usr/local/share` dir
cmd=yazi-wrapper.sh
default_dir=$HOME/Downloads
If your xdg-desktop-portal version
xdg-desktop-portal --version
# If xdg-desktop-portal not on $PATH, try:
/usr/libexec/xdg-desktop-portal --version
# OR, if it says file not found
/usr/lib64/xdg-desktop-portal --version
is >= 1.18.0, then you can specify the portal for FileChooser in ~/.config/xdg-desktop-portal/portals.conf file (see the flatpak docs and ArchWiki):
org.freedesktop.impl.portal.FileChooser=termfilechooser
If your xdg-desktop-portal --version is older, you can remove FileChooser from Interfaces of the {gtk;kde;…}.portal files:
find /usr/share/xdg-desktop-portal/portals -name '*.portal' -not -name 'termfilechooser.portal' \
-exec grep -q 'FileChooser' '{}' \; \
-exec sudo sed -i'.bak' 's/org\.freedesktop\.impl\.portal\.FileChooser;\?//g' '{}' \;
Restart the portal service:
systemctl --user restart xdg-desktop-portal.service
GDK_DEBUG=portals zenity --file-selection
and additional options: --multiple, --directory, --save.
-
After editing termfilechooser's config, restart its service:
systemctl --user restart xdg-desktop-portal-termfilechooser.service -
The termfilechooser's executable can also be launched directly:
systemctl --user stop xdg-desktop-portal-termfilechooser.service /usr/local/libexec/xdg-desktop-portal-termfilechooser -l TRACE -r &or, if it says file/folder not found:
systemctl --user stop xdg-desktop-portal-termfilechooser.service /usr/lib64/xdg-desktop-portal-termfilechooser -l TRACE -r &This way the output from the wrapper scripts (e.g.
ranger-wrapper.sh) will be written to the same terminal. This is handy for using e.g.set -xin the scripts during debugging. When termfilechooser runs as asystemdservice, its output can be viewed withjournalctl. -
Since this merge request in GNOME,
GTK_USE_PORTAL=1seems to be replaced withGDK_DEBUG=portals. -
See also: Troubleshooting section in ArchWiki.
Firefox has a setting in its about:config to always use XDG desktop portal's file chooser: set widget.use-xdg-desktop-portal.file-picker to 1. See https://wiki.archlinux.org/title/Firefox#XDG_Desktop_Portal_integration.
See man 5 xdg-desktop-portal-termfilechooser.
MIT