(One intermediate revision by one other user not shown)
Line 47:
Line 47:
== Configuration ==
== Configuration ==
===Sway config File ===
=== Sway config file ===
Copy the default Sway configuration file to {{Path|~/.config/sway/config}} so that it can be customized as per each user's choices:
Copy the default Sway configuration file to {{Path|~/.config/sway/config}} so that it can be customized as per each user's choices:
Line 54:
Line 54:
$ cp /etc/sway/config ~/.config/sway/}}
$ cp /etc/sway/config ~/.config/sway/}}
Read through it to learn the default keybindings.
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.
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.
====Quickstart - config File====
To set up an environment that launches applications full-sized and to {{Key|Alt}}+{{Key|Tab}} between these much as in [[Xfce|XFCE]] or in various other desktop environments, then a quick setup of the {{Path|config}} file could effect this. This proposed setup may be of benefit for both desktop/non-technical and technical use. ''Step 4'' is indicated to be sidestepped by those electing an {{Pkg|i3}}-style, tiled default layout.
A launchbar is not set up "out of the box", nor here, so this section only reviews essential ''keybindings'' (or "shortcuts"), saving first-time users from immediately requiring to digest a longer ''"cheatsheet"'' of keybindings that might include resizing, moving and swapping windows (called ''"views"''), say, from smaller tiles (called ''"containers"'') into larger tiles; these may be learned at a later stage.
The quickstart configuration of the {{Path|config}} file ''may be prepared within or without '''Sway''''' e.g. within an '''Xorg''' session or another compositor, or on another installation, before eventually copying over the finished {{Path|config}} file onto the target system – except:
* If one prefers alternative applications to those proposed initially in ''Step 6'' for assignment into specific workspaces. Any such modifications (to be executed in ''Step 7'') could be performed: (a) simply during one's first '''Sway''' session; or (b) by determining what those applications' {{ic|app_id}} / {{ic|class}} are (as detailed in ''Step 7''), possibly in another '''Wayland''' session or externally e.g. from documentation.
* One will likewise require to verify at some point whether one's chosen applications are installed on the target system; and to install those missing (last step, ''Step 12'').
'''''Step 1:'' Assign the main modifier key'''. In a text editor, open the {{Path|/home/<var>username</var>/.config/sway/config}} file that had been copied over. We will declare what would be the main modifier key for many of our keybindings: {{Key|Window}}, {{Key|Alt}} or otherwise. The {{Path|config}} file has already set the main modifier, called the {{ic|$mod}} key, to default as the {{ic|Mod4}} key, also known as the {{Key|Window}}, {{ic|Super}} or ''Logo'' key. Verify this towards the beginning of the file:
<Pre>
# Logo key. Use Mod1 for Alt.
set $mod Mod4
</Pre>
As proposed there, one could change that {{ic|$mod}} key to be the {{Key|Alt}} key a.k.a. the {{ic|Mod1}} key. To change the {{ic|$mod}} key assignment, as with any line in this file, one could edit/delete the lines or comment such line out i.e. add a hashtag ('''''#''''') at the start of any line that does not begin with a hashtag, so that such line would not be executed by '''Sway''' but would be left there for reference; and then enter the customised version of that line below it. Note that '''Sway''' [https://github.com/swaywm/sway/wiki#comments does not support] comments at the end of an executable line, following a hashtag.
According to the {{ic|man 5 sway}} page, ''XKB modifier names'' can be used to refer to modifier keys, plus certain aliases found among the following list, all of these "{{ic|codes}}" being acceptable for use throughout the configuration file:
* {{ic|Mod1}} - {{Key|Alt}} - Alternatively expressed as {{ic|Alt}};
* {{ic|Mod2}} - Although not universally mapped, here it refers to the {{Key|Num Lock}} key;
* {{ic|Mod3}} - It could be programmed, as an XKB modifier key;
* {{ic|Mod4}} - Alternatively expressed as the {{ic|Super}} key, a.k.a. the {{Key|Window}} or ''Logo'' key;
* {{ic|Mod5}} - {{Key|AltGr}};
* {{ic|Lock}} - {{Key|Caps Lock}};
* {{ic|Control}} - {{Key|Ctrl}} - Alternatively expressed as {{ic|Ctrl}}; and
* {{ic|Shift}} - {{Key|Shift}}.
It might be best not to use the {{Key|Ctrl}} key as the ''main modifier'', as it is often used in applications e.g. {{Key|Control}}+{{Key|c}} to ''copy'', {{Key|Control}}+{{Key|b}} for ''bold'', etc. Similarly when considering the {{ic|Shift}} as main modifier.
So, if one were to choose, say, the {{Key|Alt}} key as the main modifier, that {{ic|Mod4}} line could be changed to: {{ic|set $mod Alt}} or {{ic|set $mod Mod1}}. We will preserve the default, {{ic|Mod4}} ({{Key|Window}}), as the main modifier. Note that any modification will not be manifested until one chooses at any time to reload the {{Path|config}} file by hitting {{ic|$mod+Shift+c}} (cf. ''Step 10'').
'''''Step 2:'' Declare what your default terminal and menu launcher will be'''. In this {{Path|config}} file, these are currently configured to be the {{Pkg|foot}} terminal; and {{Pkg|wmenu}}, which supplies the {{ic|wmenu-run}} command:
<Pre>
# Your preferred terminal emulator
set $term foot
# Your preferred application launcher
set $menu wmenu-run
</Pre>
You could leave these 'as is' if you are happy with these selections. Otherwise, substitute any of them.
A word to the wise regarding one's initial choice of ''terminal'' ''if not currently running '''Sway''''': if a different terminal were to be chosen, then one would not be able to {{Key|Alt}}+{{Key|Tab}} back and forth from a launched '''foot''' terminal into other opened workspaces unless that terminal's {{ic|app_id}} / {{ic|class}} could somehow be determined and specified by the user in ''Step 7''. It may be more suitable therefore to leave '''foot''' as the default terminal until one of these could be determined once a '''Sway''' session is run, so that the terminal ('''foot''') would land in a specified workspace when launched, and then easily {{Key|Alt}}+{{Key|Tab}} to and from it. Alternatively, one could left-click on the chosen terminal's workspace button on the top {{Pkg|swaybar}} in order to switch to that workspace. (Note also that '''foot''' would already be installed if '''Sway''' had been installed using {{ic|$ doas setup-desktop sway}}). On the other hand, ''if one is currently running '''Sway''''', then it is straightforward to change this default terminal choice here, if so wished; a tweak for the preferred terminal could be made in ''Step 7''.
One's choice of menu launcher here is more flexible, regardless of the compositor/window manager currently being used, as the launcher will appear in any workspace currently displayed on-screen – a.k.a. the workspace ''in focus'' – using the keybinding declared in the following step (''Step 3''). Insert the preferred launcher's launch command here. For example, one may prefer {{Pkg|rofi}} over '''wmenu'''; Alpine Linux's '''rofi''' port now supports '''Wayland''', just as [https://github.com/davatorium/rofi rofi's mainline version] officially has since 2025. If so, that {{ic|set $menu wmenu-run}} line could be changed as follows:
<Pre>
set $menu '/usr/bin/rofi -combi-modi run,drun,window,filebrowser -show combi -sort'
</Pre>
With that menu instruction, whenever '''rofi''' is launched using the keybinding reviewed in the next step, it would first offer a ''combi'' (combination) menu of all packages and of <code>.desktop</code> files that match the the command name while it is being typed in; alternatively, one could follows this on by hitting {{Key|Control}}+{{Key|Tab}}, which in turn would offer (a) a ''drun'' menu (a launcher strictly of <code>.desktop</code> files); (b) a listing of opened ''"window"''/view selections; or (c) a simple ''filebrowser'', etc.
A tally of the chosen packages is being kept for any required installation later.
'''''Step 3:'' Choose key combinations to open the terminal and launcher and others'''. From the configuration file:
<Pre>
bindsym $mod+Return exec $term
[...]
bindsym $mod+d exec $menu
</Pre>
Modify these keybindings if so wished, which refer to the terminal and application launcher chosen in ''Step 2''. Ensure that any different chosen key combination(s) has/have not already been assigned elsewhere in this {{Path|config}} file. Make note of your chosen terminal and menu keybindings so as to know how to launch them later. As it stands:
* {{Key|Window}}+{{Key|Return}} for your terminal;
* {{Key|Window}}+{{Key|m}} for your menu launcher;
Substitute the {{Key|Window}} key for your assigned {{ic|$mod}} key, or with any other chosen combination that has not been used elsewhere in the configuration file.
Keybindings may also be made without requiring to define applications as variables that use the {{ic|set}} instruction and the {{ic|$}} variable prefix. For example, having ensured that there was no previous binding for {{ic|Control+Alt+w}}, one could add the following keybinding:
'''''Step 4:'' Applications to launch full-sized and in tabbed layout (Optional)'''. At the beginning of the {{ic|# Layout stuff:}} section, Consider inserting:
<Pre>
workspace_layout tabbed
</Pre>
Then, each launched application will launch full-sized. Each application will be named in a tab.
If opting for a default tiled layout, this step is omitted. Tiling sends applications by default into tiles/"containers", splitting the screen, unless assigned to different workspaces in ''Steps 6-7''. A further alternative would be: {{ic|workspace_layout stacking}}.
'''''Step 5:'' Focus when launched (Optional)'''. Make '''Sway''' to immediately focus on any newly-opened application. At the end of the {{ic|# Workspaces:}} section in this {{Path|config}} file, consider adding:
<Pre>
for_window [app_id=.*] focus
</Pre>
This may be suitable to avoid having to navigate to its tab/workspace. It also ensures that dialog boxes such as ''"Open ..."'' and ''"Save as..."'' appear in the currently focused workspace.
'''''Step 6:'' Assign workspaces'''. This is proposed for your most oftenly-used applications, so that most applications will land into different workspaces, and then one could {{Key|Alt}}+{{Key|Tab}} between those applications/workspaces.
Consider copying and pasting the following model in this same {{ic|# Workspaces:}} passage. Customise each line for user preferences. These specify the {{ic|app_id}} for various applications, including that of the {{Pkg|keepassxc}} password vault, the lean {{Pkg|corepad}} text editor and {{Pkg|okular}} pdf viewer. Then, one finishes off each line with a chosen workspace number. (There may be no documented upper limit of workspaces, but one would need two keystrokes to move applications into two-digit workspaces if and when such keybindings were eventually learned and used.)
<Pre>
# APPLICATIONS TO APPEAR IN SPECIFIC WORKSPACES
assign [app_id="foot"] 1
assign [app_id="chromium"] 2
assign [app_id="org.keepassxc.KeePassXC"] 3
assign [app_id="cc.cubocore.CorePad"] 4
assign [app_id="libreoffice-writer"] 5
assign [app_id="libreoffice-calc"] 6
assign [app_id="org.kde.okular"] 7
assign [app_id="thunar"] 8
</Pre>
One could use workspace names instead of numbers, but then one would need to change their instances in the default {{Path|config}} file. Some applications, not listed here, may require identification by their {{ic|class}} name instead of by {{ic|app_id}} – particularly, some that were originally designed for '''X11''' (such as '''xterm''') – see ''Step 6''. '''Sway''' supplies the {{ic|swaymsg}} command that could determine the {{ic|app_id}} and/or {{ic|class}} name of one's chosen applications.
{{Tip|The '''keepassxc''' password vault is assigned to appear in a different workspace than the '''chromium''' browser. After both are launched, then one would be able to {{Key|Alt}}+{{Key|Tab}} between the two workspaces to fetch/paste password data without engaging a browser password extension, if preferred.}}
If alternative applications are to be assigned workspaces, proceed to the next step.
'''''Step 7:'' Assign alternative application choices for specific workspaces (Optional)'''. This may require being run in a '''Sway''' session. ''If not currently running Sway'', then consider conserving whichever part of the code block in ''Step 6'' that is applicable for user purposes in the configuration file and resuming this ''Step 7'' once the first '''Sway''' session is run.
This step may succeed alternatively in a different '''Wayland''' compositor provided that: (a) '''Sway''' or {{Pkg|sway-bash-completion}} has been installed, seeing how either supply the required {{ic|swaymsg}} command; or (b) one has a different means of determining the {{ic|app_id}} / {{ic|class}} of the alternative application(s).
<ol start="1">
<li> Launch the alternative applications that are to be assigned to workspaces.</li>
<li> Run {{ic|<nowiki>swaymsg -t get_tree | grep "app_id"</nowiki>}} in a terminal. The command examines metadata for your opened windows, and the result is then whittled down (or ''"grepped"'') to display {{ic|app_id}} values. For example: </li>
<pre> $ swaymsg -t get_tree | grep "app_id"
"app_id": "Alacritty",
"app_id": "firefox-esr",
"app_id": "librewolf",
"app_id": "pavucontrol-qt",
"app_id": "featherpad",
"app_id": "audacious",
"app_id": "org.gnome.Epiphany",
"app_id": "org.qutebrowser.qutebrowser",
</pre></ol>
<ol start="3">
<li> Plug the {{ic|app_id}} values for any preferred applications into the {{ic|assign}} listings code block above; end each line with a chosen workspace number.</li>
<li> In case any application name did not appear with an {{ic|app_id}}, then it is possible that the application was originally designed for '''Xorg''' and has not been fully adapted for ''"pure '''Wayland'''"'': for example, {{Pkg|xterm}}. In that case, one would need to determine what its {{ic|class}} is instead: ''with {{Pkg|xwayland}} installed and not disabled'' in '''Sway''', launch '''xterm'''; then, in a terminal, run:</li>
<pre>
$ swaymsg -t get_tree | grep "class"
"class": "XTerm",
</pre>
<li>Determine the {{ic|class}} values for the remainder of the preferred applications that required {{ic|class}} identifiers instead of {{ic|app_id}} and create lines for them in the {{ic|assign}} code block above. For instance, for '''xterm''' to land in workspace 9, add a line to specify its ''class'' and its assigned workspace ''number'':
<pre>
assign [class="XTerm"] 9
</pre><li>
</ol>
'''''Step 8:'' Navigating between applications in different workspaces'''. Tell '''Sway''' what will be the chosen way to ''tab back'' through the workspaces that contain launched applications on a single monitor, say, {{Key|Alt}}+{{Key|Tab}}. In the {{ic|# Moving around:}} passage, consider adding:-
<Pre>
bindsym Alt+Tab workspace prev_on_output
bindsym Super+Tab workspace next_on_output
</Pre>
We have additionally assigned {{Key|Super}}+{{Key|Tab}} to tab ''forwards'' through workspaces, in case that this could be useful to the user (optional).
As mentioned, one can alternatively focus a different workspace by left-clicking on its worskpace button in the '''swaybar'''.
'''''Step 9:'' Navigating between applications within the same workspace'''. If two or more instances of the same application get launched (say, two instances of '''foot'''), then they will both appear in the same workspace that had been assigned to them, if any. In such case, {{Key|Alt}}+{{Key|Tab}} would not work to navigate between these because that keybinding navigates between applications being displayed in ''different'' workspaces. Instead, one may navigate between those two instances/tabs within that same workspace in ''three alternative ways''; no edits need be done, but one may need to make note of these methods:-
* The default {{Path|config}} file has already bound {{ic|$mod+Left}} and {{ic|$mod+Right}} to switch focus onto tabs shown to the left and right within the same workspace; in our setup, that would be {{Key|Window}}+{{Key|←}} and {{Key|Window}}+{{Key|→}}.
* The default {{Path|config}} file has similarly bound {{ic|$mod+$left}} and {{ic|$mod+$right}} for these same commands; the {{ic|$left}} and {{ic|$right}} ''"key variables"'', along with two others, have been defined in a fashion that would be familiar to those using {{Pkg|vim}}:
<pre>
set $left h
set $down j
set $up k
set $right l </pre>
:Although the {{ic|Left}} key ({{Key|←}}) is distinct from the {{ic|$left}} key (assigned here to be the {{Key|h}} key), this {{Path|config}} file has ''bound them both'' to enact the same action when combined with the {{ic|$mod}} key, specifically, to move ''left'' through tabs in the same workspace (different users prefer alternative methods):
<pre>
bindsym $mod+$left focus left
[...]
bindsym $mod+Left focus left </pre>
:Similarly for the {{ic|$right}} and {{ic|Right}} keys.
* Alternatively, one could ''left-click'' on a tab to focus on a specific application instance, similarly to how one might click on ''taskbar'' items in other desktop environments.
Any applications that were not assigned into a workspace in the {{ic|assign}} ''Steps 6-7'' above will also launch into the workspace currently focused. In such cases, therefore, their tabs would be created in the current workspace too, and one could navigate between such applications, within that same workspace, using any way reviewed in this step also.
* One may make a focused application to '''float''', and to toggle ''"floating"'' off as-and-when needed, with: {{ic|$mod+Shift+space}} . In our setup: {{Key|Window}}+{{Key|Shift}}+{{Key|Space}}.
* The {{Path|config}} file points out that one may ''"drag floating windows by holding down $mod and left mouse button"''. Seeing how {{ic|$mod}} was kept assigned as the {{Key|Window}} key: {{Key|Window}}+'''drag'''. The window needs to be floating first; in some instances, one may need to drag at the tab.
* One could make some applications to launch "floating" by default (optional). An application that is sometimes made to float by default is the {{Pkg|galculator}} calculator pad; just add:
* To toggle through '''tiled layouts''' within a workspace: {{ic|$mod+e}} / {{Key|Window}}+{{Key|e}}
* To return to '''full-sized tabs''' i.e. window-sized after being in a tiled layout, yet not fullscreen, thereby retaining toolbars, etc: {{ic|$mod+w}} / {{Key|Window}}+{{Key|w}} . Floating windows and fullscreen windows need to be toggled off first.
* To toggle in and out of '''fullscreen''': {{ic|$mod+f}} / {{Key|Window}}+{{Key|f}}
Take note of two final keybindings, or modify these first:
* To '''reload''' the '''Sway''' configuration file after editing it during a session: {{ic|$mod+Shift+c}} / {{Key|Window}}+{{Key|Shift}}+{{Key|c}}
* To '''exit''' '''Sway''' and the login session (save your work first): {{ic|$mod+Shift+e}} / {{Key|Window}}+{{Key|Shift}}+{{Key|e}}
'''''Step 11:'' Add variables and autostart instructions'''. These could be added to the beginning of this {{Path|config}} file. Typically, various environment variables would require being set before launching a '''Wayland''' compositor, for example, in {{Path|~/.profile}} . Do not add ampersands ('''&''') at the end of each line in {{Path|config}}, unlike with {{Path|.xinitrc}} syntax in '''Xorg'''.
{{Pkg|xwayland}}, if not required, can be disabled by inserting a line here to that effect. Alternatively, omit that line or comment it out by using a hashtag, as in the following example of autostart instructions, where '''Sway''' is assumed to have been launched [[Sway#Starting_Sway|using a {{ic|dbus-run-session}}]]; gui runlevel is started now if '''PipeWire''' and associated services are being [[PipeWire#Pipewire_user_service|launched as user services]]; and where '''chromium''' is also autostarted:
# Start gui runlevel for PipeWire and associated services to launch now
exec openrc -U gui
exec /usr/bin/chromium
</Pre>
{{Tip|Running ''"pure '''Wayland'''"'' – i.e. without the '''xwayland''' layer/package – may remove a possible attack surface. '''Xwayland''' could be required, however, to run certain '''Xorg'''-designed software, such as {{Pkg|xterm}}. One may also investigate '''libreoffice''' and '''okular''' functionality.}}
'''''Step 12:'' Install selected packages'''. Ensure that all mentioned applications have been installed: {{ic|apk info -e <var>package1</var> <var>package2</var>}}. Substitute entries in the following list with one's packages mentioned in the {{Path|config}} file:
'''wmenu''' was preserved for that listing; swap it out for '''rofi''' or otherwise, if necessary. One may have decided also not to include '''xterm''', etc.
Install any application not appearing in the output of that instruction.
For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].
For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].
Line 314:
Line 92:
{{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.}}
{{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.}}
Putting the system to sleep with the <Code>loginctl suspend</Code> command from [[Elogind]] requires elevated privileges or additional configuration.
For usage of the <Code>loginctl suspend</Code> command, see [[Elogind]].
To put the system to sleep after 600 seconds, use:
To put the system to sleep after 600 seconds, use:
Do not lock the screen if program is running in full screen:
Do not lock the screen if program is running in full screen:
==== Idle inhibition ====
for_window [app_id="^.*"] inhibit_idle fullscreen
for_window [app_id="^.*"] inhibit_idle fullscreen
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
Internet connectivity, unless the packages have been pre-fetched into a local cache.
Install appropriate Graphics driver drivers for your hardware. Without graphics drivers errors are likely to occur.
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.
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.
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.
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:
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 Swaybelow; 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:
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:
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:
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.
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:
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.)
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).
