Sway: Difference between revisions

From Alpine Linux
(Move eudev to the top)
 
(118 intermediate revisions by 5 users not shown)
Line 1: Line 1:
Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.
[https://swaywm.org Sway] is a tiling [[Wayland]] compositor and a drop-in replacement for the [[i3wm |i3 window manager]]. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.


== Add a normal user ==
== Prerequisites ==


Use <code>setup-user</code> to add a non-system normal user for running Sway.
* Internet [[Configure_Networking#Connectivity_testing|connectivity]], unless the packages have been pre-fetched into a local cache.
* Install appropriate [[Graphics driver]] drivers for your hardware. Without graphics drivers [[#Video Driver Issues|errors]] are likely to occur.
* A [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]].
* The [[Repositories#Managing_repositories|community repositories must be enabled]].
* Set up [[eudev]].
* Wayland compositors need raw access to input and output devices, typically mediated by a [[seat manager]]. Either [[seatd]] or [[elogind]] work fine, but installing both leads to conflicts.
{{Tip|Except for the first two [[#Prerequisites|prerequisites]], all of the others are automatically handled if the desktop is [[#Setup-desktop|installed using the following setup-desktop]] script.}}


== Set up eudev ==
== Setup-desktop ==


[[eudev]] is recommended and required for the greeter. Or else it will not be able to find any input device (libinput failure).
The [[setup-desktop]] command automates the Sway desktop installation with [[eudev]] and [[elogind]].  


setup-devd udev
{{cmd|# setup-desktop sway}} 


== Install Graphics Drivers ==
Proceed to the [[Sway#Starting Sway|Starting Sway]] section, as no [[Display manager|display manager]] is being installed nor configured by the script that would boot into a graphical login screen.


Graphics drivers:
== Manual Installation ==


* [[Intel Video]]
The installation steps below allow you to pick and choose various components for your Sway desktop.
* [[Radeon Video]]
* [[Nvidia Video]]


== Install seatd ==
=== Install Fonts ===


Install seatd, a minimal seat management daemon. This grants the required permissions to the user running sway:
Install [https://dejavu-fonts.github.io/ DejaVu] fonts ({{Pkg|font-dejavu}}), which have good [https://home.unicode.org/ Unicode] coverage:


apk add seatd
{{cmd|# apk add font-dejavu}} 
=== Install Sway ===


# add seatd to boot run-level, because it must be running before greetd
{{cmd|# apk add sway \
# else greetd will fail to start
    xwayland            \ # if you need the xserver
rc-update add seatd boot
    foot                \ # default terminal emulator. Modify $term in config for a different one.
    wmenu                \ # default Wayland native menu for choosing program and screensharing monitor
    swaylock swaylockd  \ # lockscreen tool
    swaybg              \ # display wallpaper
    grim                \ # screenshot tool
    wl-clipboard        \ # clipboard management
    i3status            \ # simple status bar
    swayidle              # idle management (DPMS) daemon
}}


rc-service seatd start
For complimentary software alternatives, see [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway Sway's wiki] or [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland Gentoo's wiki].
adduser $USER seat


== Install elogind (optional) ==
== Configuration ==


<code>swayidle</code> has integration with <code>elogind</code> and can handle <code>before-sleep</code> events.
=== Sway config file ===


apk add elogind
Copy the default Sway configuration file to {{Path|~/.config/sway/config}} so that it can be customized as per each user's choices:
rc-update add elogind
rc-service elogind start


If using <code>swayidle before-sleep</code>, there will be a race condition, so that when you resume the computer from suspend, the screen shows the contents of the unlocked screen for a second before showing the actual lock screen. This can be a privacy concern, if someone is filming the screen.
{{cmd|$ mkdir -p ~/.config/sway
To solve this issue, do the following:
$ cp /etc/sway/config ~/.config/sway/}}


Create this file <code>/etc/elogind/system-sleep/10-swaylock.sh</code>, then add the following script to this file:
Read through it to learn the default keybindings. Refer to the [[Sway customization guide|Sway customization guide]] as well as the [[#See also|See also]] section for Tips on customizing this config file. Sway's configuration is mostly backward compatible with that of [[I3wm|i3]]'s, and if you are looking for a solution for a specific issue, you could try checking whether it hasn't been provided for the i3 window manager.


#!/bin/sh
For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].
if [ "${1}" == "pre" ]; then
  touch /tmp/swaylock-sleep
  sleep 1
fi


Then set it to executable.
=== PipeWire and Screensharing ===


Later, once sway is installed, add the following line to sway config:
The Sway compositor has no involvement with audio playback. In order for screensharing to work, [[PipeWire]] is required. Therefore, installing [[PipeWire#Installation|PipeWire]] is recommended for audio playback too.


# in ~/.config/sway/config
Since v3.22, Alpine Linux provides the necessary scripts to start PipeWire as a [[OpenRC#user services|user service]] in OpenRC.
exec sh -c "touch /tmp/swaylock-sleep; inotifyd swaylock /tmp/swaylock-sleep"


With this line, the screen will be promptly locked before suspend-to-RAM starts.
From a screensharing perspective, applications are split into two categories:-


== Install greetd (optional) ==
* Those which use the native Wayland [https://wayland.app/protocols/wlr-screencopy-unstable-v1 wlr-screencopy] protocol
* Those which use the API from Flatpak's <code>xdg-desktop-portal</code> (this portal is also used by native non-Flatpak applications).


apk add greetd greetd-gtkgreet cage greetd-openrc
Applications in the first group require no additional setup. Applications in the second group (which include Firefox and Chromium) require setting up ''xdg portals'' in addition to [[PipeWire#Installation|PipeWire]].
rc-update add greetd
adduser greetd seat


In <code>/etc/greetd/config.toml</code>, set
{{Cmd|# apk add xdg-desktop-portal xdg-desktop-portal-wlr}}


<pre>
If you are using a <code>dbus-run-session</code> wrapper to launch Sway, you will also need to set D-Bus variables in order for the portal and for [[#PipeWire and Screensharing|screensharing]] features to work;  add the following line to the beginning of Sway's {{Path|config}} file:
[default_session]


command = "cage -s -- gtkgreet"
exec dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME
</pre>


In <code>/etc/greetd/environments</code>, set
The {{ic|XDG_CURRENT_DESKTOP}} environment variable may be set by various methods, including:-
<pre>
* by amending its mention in that {{ic|dbus-update-activation-environment}} line, editing it to specify {{ic|XDG_CURRENT_DESKTOP{{=}}sway}} ; or
# Launch Sway with a D-Bus server available, use:
* by exporting it from within an applicable environment configuration file, such as:
dbus-run-session -- sway
</pre>


D-Bus is required for PipeWire and screensharing in Firefox and Chromium. Running with <code>dbus-run-session</code> is a convenience wrapper that will explicitly export the path of the session bus.
:{{Cat| $XDG_CONFIG_HOME/.profile|<nowiki>
export XDG_CURRENT_DESKTOP=sway
</nowiki>}}


== Power management ==
:However, this method is not universal, as it would require resetting the {{ic|XDG_CURRENT_DESKTOP}} variable for any different desktop/compositor/window manager that may be launched afterwards, possibly by employing a launcher similar to the wrapper script alternative described for '''Sway''' [[Sway#Automatically_Launch_Sway_on_tty1|below]];  or
* by being set automatically by the display manager, as is commonplace, but none is supplied by '''Sway'''.


Controlling display backlight requires either the proper udev rules, or using some form of privilege escalation.
=== Screen Lock and suspend-to-RAM ===


Putting the system to sleep, requires elevated privileges.
{{Tip| For a seat manager-agnostic and DE-/WM-agnostic tool, consider installing the {{Pkg|zzz}} utility, available in the [[Repositories#Community|community]] repository, or the {{Pkg|powerctl}} utility from the [[Repositories#Testing|testing]] repository, in order to manage suspend and hibernation.}}


For details on configuring <code>doas</code> with <code>elogind</code>, see [[Elogind#Doas]]
For usage of the <Code>loginctl suspend</Code> command, see [[Elogind]].


== Install fonts ==
To put the system to sleep after 600 seconds, use:


Install DejaVu fonts, which has good Unicode coverage:
exec swayidle -w timeout 600 'doas /usr/bin/powerctl mem'


apk add font-dejavu
Do not lock the screen if program is running in full screen:


== Install Sway ==
==== Idle inhibition ====


  apk add sway \
  for_window [app_id="^.*"] inhibit_idle fullscreen
    xwayland            \ # if you need xserver
    foot                \ # default terminal emulator. Modify $term in config for a different one.
    bemenu              \ # wayland native menu for choosing program and screensharing monitor
    swaylock swaylockd  \ # lockscreen tool
    grim                \ # screenshot tool
    wl-clipboard        \ # clipboard management
    i3status            \ # simple status bar
    swayidle              # idle management (DPMS) daemon


For complimentary software alternatives, see for example [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland this list at Gentoo Wiki.]
{{Todo|The option below, related to <Code>wayland-pipewire-idle-inhibit</Code>, needs to be tested. If you find the option below to be working, please remove this Todo.}}


== Configuration ==
If you do not want to lock the screen while media is being played through [[PipeWire]], then install the {{pkg|wayland-pipewire-idle-inhibit}} package, and add the following to Sway's {{Path|config}} file:


Copy default sway configuration to <code>~/.config</code>:
exec wayland-pipewire-idle-inhibit


# as normal user
Make changes to the {{Path|~/.config/wayland-pipewire-idle-inhibit/config.toml}} configuration file or to whichever configuration file you may have referenced instead through the <Code> --config <PATH></Code>, if required, as per the [https://github.com/rafaelrc7/wayland-pipewire-idle-inhibit?tab=readme-ov-file#config project's website].
mkdir -p ~/.config/sway
cp /etc/sway/config ~/.config/sway/


Read through it to learn the default keybindings.
=== Elogind and swayidle ===
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.


For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].
<code>swayidle</code> has integration with <code>elogind</code>, and it can handle ''before-sleep'' events.


== Launch PipeWire and enable screensharing ==
If using <code>swayidle before-sleep</code>, then there will be a race condition, so that when you resume the computer from ''suspend'', the screen will show the contents of the unlocked screen for a second before showing the actual lock screen.  This can be a privacy concern.


For a reasonable desktop experience with support for audio and screensharing, install pipewire, wireplumber and xdg portals:
To solve this issue, do the following.


apk add pipewire pipewire-pulse pipewire-tools
Create the <code>/etc/elogind/system-sleep/10-swaylock.sh</code> file, and then add the following script to this file:
  apk add wireplumber
{{Cat|/etc/elogind/system-sleep/10-swaylock.sh|<nowiki>
  apk add xdg-desktop-portal xdg-desktop-portal-wlr
  #!/bin/sh
  if [ "${1}" == "pre" ]; then
  touch /tmp/swaylock-sleep
  sleep 1
fi
</nowiki>}}


Launch PipeWire with Sway, add the following to sway config:
Then set it to executable.


exec /usr/libexec/pipewire-launcher
Later, once Sway is installed, add the following line to its {{Path|config}} file:


You also need to set DBus variables for the portal and screensharing features to work:
exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep


exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway
With this line, the screen will be promptly locked before ''suspend-to-RAM'' starts.


Replace dmenu (depends on X server) with bemenu (Wayland native) for launching programs and selecting which screen to share in Firefox/Chromium:
=== Brightness Control ===


set $menu bemenu-run | xargs swaymsg exec
Refer to [[Backlight]] for information on brightness control.


== Mouse cursor theme ==
=== Output Scaling for High Resolution Displays ===


Set a mouse cursor, using GNOME Adwaita theme:
Without further configuration, program interfaces may be too small to use on high resolution displays.


seat "*" xcursor_theme Adwaita 16
Sway supports the per-display configuration of:-


== Screen lock and suspend-to-RAM ==
* fractional (e.g. 1.5x);  and
* integer scaling (e.g. 2x)


Set screen lock and suspend-to-RAM:
However, fractional scaling is discouraged due both to the performance impact and to the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT-based toolkit scaling is recommended.  See [[Sway#Toolkit Scaling|See below]].


exec swayidle -w timeout 630 'doas /bin/loginctl suspend'
==== Scaling with wdisplays ====


loginctl suspend command will trigger the screenlock, as mentioned above.
To enable Sway scaling, the user can first preview different scaling factors with the {{Pkg|wdisplays}} package.  Note the output name (''eDP-1'', ''LVDS-1'') and try apply scaling factors such as 1 and 2.  To make changes permanent, add the following line, completed with your settings, to Sway's {{Path|config}} file.


Do not lock the screen if program is running in full screen:
<pre>
output <name> scale <factor>
</pre>


for_window [app_id="^.*"] inhibit_idle fullscreen
==== Toolkit Scaling ====


== Brightness control ==
To use toolkit scaling, say, at x2, add the following, for instance, to your {{Path|~/.profile}}:


Use brightnessctl. Configure permission in doas config. Optionally enable brightnessctl service to restore brightness settings on reboot:
  # for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE{{=}}2


  rc-update add brightnessctl
  # for QT-based programs
export QT_WAYLAND_FORCE_DPI{{=}}"physical"
# or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI{{=}}192 # 2x scaling
export QT_QPA_PLATFORM{{=}}"wayland-egl"


== Output scaling for high resolution displays ==
=== Notification Daemon ===


Without further configuration, program interfaces might be too small to use on high resolution displays.
[[mako]] is a lightweight notification daemon that works seamlessly with Sway.  


Sway supports the per-display configuration of
=== Screenshots ===


* fractional (e.g., 1.5x), and
A simple tool that works well under Wayland is {{pkg|grimshot}}. Example keybindings:-
* integer scaling (e.g., 2x)
 
However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended. See below.
 
To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package.  Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2.  To make changes permanent, add


<pre>
<pre>
output <name> scale <factor>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>
</pre>


to ~/.config/sway/config.
See Sway's [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway wiki article] for a listing of further screenshot tools.


To use toolkit scaling, use
=== Make Clipboard Content Persistent ===
{{Cmd|# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE{{=}}2
 
<nowiki>#</nowiki> for QT-based programs
export QT_WAYLAND_FORCE_DPI{{=}}"physical"
<nowiki>#</nowiki> or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI{{=}}192 # 2x scaling
export QT_QPA_PLATFORM{{=}}"wayland-egl"
}}


== Make clipboard content persistent ==
By default, the clipboard content does not persist after terminating the program: if you copy some text from Firefox and then exit Firefox, then the copied text is also lost.
By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.


Install clipman from testing repo and add the following to sway config:
Install {{Pkg|clipman}} from the community repo, and then add the following to Sway's {{Path|config}} file:


<pre>
<pre>
Line 207: Line 201:
</pre>
</pre>


== Firefox picture-in-picture mode/floating windows ==
=== Firefox Picture-in-Picture Mode/Floating Windows ===
Add this to your sway config file (modify the numeric values to suit your needs and your display):
 
Add this to your Sway configuration file (modify the numeric values to suit your needs and your display):
 
<pre>
<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>
</pre>


== Screenshots ==
=== Start with NumLock Enabled ===
A simple tool that works well under Wayland is Grimshot. Example keybindings:
 
<pre>
Add the following to your Sway {{Path|config}} file:
bindsym Print exec grimshot copy area
 
bindsym Shift+Print exec grimshot copy screen
input type:keyboard xkb_numlock enabled
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
 
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
=== Change mouse cursor theme and size ===
</pre>
 
Add to your Sway {{Path|config}} file:
 
seat seat0 xcursor_theme my_cursor_theme my_cursor_size
 
For example, set a mouse cursor using the '''GNOME Adwaita''' theme:


See [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the sway wiki's article] for a list of screenshot tools.
seat seat0 xcursor_theme Adwaita 16


== Start with NumLock enabled ==
You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your configuration does not result in change, try logging out and in.
Add this to your sway config file:
<code>input type:keyboard xkb_numlock enabled</code>


== Change cursor theme and size ==
{{Note|Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}
Add to your sway config:
<pre>
seat seat0 xcursor_theme my_cursor_theme my_cursor_size
</pre>
You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.
{{Note|Wayland uses client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}


=== Custom Keyboard Layout ===


== Custom keyboard layout ==
To use a custom keyboard layout, just use:


To use custom keyboard layout, just use
<pre>
<pre>
input type:keyboard {
input type:keyboard {
Line 246: Line 239:
</pre>
</pre>


== Default font ==
=== Flatpaks ===
 
{{main|Flatpak}}


This is not related to Sway, but still nice to have: change system wide default font selection.  In <code>/etc/fonts/conf.d/52-my-default-fonts.conf</code>, set
As mentioned in [[Flatpak#Portals|Flatpak]] page, install the minimal required portal related packages i.e {{pkg|xdg-desktop-portal}}, {{pkg|xdg-desktop-portal-gtk}} and {{pkg|xdg-desktop-portal-wlr}}. After installing the packages, add the following to the ''autostart'' section in your Sway {{Path|config}} file to avoid [[Flatpak#GDBus_Error|GDBus errors]].
<pre>
<pre>
<?xml version='1.0'?>
exec /usr/libexec/xdg-desktop-portal
<!DOCTYPE fontconfig SYSTEM 'urn:fontconfig:fonts.dtd'>
exec /usr/libexec/xdg-desktop-portal-gtk
<fontconfig>
exec /usr/libexec/xdg-desktop-portal-wlr
  <!-- Default fonts -->
  <alias binding="same">
    <family>sans-serif</family>
    <prefer>
      <family>DejaVu Sans</family>
    </prefer>
  </alias>
  <alias binding="same">
    <family>serif</family>
    <prefer>
      <family>DejaVu Serif</family>
    </prefer>
  </alias>
  <alias binding="same">
    <family>monospace</family>
    <prefer>
      <family>DejaVu Sans Mono</family>
    </prefer>
  </alias>
</fontconfig>
</pre>
</pre>
You can obtain a list of installed fonts with <code>fc-list</code>.


These startup instructions are only needed, if these are not started automatically via other means.
== Starting Sway ==
=== Manually Launch Sway ===
You can launch Sway manually by issuing the <Code>sway</Code> command from a TTY.
{{Cmd|$ sway}}
{{Tip|When using [[Wayland]], for [[PipeWire]] and screensharing to work in Firefox and Chromium, a [[D-Bus]] is required. In the absence of a [[OpenRC#User_services|user service manager]], consider running <Code>sway</Code> with <code>dbus-run-session</code>, a convenient wrapper that will explicitly export the path of the session bus.{{Cmd|$ dbus-run-session sway}}
}}
=== Automatically Launch Sway on tty1 ===
Adding the following lines to {{Path|~/.profile}} or to its equivalent will ensure that <Code>sway</Code> launches automatically, with a D-Bus, ''only'' from ''tty1''.  This is handy for troubleshooting, because if the Sway configuration ever falters, one could troubleshoot by logging into a different TTY (''tty2''-''tty6''), and your startup script then will not attempt to launch the faulty Sway environment from there also.
{{Cat| ~/.profile|<nowiki>
...
if [ "$(tty)" = "/dev/tty1" ]; then
    exec dbus-run-session sway
fi
...</nowiki>}}
=== Using a Wrapper Script to Launch Sway ===
Instead of using {{Path|~/.profile}} or its equivalent file, a [https://man.sr.ht/~kennylevinsen/greetd/#how-to-set-xdg_session_typewayland wrapper script] can be placed at {{Path|/usr/local/bin/sway-run}}. This script can be used to launch <Code>sway</Code> from either a TTY or by [[greetd]], a lightweight [[Display manager|display manager]], as follows: {{Cat|/usr/local/bin/sway-run|<nowiki>#!/bin/sh
# Session
export XDG_SESSION_TYPE=wayland
export XDG_SESSION_DESKTOP=sway
export XDG_CURRENT_DESKTOP=sway
# Wayland stuff
export MOZ_ENABLE_WAYLAND=1
export QT_QPA_PLATFORM=wayland
export SDL_VIDEODRIVER=wayland
export _JAVA_AWT_WM_NONREPARENTING=1
# Launch Sway with a D-Bus server
exec dbus-run-session sway "$@" </nowiki>}}
Make the file executable:
{{Cmd|# chmod +x /usr/local/bin/sway-run}}


== Troubleshooting ==
== Troubleshooting ==


If you encounter any issues, try running <code>sway -Vc /etc/sway/config</code>. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).  
If you encounter any issues, try running <Code>sway -Vc /etc/sway/config</Code>. It will run <Code>sway</Code> with the default config file and set the output to be more verbose. It is generally a good idea to track your configuration files with ''git'' (if and when you use a remote repository for them, keep it private, for security reasons).  


== Flatpaks ==
To capture the Sway error log in a file for troubleshooting, replace <code>sway</code> in your startup file by:
{{main|Flatpak}}
 
Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.
sway -d 2> ~/sway_error.log
 
Alternatively, you can also issue the below command from TTY.
 
{{Cmd|$ sway -d 2> ~/sway_error.log}}  
 
=== Video Driver Issues ===
 
After installing Sway, and while launching it for the first time, a lack of appropriate [[#Install Graphics Drivers|video drivers]] may cause various error messages such as:
 
* "unable to create backend"
* "Failed to create renderer"
 
Install the necessary drivers in order for your [[#Install Graphics Drivers|graphics card]] to work with Sway.  
 
=== XDG_RUNTIME_DIR is not set in the environment. Aborting ===
 
If [[seatd]] is used instead of [[elogind]], the error message '''XDG_RUNTIME_DIR is not set in the environment. Aborting''' might be encountered.
 
Ensure that the mandatory steps outlined in the [[Seatd]] wiki page are completed in order to set the [[XDG_RUNTIME_DIR]] variable.
 
=== No backend was able to open a seat ===
 
If no [[seat manager]] is available, then the error below will appear.
 
<Pre>
[libseat] [libseat/libseat.c:73] libseat_open_seat : No backend was able to open a seat
[backend/session/libseat.c:102] Unable to create seat : Function not implemented
[backend/backend.c:303] Failed to open any DRM device
[sway/server.c:49] Unable to create backend
</Pre>
 
Ensure that either [[Elogind]] or [[Seatd]] is properly configured and running.  


After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
=== Firefox (Flatpak) and/or GTK Apps ===
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
</pre>


This is only needed if they are not started automatically via other means.
==== Disappearing Cursor ====


== Firefox (Flatpak) and/or GTK apps ==
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively, one could install an [https://pkgs.alpinelinux.org/packages?name=*-icon-theme&branch=edge&repo=&arch=x86_64&origin=&flagged=&maintainer= icon theme] package for all users.
=== Disappearing cursor ===
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme      for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.


=== Missing file picker/cannot download ===
==== Missing file picker/cannot download ====


Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.
Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.


== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ==
=== Nvidia Issues ===
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').
 
== Sway socket not detected ==


See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[tmux]]
{{Draft|This section is partly outdated and could benefit from contributions in view of Nvidia's [https://docs.nvidia.com/drive/drive-os-5.2.3.0L/drive-os/index.html#page/DRIVE_OS_Linux_SDK_Development_Guide/Windows%20Systems/window_system_wayland.html current support] of Wayland. Help is encouraged.}}
{{Main|NVIDIA}}
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your <Code>WLR_BACKENDS</Code> environmental variables to <code>drm,libinput</code> or <code>x11</code> (add {{Pkg|libinput}} here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install {{Pkg|libinput}} first''').


== See also ==


== See Also ==
* [https://github.com/swaywm/sway/wiki/ Sway Wiki]
* [https://wiki.archlinux.org/title/Sway Archwiki]
* [https://wiki.archlinux.org/title/Sway Archwiki]
* [https://wiki.gentoo.org/wiki/Sway Gentoo Wiki]
* [https://wiki.gentoo.org/wiki/Sway Gentoo Wiki]
* [https://wiki.postmarketos.org/wiki/Sway PostmarketOS Wiki]
* [https://wiki.postmarketos.org/wiki/Sway PostmarketOS Wiki]


[[Category:Desktop]]
[[Category:Compositor]]
[[Category:Window Managers]]
[[Category:Wayland]]

Latest revision as of 04:14, 15 October 2025

Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.

Prerequisites

Tip: Except for the first two prerequisites, all of the others are automatically handled if the desktop is installed using the following setup-desktop script.

Setup-desktop

The setup-desktop command automates the Sway desktop installation with eudev and elogind.

# setup-desktop sway

Proceed to the Starting Sway section, as no display manager is being installed nor configured by the script that would boot into a graphical login screen.

Manual Installation

The installation steps below allow you to pick and choose various components for your Sway desktop.

Install Fonts

Install DejaVu fonts (font-dejavu), which have good Unicode coverage:

# apk add font-dejavu

Install Sway

# apk add sway \ xwayland \ # if you need the xserver foot \ # default terminal emulator. Modify $term in config for a different one. wmenu \ # default Wayland native menu for choosing program and screensharing monitor swaylock swaylockd \ # lockscreen tool swaybg \ # display wallpaper grim \ # screenshot tool wl-clipboard \ # clipboard management i3status \ # simple status bar swayidle # idle management (DPMS) daemon

For complimentary software alternatives, see Sway's wiki or Gentoo's wiki.

Configuration

Sway config file

Copy the default Sway configuration file to ~/.config/sway/config so that it can be customized as per each user's choices:

$ mkdir -p ~/.config/sway $ cp /etc/sway/config ~/.config/sway/

Read through it to learn the default keybindings. Refer to the Sway customization guide as well as the See also section for Tips on customizing this config file. Sway's configuration is mostly backward compatible with that of i3's, and if you are looking for a solution for a specific issue, you could try checking whether it hasn't been provided for the i3 window manager.

For additional information, start at man 5 sway and read the upstream wiki.

PipeWire and Screensharing

The Sway compositor has no involvement with audio playback. In order for screensharing to work, PipeWire is required. Therefore, installing PipeWire is recommended for audio playback too.

Since v3.22, Alpine Linux provides the necessary scripts to start PipeWire as a user service in OpenRC.

From a screensharing perspective, applications are split into two categories:-

  • Those which use the native Wayland wlr-screencopy protocol
  • Those which use the API from Flatpak's xdg-desktop-portal (this portal is also used by native non-Flatpak applications).

Applications in the first group require no additional setup. Applications in the second group (which include Firefox and Chromium) require setting up xdg portals in addition to PipeWire.

# apk add xdg-desktop-portal xdg-desktop-portal-wlr

If you are using a dbus-run-session wrapper to launch Sway, you will also need to set D-Bus variables in order for the portal and for screensharing features to work; add the following line to the beginning of Sway's config file: 

exec dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME

The XDG_CURRENT_DESKTOP environment variable may be set by various methods, including:-

  • by amending its mention in that dbus-update-activation-environment line, editing it to specify XDG_CURRENT_DESKTOP=sway ; or
  • by exporting it from within an applicable environment configuration file, such as:

Contents of $XDG_CONFIG_HOME/.profile

export XDG_CURRENT_DESKTOP=sway
However, this method is not universal, as it would require resetting the XDG_CURRENT_DESKTOP variable for any different desktop/compositor/window manager that may be launched afterwards, possibly by employing a launcher similar to the wrapper script alternative described for Sway below; or
  • by being set automatically by the display manager, as is commonplace, but none is supplied by Sway.

Screen Lock and suspend-to-RAM

Tip: For a seat manager-agnostic and DE-/WM-agnostic tool, consider installing the zzz utility, available in the community repository, or the powerctl utility from the testing repository, in order to manage suspend and hibernation.

For usage of the loginctl suspend command, see Elogind.

To put the system to sleep after 600 seconds, use: 

exec swayidle -w timeout 600 'doas /usr/bin/powerctl mem'

Do not lock the screen if program is running in full screen:

Idle inhibition

for_window [app_id="^.*"] inhibit_idle fullscreen
Todo: The option below, related to wayland-pipewire-idle-inhibit, needs to be tested. If you find the option below to be working, please remove this Todo.


If you do not want to lock the screen while media is being played through PipeWire, then install the wayland-pipewire-idle-inhibit package, and add the following to Sway's config file: 

exec wayland-pipewire-idle-inhibit

Make changes to the ~/.config/wayland-pipewire-idle-inhibit/config.toml configuration file or to whichever configuration file you may have referenced instead through the --config <PATH>, if required, as per the project's website.

Elogind and swayidle

swayidle has integration with elogind, and it can handle before-sleep events.

If using swayidle before-sleep, then there will be a race condition, so that when you resume the computer from suspend, the screen will show the contents of the unlocked screen for a second before showing the actual lock screen. This can be a privacy concern.

To solve this issue, do the following.

Create the /etc/elogind/system-sleep/10-swaylock.sh file, and then add the following script to this file:

Contents of /etc/elogind/system-sleep/10-swaylock.sh

#!/bin/sh if [ "${1}" == "pre" ]; then touch /tmp/swaylock-sleep sleep 1 fi

Then set it to executable.

Later, once Sway is installed, add the following line to its config file: 

exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep

With this line, the screen will be promptly locked before suspend-to-RAM starts.

Brightness Control

Refer to Backlight for information on brightness control.

Output Scaling for High Resolution Displays

Without further configuration, program interfaces may be too small to use on high resolution displays.

Sway supports the per-display configuration of:-

  • fractional (e.g. 1.5x); and
  • integer scaling (e.g. 2x)

However, fractional scaling is discouraged due both to the performance impact and to the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT-based toolkit scaling is recommended. See See below.

Scaling with wdisplays

To enable Sway scaling, the user can first preview different scaling factors with the wdisplays package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add the following line, completed with your settings, to Sway's config file. 

output <name> scale <factor>

Toolkit Scaling

To use toolkit scaling, say, at x2, add the following, for instance, to your ~/.profile: 

# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE=2

# for QT-based programs
export QT_WAYLAND_FORCE_DPI="physical"
# or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI=192 # 2x scaling
export QT_QPA_PLATFORM="wayland-egl"

Notification Daemon

mako is a lightweight notification daemon that works seamlessly with Sway.

Screenshots

A simple tool that works well under Wayland is grimshot. Example keybindings:- 

bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png

See Sway's wiki article for a listing of further screenshot tools.

Make Clipboard Content Persistent

By default, the clipboard content does not persist after terminating the program: if you copy some text from Firefox and then exit Firefox, then the copied text is also lost.

Install clipman from the community repo, and then add the following to Sway's config file: 

exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"

Firefox Picture-in-Picture Mode/Floating Windows

Add this to your Sway configuration file (modify the numeric values to suit your needs and your display): 

for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none

Start with NumLock Enabled

Add the following to your Sway config file: 

input type:keyboard xkb_numlock enabled

Change mouse cursor theme and size

Add to your Sway config file: 

seat seat0 xcursor_theme my_cursor_theme my_cursor_size

For example, set a mouse cursor using the GNOME Adwaita theme: 

seat seat0 xcursor_theme Adwaita 16

You can inspect their values with echo $XCURSOR_SIZE and echo $XCURSOR_THEME. If reloading your configuration does not result in change, try logging out and in.

Note: Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of $XCURSOR_SIZE and $XCURSOR_THEME.

Custom Keyboard Layout

To use a custom keyboard layout, just use: 

input type:keyboard {
  xkb_file /path/to/my/custom/layout
}

Flatpaks

Main article: Flatpak

As mentioned in Flatpak page, install the minimal required portal related packages i.e xdg-desktop-portal, xdg-desktop-portal-gtk and xdg-desktop-portal-wlr. After installing the packages, add the following to the autostart section in your Sway config file to avoid GDBus errors. 

exec /usr/libexec/xdg-desktop-portal
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr

These startup instructions are only needed, if these are not started automatically via other means.

Starting Sway

Manually Launch Sway

You can launch Sway manually by issuing the sway command from a TTY.

$ sway

Tip: When using Wayland, for PipeWire and screensharing to work in Firefox and Chromium, a D-Bus is required. In the absence of a user service manager, consider running sway with dbus-run-session, a convenient wrapper that will explicitly export the path of the session bus.

$ dbus-run-session sway

Automatically Launch Sway on tty1

Adding the following lines to ~/.profile or to its equivalent will ensure that sway launches automatically, with a D-Bus, only from tty1. This is handy for troubleshooting, because if the Sway configuration ever falters, one could troubleshoot by logging into a different TTY (tty2-tty6), and your startup script then will not attempt to launch the faulty Sway environment from there also.

Contents of ~/.profile

... if [ "$(tty)" = "/dev/tty1" ]; then exec dbus-run-session sway fi ...

Using a Wrapper Script to Launch Sway

Instead of using ~/.profile or its equivalent file, a wrapper script can be placed at /usr/local/bin/sway-run. This script can be used to launch sway from either a TTY or by greetd, a lightweight display manager, as follows:

Contents of /usr/local/bin/sway-run

#!/bin/sh # Session export XDG_SESSION_TYPE=wayland export XDG_SESSION_DESKTOP=sway export XDG_CURRENT_DESKTOP=sway # Wayland stuff export MOZ_ENABLE_WAYLAND=1 export QT_QPA_PLATFORM=wayland export SDL_VIDEODRIVER=wayland export _JAVA_AWT_WM_NONREPARENTING=1 # Launch Sway with a D-Bus server exec dbus-run-session sway "$@"

Make the file executable:

# chmod +x /usr/local/bin/sway-run

Troubleshooting

If you encounter any issues, try running sway -Vc /etc/sway/config. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your configuration files with git (if and when you use a remote repository for them, keep it private, for security reasons).

To capture the Sway error log in a file for troubleshooting, replace sway in your startup file by: 

sway -d 2> ~/sway_error.log

Alternatively, you can also issue the below command from TTY.

$ sway -d 2> ~/sway_error.log

Video Driver Issues

After installing Sway, and while launching it for the first time, a lack of appropriate video drivers may cause various error messages such as:

  • "unable to create backend"
  • "Failed to create renderer"

Install the necessary drivers in order for your graphics card to work with Sway.

XDG_RUNTIME_DIR is not set in the environment. Aborting

If seatd is used instead of elogind, the error message XDG_RUNTIME_DIR is not set in the environment. Aborting might be encountered.

Ensure that the mandatory steps outlined in the Seatd wiki page are completed in order to set the XDG_RUNTIME_DIR variable.

No backend was able to open a seat

If no seat manager is available, then the error below will appear. 

[libseat] [libseat/libseat.c:73] libseat_open_seat : No backend was able to open a seat
[backend/session/libseat.c:102] Unable to create seat : Function not implemented
[backend/backend.c:303] Failed to open any DRM device
[sway/server.c:49] Unable to create backend

Ensure that either Elogind or Seatd is properly configured and running.

Firefox (Flatpak) and/or GTK Apps

Disappearing Cursor

You may need to get an icon pack and possibly a theme from Pling store and set GTK_THEME environmental variable. Alternatively, one could install an icon theme package for all users.

Missing file picker/cannot download

Go to about:config and set widget.use-xdg-desktop-portal.file-picker to 0.

Nvidia Issues

This material is work-in-progress ...

This section is partly outdated and could benefit from contributions in view of Nvidia's current support of Wayland. Help is encouraged.
(Last edited by Prabuanand on 15 Oct 2025.)


Main article: NVIDIA

As of Dec 31 2022, Nvidia still doesn't fully support Wayland. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to drm,libinput or x11 (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards (make sure to install libinput first).

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Sway&oldid=31234"