wl-clipboard: wl-copy and wl-paste for Wayland pipes

What wl-copy and wl-paste actually solve

On X11, a clipboard tool could talk to the X server directly and read or write the selection whenever it liked. Wayland compositors do not expose that, so a script that wants to put a string on the clipboard needs a client that speaks the compositor's clipboard protocol. wl-clipboard provides exactly two such clients: wl-copy writes data to the clipboard, and wl-paste reads data from it. The README frames the purpose as copying data between the clipboard and Unix pipes, sockets, files and so on.

The audience is narrow and specific. It is a tool for people who already live in a terminal: shell script authors, users writing pipeline one-liners, and anyone who wants the clipboard to behave like a file descriptor. The README's own examples are all of this kind, including copying the output of ls into the clipboard and sorting clipboard contents with wl-paste | sort | wl-copy. If you want a graphical clipboard history with thumbnails and a search box, this is not that project, and the README never claims it is.

The mechanism: two short-lived Wayland clients

wl-clipboard is written in C and built with Meson, which is visible in the repository layout: meson.build and meson_options.txt sit at the top level, with source under src/, shell completions under completions/, and data/ for installed files. There is no daemon in the tree and no background service in the README. Each invocation of wl-copy or wl-paste is a client that connects to the compositor and uses the clipboard protocol the compositor exposes.

That design explains the behaviour people notice first. Because the utility is a client and not a server, the data it places on the clipboard is owned by the running process, so a compositor that loses the client loses the clipboard contents. It also explains why the tool is useful in pipelines: standard input and standard output are the interface, so the clipboard composes with sort, nc, or any other program that reads and writes streams. The README's pastebin example, wl-paste --watch nc paste.example.org 5555, is the clearest illustration of the model. The --watch flag makes wl-paste stay resident and run a command whenever the clipboard changes, which is the one place where the tool stops being purely short-lived. The README does not document what happens to --watch across compositor restarts or how it handles multiple MIME types.

Installing wl-clipboard and running a first pipeline

The README states that wl-clipboard is likely available in your favorite Linux or BSD distro, and points at BUILDING.md for source builds. The distribution package is the path to prefer on Arch, Gentoo, Ubuntu, Fedora and NixOS, since the release history shows a gap between 2.2.1 in 2023 and 2.3.0 in 2026, and packaged versions may lag. The commands below are the README's own examples.

Copy a literal string to the clipboard:

wl-copy Hello world!

Nothing is printed on success. The string is now the clipboard contents for any Wayland client on the same session.

Read it back, either to the terminal or into a file:

wl-paste
wl-paste > clipboard.txt

The first command prints the text; the second writes it to clipboard.txt in the current directory. Both use standard output, so they compose with anything else.

Round-trip through a pipe, which is the pattern the tool is built for:

wl-paste | sort | wl-copy

This reads the current clipboard, sorts the lines, and writes the result back. For binary data the README shows redirection instead: wl-copy < ~/Pictures/photo.png copies an image file. If you want a command to run every time the clipboard changes, the README gives wl-paste --watch nc paste.example.org 5555. The man page, wl-clipboard(1), is where the README sends you for the full flag set.

Where wl-clipboard stops: history, persistence and MIME types

The most common wrong expectation is that wl-clipboard keeps a clipboard history. It does not. There is no store in the repository, no database file, and no history flag in the README. If you copy something new, the previous contents are gone as far as this tool is concerned. A related search phrase, wl clipboard history, describes a feature this project does not implement; users who need history combine wl-clipboard with a separate manager rather than expecting one from it.

The second limitation follows from the client model. Because the clipboard is owned by the process that set it, closing that process or losing the compositor session can drop the contents. The README does not document rollback, recovery or persistence semantics, and BUILDING.md is about compilation, not runtime guarantees. Treat any assumption about clipboard contents surviving a logout as unverified.

MIME types are the third gap. The README shows text and image examples but does not describe how to select among multiple offered types, and the man page is the only pointer given. Scripts that need to distinguish text from images should not assume the default choice is the one they want. Finally, wl-clipboard requires a Wayland session with a compositor that implements the relevant clipboard protocol. Under X11 it is the wrong tool, and the related project wl-clipboard-x11 exists precisely as a wrapper for using wl-clipboard as a drop-in replacement for X11 clipboard tools.

Alternatives: wl-clipboard-rs, wl-clipboard-x11 and cliphist

The README lists two related projects, and they differ from wl-clipboard in approach rather than in surface behaviour. wl-clipboard-rs is a Rust crate for working with the Wayland clipboard that includes a reimplementation of wl-copy and wl-paste. The difference is packaging and reuse: wl-clipboard-rs ships as a library, so a Rust application can call clipboard functions in-process instead of shelling out to a C binary. wl-clipboard itself is a C program with a Meson build; if your code is in Rust and you want clipboard access without spawning a process, the crate is the more natural dependency.

wl-clipboard-x11 is a wrapper whose stated purpose is to use wl-clipboard as a drop-in replacement for X11 clipboard tools. That is a migration aid, not a competing implementation: it lets scripts written against X11 clipboard commands keep working on a Wayland session by translating the calls.

A third comparison, cliphist, appears in search data as wl clipboard vs cliphist. The wl-clipboard README does not discuss cliphist, so the honest difference to state is architectural. wl-clipboard copies and pastes; a clipboard manager stores a history of past selections. The two are complementary, and the README's own --watch example is the hook you would use to feed a manager.

Maintenance, licence and upgrade cost

The repository is not archived. The last push was on 2026-08-06, and the most recent release is v2.3.0 from 2026-03-22, following v2.2.1 in 2023 and v2.2.0 in 2023. That cadence matters for planning: the 2023 to 2026 gap means a distribution that packaged 2.2.1 may be several years behind on fixes, so checking your distro's version is worth doing before filing a bug. The project is written in C and built with Meson, which keeps the build dependency surface small, and shell completions ship in the repository under completions/, so packaged installs should include them.

Licensing is straightforward to state and not to interpret. wl-clipboard is free software under the GNU General Public License version 3 or later, and COPYING is the licence text in the repository. For most users this changes nothing. For anyone linking the code into a larger product, the GPL's copyleft terms are the relevant consideration, and that is a question for your own legal review rather than something this article can settle. The practical upgrade cost is low: the tool is a pair of binaries with no configuration file in the repository, so upgrading means replacing the package, not migrating settings.

Editorial conclusion

Adopt wl-clipboard if you work on a Wayland session and want clipboard access from shell scripts, pipelines or a terminal, and install it from your distribution rather than building it. Do not adopt it if you need a persistent clipboard history, a GUI picker or a daemon that survives a compositor restart: wl-clipboard is a pair of short-lived utilities, not a manager. Before relying on it, verify that your compositor implements the wlr-data-control protocol, check whether your distribution ships 2.3.0 or an older package, and confirm that wl-paste --watch behaves the way you expect on your compositor, since the README documents the flag but not its edge cases.

Frequently asked questions

Official sources

1. bugaevc/wl-clipboard on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases