From postmarketOS
(Redirected from Xfce)
Xfce4 default configuration running on samsung-serranove
Xfce4 default configuration
running on samsung-serranove
Name Xfce4
Graphics stack Xfwm4 on X11
Toolkit GTK 3
In postmarketOS
Package postmarketos-ui-xfce4
Status Available

Xfce4 is a GTK-based desktop environment aiming to be fast and lightweight. It works on most devices with a working display, and runs fine without hardware acceleration. Uses latest Xfce version packages from Alpine repository.


  • pmbootstrap init
  • User interface: xfce4

The number of default installed packages is kept low on intension for usage on phones/tablets (limited storage) and development (installation time). Turning it into a full-featured desktop would blow it up a lot. The idea is that users individually install additional software they need. You can add the ones you would like in pmbootstrap init at step "Extra packages" or later on by sudo apk add .... For a list of additional software, see Xfce4#Additional_software.

Better (touch) usability

  • General font size can be enlarged in Settings -> Appearance -> Fonts -> Custom DPI setting. Logout or reboot thereafter.
  • The font size of the windows title bars can be enlarged in Settings -> Window Manager. Depending on the device, try e.g. size 16.
  • On devices with large screen, the windows scaling can be set to 2x in Settings -> Appearance > Settings -> Window Scaling.
  • In Settings -> File Manager Settings -> Side Pane, the Shortcut Pane Icon Size can be increased to e.g. 48 px.
  • In the lower panel there is a launcher that starts the terminal maximized. This can also be assigned to a hardware button or to other launchers by xfce4-terminal --maximize.
  • If you can't grab something by touchscreen, use the keyboard (tab key to go through the elements, arrow keys to choose).
  • The onboard keyboard can be hidden/shown by clicking the onboard icon in the panel. A bigger floating icon can be enabled in the onboard settings.
  • To simulate right mouse clicks with the touchscreen, long-click the return key of the onboard keyboard to get some mouse click options at the right side of the keyboard (enabled by default in edge). For other possibilities of right mouse click emulation see Input_methods#Simulate_secondary_click.
  • Hiding the cursor is done by autostart command unclutter-xfixes --start-hidden --hide-on-touch (just for information).
  • Tooltips can be annoying as one cannot interact with what is underneath them, and there is a mouse hovering effect where the screen was last touched so they tend to pop-up a lot. Unfortunately it seems that GTK3 no longer supports optional tooltips so the only real workaround is to make them transparent. Adding the following to ~/.config/gtk-3.0/gtk.css make tooltips transparent and reduce there size (implemented in edge).
tooltip {
    opacity: 0;
    font-size: 0;
Note: Transparency requires a compositor, so this will only affect the size of the tooltips if "display compositing" is disabled in Settings -> Windows Manager Tweaks -> tab "Compositor". Also how small the size of the tooltips can be reduced to seems to be affected by the theme used (in Appearance -> Style). With some themes like "Dexy-Color-Dark-GTK" the size is reduced to a tiny square (the smaller there are the less obstructive it is). Additional possible options for the tooltip block in the gtk.css file are background-color: rgba(0, 0, 0, 0.0);, border-color: rgba(0, 0, 0, 0.0); and border-radius: 0px;.


  • In Settings -> Panel, the panel height can be increased. Setting automatically hide to Intelligently will hide it if a window overlaps the panel area.
  • Icon size of NetworkManager and Onboard can be changed in Settings -> Panel -> Items -> System Tray Plugin -> Edit -> Fixed icon size.
  • To save space on the panel, running programs can be represented as icons only: Settings -> Panel -> Items -> Windows Button -> Edit -> uncheck Show button labels.
  • Reduce the workspace switcher size by Settings -> Panel -> Items -> Workspace Switcher -> Edit -> Appearance: Buttons -> thereafter click the Workspace Settings below and rename the Workspace names to something shorter, e.g. 1, 2, 3, 4. Adding blank spaces before and after the numbers makes the buttons a bit larger again.
  • For shutdown and reboot, the Action Buttons plugin can be added to the panel. In their settings, Appearance can be set to Action Buttons and the list below allows to choose which ones shall be shown.
  • As menu plugin, "Whisker Menu" is set by default. The plugin "Application Menu" can be used alternatively, depending on your taste. The "Application Menu" more compact and in a classic menu look.
  • The size of the window of "Whisker Menu" can be changed by picking the lower right corner and drawing it to the desired size.
  • Icon size in the "Whisker Menu" can be changed in Settings -> Panel -> Items -> Whisker Menu -> Edit.
  • For battery monitoring the "Power Manager Plugin" was added to the panel. This also offers a screen brightness control. To make it look nicer, the label was changed to Percentage, a transparent separater was added between the plugin and the clock and the icon size was changed by the file ~/.config/gtk-3.0/gtk.css. However, if the screen is small and the panel crowded, plugin "Battery Monitor" can be used instead because it's more space-saving than the "Power Manager Plugin".

Horizontal mode

Depending on the device, changing Xfce4 to landscape orientation can increase usability.

  • Rotate the display and touch to horizontal using Display guide.
  • In panel setting, change the mode to Deskbar and remove other plugins.
  • Use CoreApps as they work best on horizontal screens.


On devices with low computing power or without video acceleration, in Settings -> Window Manager Tweaks -> Compositor disable Enable display compositing to get a faster experience.

On some devices, unfortunately, this causes a black screen on the reboot/shutdown dialog (probably because of the transparency of this screen). The screen is still responsive so you have to click "something" in the center, the device will either reboot, shutdown, logout or lock. Instead you better add the Action Buttons plugin to the panel and use this, see Xfce4#Panel section above.

If you can't reach the settings window to disable compositing for some reason, you can also edit the file ~/.config/xfce4/xfconf/xfce-perchannel-xml/xfwm4.xml, search for the line "use_compositing" and change the value to "false".

Toggle wifi

A toggle wifi button can be created from an empty launcher in the panel with command:

/bin/sh -c 'if [ "$(nmcli r wifi)" = "enabled" ]; then nmcli r wifi off; else nmcli r wifi on; fi'.

However, it's more comfortable to have a feedback whether you really hit the button or missed it. This can be achieved by e.g.:

  • sudo apk add zenity
  • vi ~/toggle-wifi-zenity.sh

if [ "$(nmcli r wifi)" = "enabled" ]; then
  if zenity --question --title "" --text "Turn off wifi?" --no-wrap; then
    nmcli r wifi off
  if zenity --question --title "" --text "Turn on wifi?" --no-wrap; then
    nmcli r wifi on
  • chmod +x ~/toggle-wifi-zenity.sh
  • Add an empty launcher to the panel and change it to e.g.:
    • Name: Toggle wifi
    • Comment: Turn on/off wifi
    • Command: /home/user/toggle-wifi-zentiy.sh
    • Icon: network-wireless


  • To enable touch behaviour in Firefox, add a new file sudo vi /etc/profile.d/firefox-touch-scrolling.sh and write export MOZ_USE_XINPUT2=1.
  • Additionally, in about:config, change dom.w3c.touch_events.enabled from 2 (default, auto-detect) to 1 (enabled).
  • To save space, in Firefox -> Menu -> More Tools -> Customize Toolbar the Title Bar option can be unchecked.
  • With environment variable MOZ_USE_XINPUT2=1 active, in Firefox -> Menu -> More Tools -> Customize Toolbar, drag & drob doesn't work. However, with long click on items they can be added or removed. To move them, you need to deactivate MOZ_USE_XINPUT2=1 temporarily.
  • A special issue: When moving the Firefox window partially out of screen, the window manager automatically positions the window back into the screen. For some reason, touch clicks in the Firefox window are then not recognized anymore. You need to open a terminall and killall firefox. Moving the window out of screen can happen accidentally when interacting with the title bar area, so be careful there.
  • In Firefox -> Menu -> More Tools -> Customize Toolbar, at the bottom you can choose a "Density", which is mainly the size of the icons.
  • You can install the package mobile-config-firefox to improve touch usability of Firefox in general (more information on the package).


  • Panel transparency can be set in Settings -> Panel -> Appearance -> Style: Solid Color -> Color -> + -> choose a color, at the bottom the transparency level can be set (documentation).
    • If you want to clean up the set of custom colors, this can be done with gsettings. Get the selected color by gsettings get org.gtk.Settings.ColorChooser selected-color. To clean up the custom colors, paste the output as follows, e.g. gsettings set org.gtk.Settings.ColorChooser custom-colors "[(0.0, 0.0, 0.0, 0.69796610169491529)]". For the second command, when doing this via ssh, DISPLAY variable needs to be put at the beginning of the command, e.g. DISPLAY=:0.
  • The panel size can be changed in Settings -> Panel -> Row size (pixels).
  • Scale of PulseAudio Plugin and Power Manager Plugin icons are editable in file ~./gtk-3.0/gtk.css. For default values, see source. Log out or reboot to apply the changes.
  • Also additional icons can be installed, e.g. arc-icon-theme, oxygen-icons, papirus-icon-theme, zafiro-icon-theme.
  • The plugin of package xfce4-sensors-plugin allows to show sensor data in the panel, mainly hardware temperatures. Plugin xfce4-cpugraph-plugin shows the CPU load, plugin xfce4-cpufreq-plugin shows current frequency and governor.
  • The generic monitor plugin xfce4-genmon-plugin can be used to show all kind of information in the panel. For example:
    • If your device e.g. has multiple batteries and you want to see the percentage of a specific one, enter following command to the plugin to see the percentage of that battery in the panel: cat /sys/class/power_supply/rt5033-battery/capacity. The path to the battery needs to be adapted. Adding a percent sign to the representation can be done by sh -c 'echo $(cat /sys/class/power_supply/rt5033-battery/capacity) %'.
    • A command to show the battery voltage in the panel: sh -c 'echo $(echo "scale=2; $(cat /sys/class/power_supply/rt5033-battery/voltage_ocv) / 1000000" | bc) V'. It converts the value from microvolts to volts (division by 1000000) and rounds the result to two digits (scale=2). This specific example requires package bc to be installed and the path to the battery and available voltage file needs to be adapted.


Auto-rotation is not implemented natively in Xfce4 (upstream issue report). On the page Auto-rotation there are some scripts listed that can provide this functionality. There is also a simple script that can be triggered manually, thus doesn't need a working accelerometer sensor.

Reset Xfce4 configs

Remove the folder ~/.config/xfce4 by e.g. rm -r ~/.config/xfce4 or move it to a backup location like mv ~/.config/xfce4 ~/.config/xfce4_backup. After logout and login again, the default configuration from /etc/xdg/xfce4-phone should be adopted. This applies to Xfce4 settings only, not all of the above described changes will be reset.

Issues with graphics

If you experience issues with graphics, you can try to disable compositing. See Xfce4#Performance.

You can also try to set the "vblank_mode" in file ~/.config/xfce4/xfconf/xfce-perchannel-xml/xfwm4.xml to "off" or "glx". To do so, the line needs to look like <property name="vblank_mode" type="string" value="off"/> or "glx" respectively. Try this in combination with compositing enabled/disabled. The default value is "xpresent", stored at /etc/xdg/xfce4-phone/xfce4/xfconf/xfce-perchannel-xml/xfwm4.xml. In the local config at ~/.config, the default line is <property name="vblank_mode" type="empty"/>, which means that the config of /etc/xdg/xfce4-phone is used.

If this doesn't help, maybe adding some Xorg configs to /etc/X11/xorg.conf.d can improve the situation. See e.g. Debian manpage or Arch Linux wiki.

When still unsolved, probably some work on the kernel drivers is needed.

Backlight control

Clicking the battery icon, there is a slider to set the brightness of the backlight (if backlight control is available in the kernel for the device).

If your device has hardware brightness keys and they don't work, try to enable "Handle display brightness keys" in Settings -> Power manager.

On some (or all?) devices restoring the brightness level after reboot doesn't work. It's unlcear whether this is related to kernel drivers, devicetree setting, init system OpenRC instead of systemd, Xfce4 maybe only being able to handle ACPI controlled backlight, or some missing priviliges e.g. in polkit. A possible workaround is to set up an udev rule:

  • In a terminal use command udevadm info --attribute-walk /sys/class/backlight/[backlight], you need to adjust the last part specifically to the path of your device.
    • Look for SUBSYSTEM and KERNEL
  • Add a new udev rule by sudo vi /etc/udev/rules.d/10_backlight.rules
    • Type ACTION=="add", SUBSYSTEM=="backlight", KERNEL=="...", ATTR{brightness}="100" where you need to change the name of KERNEL and possibly SUBSYSTEM and set a brightness value that suits for you. Safe by Esc and typing :wq.

Setting the timezone

The timezone configuration in the panel clock settings doesn't work for some reason. Setting or changing the timezone can be done by e.g. sudo setup-timezone -z Europe/Amsterdam. Available timezones can be looked up at ls /usr/share/zoneinfo.

Lock screen

To ease the locking, it can be assigned to e.g. the power button. Go to Settings -> Keyboard -> Application Shortcuts, look for the command xflock4, double-click the current key combination to bring up a window for re-assignment, hit the power button to assign. Additionally, you need to edit sudo vi /etc/elogind/logind.conf, disable the line "HandlePowerKey=ignore", log out or reboot to apply the change.

An example draft script to disable inputs while locked can be found at Screen_locker:Disable_inputs#Xfce4.

The virtual keyboard layout can be changed in the screensaver settings, tab "Lock Screen", on screen keyboard command. For bigger screens, layout "Phone" can be replaced by layout "Compact". For more options of the onboard command see e.g. debian manpage.

As the onboard keyboard needs some time to show up, matchbox-keyboard can be installed alternatively and used by command matchbox-keyboard --xid. However, it's not as configurable as the onboard keyboard.


Autologin is configured by default. If you want to use LightDM as a login screen, see Display_manager#LightDM how to set this up.

Disk management

With the set of installed software, additional drives are not shown in the file manager and at the desktop. Install gvfs and udisks2 to make them available (for more information see also pmaports#1377).

As a graphical interface for formatting drives or image writing, e.g. package gnome-disk-utility can be installed (this installs udisks2 as well). After installation, it's at Accessories -> Disks. On small screens, right-click the top bar of the window, choose "Resize" and click approximately where the lower right corner of the window should be.

PDF viewer

Following applications might be installed and used for viewing PDF files: Firefox, MuPDF (see next paragraph), Evince (installs gnome-desktop, these are just the core libraries), possibly Atril (but this brings along file manager caja and mate-desktop). See also PDF#PDF_viewers.


This is a lightweight PDF viewer. Install package mupdf-x11. After installation, files can be opened from terminal by mupdf filename.pdf.

Zooming in and out is done by keyboard keys + and -. To call the virtual keyboard, hit the onboard icon in the panel. For more keybindings see e.g. debian manpage.

Set MuPDF as the default PDF viewer by Settings -> Default Applications -> tab "Others" -> filter for "pdf" -> select "application/pdf" -> button "Open with..." -> at the bottom "Use a custom command" -> button "Browse..." -> choose /usr/bin/mupdf -> hit enter to select.

Phone applications

Packages calls, chatty and gnome-contacts, which are used in Phosh, work also on Xfce4.

The package modemmanager needs to be installed (actually gets installed automatically when installing the above mentioned packages). Start its service by sudo rc-service modemmanager start and add it permanently by sudo rc-update add modemmanager default. When rebooting, a dialog to enter the PIN shows up after boot (if you need to call the keyboard, click the onboard icon in the panel). The connections are managed by NetworkManager: Create a new Mobile Broadband connection and connect to it by clicking the NetworkManager icon in the panel and select the new connection. You might want to enable "connect automatically" in the settings of the connection, tab "General".


For bluetooth management package blueman is installed.

The tray icon needs right-clicking. Alternatively use Menu -> Settings -> Bluetooth Manager and Bluetooth Adapters, and sudo rfkill unblock bluetooth or block respectively to enable/disable.

When hitting the "Search" button in the Blueman window, it searches 30 seconds for other Bluetooth devices. Often those 30 seconds are not enough to detect other devices, which is a bit frustrating. Just keep klicking "Search" several times, keep patient, at some point your target device should show up. If it doesn't work at all, try command bluetoothctl scan on in the terminal with the Blueman window opened in parallel, it's more "efficient", and exit the command with Ctrl+C after having the devices connected.

When entering the adapter or device menu for the first time, there is a question "Shall bluetooth get enabled automatically". The desicion here can later be changed by gsettings set org.blueman.plugins.powermanager auto-power-on false or true. When using the command via ssh, it needs an additional prepending DISPLAY=:0.

Connections can be handled by clicking the tray icon -> Devices (or Settings -> Bluetooth Manager). Connected/disconnected notifications can be disabled in tray icon -> plugins (or in the Bluetooth Manager -> View -> Plugins) and uncheck "ConnectionNotifier".

Visibility and name of the adapter can be changed by hitting the tray icon -> Adapters (or Settings -> Bluetooth Adapters). If visibility is set to hidden, it can be made temporarily visible by hitting the tray icon and choosing "Make Discoverable".

Audio routing should work automatically. Changing the audio output manually can be done by hitting the speaker icon in the panel, below the volume there should be a choice for the audio route. More Settings are available in Menu -> Multimedia -> PulseAudio Volume Control.

If the tray icon doesn't show up in the panel and the adapter isn't reachable, try if something like the following helps:

  • lsmod | grep bluetooth -> note the name of the device-specific module at the right hand side, starting with "bt...".
  • sudo modprobe -r btqcomsmd -> use the name of the device-specific module
  • sudo modprobe btqcomsmd

For more troubleshooting, see Bluetooth.

For sending files via bluetooth, package bluez-obexd needs to be installed. However, file transfer seems not to work (?).

Keyboard shortcuts

Some can be set in Settings -> Keyboard -> Application Shortcuts and others are at Settings -> Window Manager -> Keyboard.

Additional software

  • gvfs to make the trash can available.
  • gvfs and udisks2 for mounting drives and drive management.
  • Browser: firefox or firefox-esr. For touch usability of firefox, see Xfce4#Firefox. If you need something more lightweight, you can try midori.
  • For opening PDF files, see Xfce4#PDF_viewer.
  • Text editor e.g. mousepad.
  • Image viewer e.g. ristretto.
  • Taking screenshots with xfce4-screenshooter.
  • Task manager: xfce4-taskmanager.
  • Graphical interface for formatting drives or writing images e.g. gnome-disk-utility.
  • alsa-utils to investigate sound issues, it contains commands alsamixer, aplay, arecord, which are helpful.
  • (File searching tool catfish unfortunately isn't packaged in Alpine Linux.)


Default configs of Xfce4 desktop environment are managed in the subproject xfce4-phone.

They go into the package postmarketos-ui-xfce4.