wayland.txt For Vim version 9.2. Last change: 2026 Apr 20
VIM REFERENCE MANUAL by Bram Moolenaar
Wayland Protocol Support wayland
1. Useful Wayland information wayland-useful
2. Wayland selections wayland-selections
==============================================================================
1. Useful Wayland information wayland-useful
wayland-seat
Functionality such as the clipboard for Wayland requires a seat to use. A
Wayland seat can consist of a keyboard, pointer, and touch device(s). The
seat to use can be set with the 'wlseat' option. Only useful if you use
multiple Wayland seats in the same Wayland session. If you don't know what
this is means, then it likely does not matter for you.
wayland-gui
See gui-wayland. Please note that when using the GUI, Vim uses the toolkit
such as GTK for accessing the clipboard, and does not access the clipboard
though Wayland. You can check this though the v:clipmethod variable, which
should equal to "none" when running the GUI.
Wayland commands:
:wlrestore :wl
:wl[restore] [display] Reinitializes the connection to the Wayland
compositor.
Useful when running Vim in a screen/tmux session that
continues running after the Wayland compositor
restarts.
[display] should be in the format of the
$WAYLAND_DISPLAY environment variable (e.g.
"wayland-0"). If [display] is omitted, then it
reinitializes the connection using the same value as
was used for the previous execution of this command.
If the value was never specified, then it uses the
value of $WAYLAND_DISPLAY environment variable. This
will also update v:clipmethod.
{only available when compiled with the +wayland
feature}
Wayland errors:
E1548
Vim failed communicating with the Wayland compositor. This is likely due to
the Wayland compositor process being killed. Try the :wlrestore command to
try connecting again.
==============================================================================
2. Wayland Selections wayland-selections
Vim supports the wlr-data-control-unstable-v1 and ext-data-control-v1
protocols, for accessing the current Wayland selection. Selection in this case
essentially means the "clipboard." You can check if your Wayland compositor
supports either of these protocols by running the wayland-info command, which
should be bundled with libwayland on your system:
Some compositors that are known to support either or both protocols:
1. KWin (KDE)
2. wlroots based (Sway, Labwc)
3. Niri
4. Hyprland
5. Wayfire
If you come from X11, then the regular Wayland selection is equivalent to the
CLIPBOARD selection in X11, and the primary Wayland selection equates to the
X11 PRIMARY selection. Accessing these selections is the same as X11 in Vim,
in which the + register is the regular selection, and the * register is the
primary selection. Note that your compositor may not support primary
selections, see wayland-primary-selection for more details.
wayland-persist
If you use X11 cut buffers, no such things exist on Wayland. Instead to
emulate such functionality, a separate clipboard manager must be used in order
to persist selection data when a Wayland client exits.
wayland-and-x11
If your version of Vim comes compiled with both X11 and Wayland support, then
Vim determines which one to use when accessing the clipboard using the
'clipmethod' option.
wayland-primary-selection
If you find X11 style primary selections useful, Wayland also implements this
feature using the protocols that Vim supports. This is unless you are using
version 1 (not the same as the 'v1' in the protocol name), of the
wlr-data-control protocol, then primary selection will not be supported. You
can check this using
then primary selection is supported. If you also get
"ext_data_control_manager_v1", then Vim will use that protocol instead, which
has primary selection support builtin into it.
If your Wayland compositor does not support the wlr-data-control-v1 or the
ext-data-control-v1 protocol, Vim cannot access the clipboard directly through
the Wayland protocol. External tools such as wl-clipboard can be used instead
via a user-defined clipboard-providers.
Example: define a provider that shells out to wl-copy and wl-paste: >vim9
vim9script
def Available(): bool
return executable('wl-copy') && executable('wl-paste')
enddef
def Copy(reg: string, type: string, str: list<string>)
var args = "wl-copy"
if reg == "*"
args ..= " -p"
endif
system(args, str)
enddef
def Paste(reg: string): tuple<string, list<string>>
var args = "wl-paste --type text/plain;charset=utf-8"
if reg == "*"
args ..= " -p"
endif
return ("", systemlist(args))
enddef
v:clipproviders["wl_clipboard"] = {
available: Available,
copy: {
"+": Copy,
"*": Copy
},
paste: {
"+": Paste,
"*": Paste
}
}
set clipmethod=wl_clipboard
This relies on the wl-clipboard package being installed
(https://github.com/bugaevc/wl-clipboard).
vim:tw=78:ts=8:noet:ft=help:norl
VIM REFERENCE MANUAL by Bram Moolenaar
Wayland Protocol Support wayland
1. Useful Wayland information wayland-useful
2. Wayland selections wayland-selections
==============================================================================
1. Useful Wayland information wayland-useful
wayland-seat
Functionality such as the clipboard for Wayland requires a seat to use. A
Wayland seat can consist of a keyboard, pointer, and touch device(s). The
seat to use can be set with the 'wlseat' option. Only useful if you use
multiple Wayland seats in the same Wayland session. If you don't know what
this is means, then it likely does not matter for you.
wayland-gui
See gui-wayland. Please note that when using the GUI, Vim uses the toolkit
such as GTK for accessing the clipboard, and does not access the clipboard
though Wayland. You can check this though the v:clipmethod variable, which
should equal to "none" when running the GUI.
Wayland commands:
:wlrestore :wl
:wl[restore] [display] Reinitializes the connection to the Wayland
compositor.
Useful when running Vim in a screen/tmux session that
continues running after the Wayland compositor
restarts.
[display] should be in the format of the
$WAYLAND_DISPLAY environment variable (e.g.
"wayland-0"). If [display] is omitted, then it
reinitializes the connection using the same value as
was used for the previous execution of this command.
If the value was never specified, then it uses the
value of $WAYLAND_DISPLAY environment variable. This
will also update v:clipmethod.
{only available when compiled with the +wayland
feature}
Wayland errors:
E1548
Vim failed communicating with the Wayland compositor. This is likely due to
the Wayland compositor process being killed. Try the :wlrestore command to
try connecting again.
==============================================================================
2. Wayland Selections wayland-selections
Vim supports the wlr-data-control-unstable-v1 and ext-data-control-v1
protocols, for accessing the current Wayland selection. Selection in this case
essentially means the "clipboard." You can check if your Wayland compositor
supports either of these protocols by running the wayland-info command, which
should be bundled with libwayland on your system:
wayland-info | grep -E '(ext_data_control|zwlr_data_control)'
If grep finds a match, then you have either or both protocols on your system.Some compositors that are known to support either or both protocols:
1. KWin (KDE)
2. wlroots based (Sway, Labwc)
3. Niri
4. Hyprland
5. Wayfire
If you come from X11, then the regular Wayland selection is equivalent to the
CLIPBOARD selection in X11, and the primary Wayland selection equates to the
X11 PRIMARY selection. Accessing these selections is the same as X11 in Vim,
in which the + register is the regular selection, and the * register is the
primary selection. Note that your compositor may not support primary
selections, see wayland-primary-selection for more details.
wayland-persist
If you use X11 cut buffers, no such things exist on Wayland. Instead to
emulate such functionality, a separate clipboard manager must be used in order
to persist selection data when a Wayland client exits.
wayland-and-x11
If your version of Vim comes compiled with both X11 and Wayland support, then
Vim determines which one to use when accessing the clipboard using the
'clipmethod' option.
wayland-primary-selection
If you find X11 style primary selections useful, Wayland also implements this
feature using the protocols that Vim supports. This is unless you are using
version 1 (not the same as the 'v1' in the protocol name), of the
wlr-data-control protocol, then primary selection will not be supported. You
can check this using
wayland-info | grep -E '(ext_data_control|zwlr_data_control)'
If the "version:" entry for "zwlr_data_control_manager_v1" is "2" or greater,then primary selection is supported. If you also get
"ext_data_control_manager_v1", then Vim will use that protocol instead, which
has primary selection support builtin into it.
If your Wayland compositor does not support the wlr-data-control-v1 or the
ext-data-control-v1 protocol, Vim cannot access the clipboard directly through
the Wayland protocol. External tools such as wl-clipboard can be used instead
via a user-defined clipboard-providers.
Example: define a provider that shells out to wl-copy and wl-paste: >vim9
vim9script
def Available(): bool
return executable('wl-copy') && executable('wl-paste')
enddef
def Copy(reg: string, type: string, str: list<string>)
var args = "wl-copy"
if reg == "*"
args ..= " -p"
endif
system(args, str)
enddef
def Paste(reg: string): tuple<string, list<string>>
var args = "wl-paste --type text/plain;charset=utf-8"
if reg == "*"
args ..= " -p"
endif
return ("", systemlist(args))
enddef
v:clipproviders["wl_clipboard"] = {
available: Available,
copy: {
"+": Copy,
"*": Copy
},
paste: {
"+": Paste,
"*": Paste
}
}
set clipmethod=wl_clipboard
This relies on the wl-clipboard package being installed
(https://github.com/bugaevc/wl-clipboard).
vim:tw=78:ts=8:noet:ft=help:norl