table of contents
- bookworm 1.7-6
- testing 1.9-2
- unstable 1.9-2
- experimental 1.10-1
sway(5) | File Formats Manual | sway(5) |
NAME¶
sway - configuration file and commands
DESCRIPTION¶
A sway configuration file is a list of sway commands that are executed by sway on startup. These commands usually consist of setting your preferences and setting key bindings. An example config is likely present in /etc/sway/config for you to check out.
Lines in the configuration file might be extended through multiple lines by adding a '\' character at the end of line. e.g.:
bindsym Shift+XF86AudioRaiseVolume exec \ pactl set-sink-volume @DEFAULT_SINK@ -1%
Commands can also be given as a block in the form command { <subcommands...> }. Anything before the opening { will be prepended to the lines inside the block. For example:
output eDP-1 { background ~/wallpaper.png fill resolution 1920x1080 }
is identical to
output eDP-1 background ~/wallpaper.png fill output eDP-1 resolution 1920x1080
These commands can be executed in your config file, via swaymsg(1), or via the bindsym command.
COMMAND CONVENTIONS¶
Commands are split into several arguments using spaces. You can enclose arguments with quotation marks ("..." or '...') to add spaces to a single argument. You may also run several commands in order by separating each with , or ;. Criteria is retained across commands separated by ,, but will be reset (and allow for new criteria, if desired) for commands separated by a ;.
Throughout the documentation, | is used to distinguish between arguments for which you may only select one. [...] is used for optional arguments, and <...> for arguments where you are expected to supply some value.
COMMANDS¶
This section only lists general commands. For input and output commands, refer to sway-input(5) and sway-output(5).
Config only commands¶
The following commands may only be used in the configuration file.
bar [<bar-id>] <bar-subcommands...>
default_orientation horizontal|vertical|auto
include <path>
swaybg_command <command>
It can be disabled by setting the command to a single dash: swaybg_command -
swaynag_command <command>
It can be disabled by setting the command to a single dash: swaynag_command -
workspace_layout default|stacking|tabbed
xwayland enable|disable|force
Runtime only commands¶
The following commands cannot be used directly in the configuration file. They are expected to be used with bindsym or at runtime through swaymsg(1).
border none|normal|csd|pixel [<n>]
border toggle
exit
floating enable|disable|toggle
<criteria> focus
focus up|right|down|left
focus prev|next [sibling]
focus child
focus parent
focus output up|right|down|left
focus output <name>
focus tiling
focus floating
focus mode_toggle
fullscreen [enable|disable|toggle] [global]
gaps inner|outer|horizontal|vertical|top|right|bottom|left all|current set|plus|minus|toggle <amount>
inhibit_idle focus|fullscreen|open|none|visible
This can also be used with criteria to set an idle inhibitor for any existing view or with for_window to set idle inhibitors for future views.
layout default|splith|splitv|stacking|tabbed
When using the stacking layout, only the focused window in the container is displayed, with the opened windows' list on the top of the container.
The tabbed layout is similar to stacking, but the windows’ list is vertically split.
layout toggle [split|all]
layout toggle [split|tabbed|stacking|splitv|splith] [split|tabbed|stacking|splitv|splith]...
max_render_time off|<msec>
When set to off, the relevant application is told to render this window immediately after display refresh. How much time is left for rendering before sway composites the output at that point depends on the output max_render_time setting.
To set this up for optimal latency:
- 1.
- Set up output max_render_time (see sway-output(5)).
- 2.
- Put the target application in full-screen and have it continuously render something.
- 3.
- Start by setting max_render_time 1. If the application drops frames, increment by 1.
This setting only has an effect if a per-output max_render_time is in effect on the output the window is currently on. See sway-output(5) for further details.
allow_tearing yes|no
When this option is not set, the tearing hints provided by the application determine whether tearing is allowed. When yes is specified, the application allows tearing regardless of the tearing hints. When no is specified, tearing will never be allowed on the application, regardless of the tearing hints.
This setting only has an effect if tearing is allowed on the output through the per-output allow_tearing setting. See sway-output(5) for further details.
move left|right|up|down [<px> px]
move [absolute] position <pos_x> [px|ppt] <pos_y> [px|ppt]
move [absolute] position center
move position cursor|mouse|pointer
move [container|window] [to] mark <mark>
move [--no-auto-back-and-forth] [container|window] [to] workspace [number] <name>
move [container|window] [to] workspace prev|next|current
move [container|window] [to] workspace prev_on_output|next_on_output
move [container|window] [to] workspace back_and_forth
move [container|window] [to] output <name-or-id>|current
move [container|window] [to] output up|right|down|left
move [container|window] [to] scratchpad
move workspace [to] output <name-or-id>|current
move workspace to [output] <name-or-id>|current
move workspace [to] output up|right|down|left
move workspace to [output] up|right|down|left
nop <comment>
reload
rename workspace [<old_name>] to <new_name>
resize shrink|grow width|height [<amount> [px|ppt]]
resize set height <height> [px|ppt]
resize set [width] <width> [px|ppt]
resize set [width] <width> [px|ppt] [height] <height> [px|ppt]
scratchpad show
shortcuts_inhibitor enable|disable
split vertical|v|horizontal|h|none|n|toggle|t
splith
splitv
splitt
sticky enable|disable|toggle
swap container with id|con_id|mark <arg>
title_format <format>
%app_id - The wayland app ID (applicable to wayland windows only)
%class - The X11 classname (applicable to xwayland windows only)
%instance - The X11 instance (applicable to xwayland windows only)
%shell - The protocol the window is using (typically xwayland or
This command is typically used with for_window criteria. For example:
Note that markup requires pango to be enabled via the font command.
The default format is "%title".
Config or runtime commands¶
The following commands may be used either in the configuration file or at runtime.
assign <criteria> [→] [workspace] [number] <workspace>
assign <criteria> [→] output left|right|up|down|<name>
bindsym [--whole-window] [--border] [--exclude-titlebar] [--release] [--locked] [--to-code] [--input-device=<device>] [--no-warn] [--no-repeat] [--inhibited] [Group<1-4>+]<key combo> <command>
For specifying modifier keys, you can use the XKB modifier names Shift, Lock (for Caps Lock), Control, Mod1 (for Alt), Mod2 (for Num Lock), Mod3 (for XKB modifier Mod3), Mod4 (for the Logo key), and Mod5 (for AltGr). In addition, you can use the aliases Ctrl (for Control), Alt (for Alt), and Super (for the Logo key).
Unless the flag --locked is set, the command will not be run when a screen locking program is active. If there is a matching binding with and without --locked, the one with will be preferred when locked and the one without will be preferred when unlocked. If there are matching bindings and one has both --input-device and --locked and the other has neither, the former will be preferred even when unlocked.
Unless the flag --inhibited is set, the command will not be run when a keyboard shortcuts inhibitor is active for the currently focused window. Such inhibitors are usually requested by remote desktop and virtualization software to enable the user to send keyboard shortcuts to the remote or virtual session. The --inhibited flag allows one to define bindings which will be exempt from pass-through to such software. The same preference logic as for --locked applies.
Unless the flag --no-repeat is set, the command will be run repeatedly when the key is held, according to the repeat settings specified in the input configuration.
Bindings to keysyms are layout-dependent. This can be changed with the --to-code flag. In this case, the keysyms will be translated into the corresponding keycodes in the first configured layout.
Mouse bindings operate on the container under the cursor instead of the container that has focus. Mouse buttons can either be specified in the form button[1-9] or by using the name of the event code (ex BTN_LEFT or BTN_RIGHT). For the former option, the buttons will be mapped to their values in X11 (1=left, 2=middle, 3=right, 4=scroll up, 5=scroll down, 6=scroll left, 7=scroll right, 8=back, 9=forward). For the latter option, you can find the event names using libinput debug-events.
The priority for matching bindings is as follows: input device, group, and locked state.
--whole-window, --border, and --exclude-titlebar are mouse-only options which affect the region in which the mouse bindings can be triggered. By default, mouse bindings are only triggered when over the title bar. With the --border option, the border of the window will be included in this region. With the --whole-window option, the cursor can be anywhere over a window including the title, border, and content. --exclude-titlebar can be used in conjunction with any other option to specify that the titlebar should be excluded from the region of consideration.
If --whole-window is given, the command can be triggered when the cursor is over an empty workspace. Using a mouse binding over a layer surface's exclusive region is not currently possible.
Example:
# Execute firefox when alt, shift, and f are pressed together bindsym Mod1+Shift+f exec firefox
bindswitch [--locked] [--no-warn] [--reload] <switch>:<state> <command>
Unless the flag --locked is set, the command will not be run when a screen locking program is active. If there is a matching binding with and without --locked, the one with will be preferred when locked and the one without will be preferred when unlocked.
If the --reload flag is given, the binding will also be executed when the config is reloaded. toggle bindings will not be executed on reload. The --locked flag will operate as normal so if the config is reloaded while locked and --locked is not given, the binding will not be executed.
By default, if you overwrite a binding, swaynag will give you a warning. To silence this, use the --no-warn flag.
Example:
# Show the virtual keyboard when tablet mode is entered. bindswitch tablet:on busctl call --user sm.puri.OSK0 /sm/puri/OSK0 sm.puri.OSK0 SetVisible b true # Log a message when the laptop lid is opened or closed. bindswitch lid:toggle exec echo "Lid moved"
bindgesture [--exact] [--input-device=<device>] [--no-warn] <gesture>[:<fingers>][:directions] <command>
type | fingers | direction |
hold | 1 - 5 | none |
swipe | 3 - 5 | up, down, left, right |
pinch | 2 - 5 | all above + inward, outward, clockwise, counterclockwise |
If a input-device is given, the binding will only be executed for that input device and will be executed instead of any binding that is generic to all devices. By default, if you overwrite a binding, swaynag will give you a warning. To silence this, use the --no-warn flag.
The --exact flag can be used to ensure a binding only matches when exactly all specified directions are matched and nothing more. If there is matching binding with --exact, it will be preferred.
The priority for matching bindings is as follows: input device, then exact matches followed by matches with the highest number of matching directions.
Gestures executed while the pointer is above a bar are not handled by sway. See the respective documentation, e.g. bindgesture in sway-bar(5).
Example:
# Allow switching between workspaces with left and right swipes bindgesture swipe:right workspace prev bindgesture swipe:left workspace next # Allow container movements by pinching them bindgesture pinch:inward+up move up bindgesture pinch:inward+down move down bindgesture pinch:inward+left move left bindgesture pinch:inward+right move right
client.background <color>
client.<class> <border> <background> <text> [<indicator> [<child_border>]]
The available classes are:
client.focused
client.focused_inactive
client.focused_tab_title
client.placeholder
client.unfocused
client.urgent
The meaning of each color is:
border
background
text
indicator
child_border
The default colors are:
class | border | background | text | indicator | child_border |
background | n/a | #ffffff | n/a | n/a | n/a |
focused | #4c7899 | #285577 | #ffffff | #2e9ef4 | #285577 |
focused_inactive | #333333 | #5f676a | #ffffff | #484e50 | #5f676a |
focused_tab_title | #333333 | #5f676a | #ffffff | n/a | n/a |
unfocused | #333333 | #222222 | #888888 | #292d2e | #222222 |
urgent | #2f343a | #900000 | #ffffff | #900000 | #900000 |
placeholder | #000000 | #0c0c0c | #ffffff | #000000 | #0c0c0c |
default_border normal|none|pixel [<n>]
default_floating_border normal|none|pixel [<n>]
exec <shell command>
exec_always <shell command>
floating_maximum_size <width> x <height>
floating_minimum_size <width> x <height>
floating_modifier <modifier> [normal|inverse]
focus_follows_mouse yes|no|always
focus_on_window_activation smart|urgent|focus|none
focus_wrapping yes|no|force|workspace
font [pango:]<font>
force_display_urgency_hint <timeout> [ms]
titlebar_border_thickness <thickness>
titlebar_padding <horizontal> [<vertical>]
for_window <criteria> <command>
gaps inner|outer|horizontal|vertical|top|right|bottom|left <amount>
This affects new workspaces only, and is used when the workspace doesn't have its own gaps settings (see: workspace <ws> gaps ...).
hide_edge_borders [--i3] none|vertical|horizontal|both|smart|smart_no_gaps
input <input_device> <input-subcommands...>
* may be used in lieu of a specific device name to configure all input devices. A list of input device names may be obtained via swaymsg -t get_inputs.
seat <seat> <seat-subcommands...>
kill
smart_borders on|no_gaps|off
smart_gaps on|off|toggle|inverse_outer
mark --add|--replace [--toggle] <identifier>
mode <mode>
mode [--pango_markup] <mode> <mode-subcommands...>
mouse_warping output|container|none
no_focus <criteria>
output <output_name> <output-subcommands...>
* may be used in lieu of a specific output name to configure all outputs. A list of output names may be obtained via swaymsg -t get_outputs.
popup_during_fullscreen smart|ignore|leave_fullscreen
primary_selection enabled|disabled
set $<name> <value>
show_marks yes|no
opacity [set|plus|minus] <value>
tiling_drag enable|disable|toggle
tiling_drag_threshold <threshold>
title_align left|center|right
unbindswitch <switch>:<state>
unbindgesture [--exact] [--input-device=<device>] <gesture>[:<fingers>][:directions]
unbindsym [--whole-window] [--border] [--exclude-titlebar] [--release] [--locked] [--to-code] [--input-device=<device>] <key combo>
unbindcode [--whole-window] [--border] [--exclude-titlebar] [--release] [--locked] [--input-device=<device>] <code> is also available for unbinding with key/button codes instead of key/button names.
unmark [<identifier>]
urgent enable|disable|allow|deny
workspace [--no-auto-back-and-forth] [number] <[num:]name>
If the no-auto-back-and-forth option is given, then this command will not perform a back-and-forth operation when the workspace is already focused and workspace_auto_back_and_forth is enabled.
If the number keyword is specified and a workspace with the number already exists, then the workspace with the number will be used. If a workspace with the number does not exist, a new workspace will be created with the name name.
workspace prev|next
workspace prev_on_output|next_on_output
workspace back_and_forth
workspace <name> gaps inner|outer|horizontal|vertical|top|right|bottom|left <amount>
This command does not affect existing workspaces. To alter the gaps of an existing workspace, use the gaps command.
workspace <name> output <outputs...>
This command does not affect existing workspaces. To move an existing workspace, use the move command in combination with the workspace criteria (non-empty workspaces only) or workspace command (to switch to the workspace before moving).
workspace_auto_back_and_forth yes|no
CRITERIA¶
A criteria is a string in the form of, for example:
[class="[Rr]egex.*" title="some title"]
The string contains one or more (space separated) attribute/value pairs. They are used by some commands to choose which views to execute actions on. All attributes must match for the criteria to match. Criteria is retained across commands separated by a ,, but will be reset (and allow for new criteria, if desired) for commands separated by a ;.
Criteria may be used with either the for_window or assign commands to specify operations to perform on new views. A criteria may also be used to perform specific commands (ones that normally act upon one window) on all views that match that criteria. For example:
Focus on a window with the mark "IRC":
[con_mark="IRC"] focus
Kill all windows with the title "Emacs":
[class="Emacs"] kill
You may like to use swaymsg -t get_tree for finding the values of these properties in practice for your applications.
The following attributes may be matched with:
all
app_id
class
con_id
con_mark
floating
id
instance
pid
shell
tiling
title
urgent
window_role
window_type
workspace
SEE ALSO¶
sway(1) sway-input(5) sway-output(5) sway-bar(5) sway-ipc(7)
2024-10-28 |