slurp picks a rectangle on Wayland and hands it to the next command

A selection tool that writes to standard output

slurp selects a region in a Wayland compositor and prints it to standard output. That one sentence is the whole design, and it explains everything else about the program.

The usual run is a bare invocation, and the result is on standard output, which means the tool is a filter in a pipeline rather than an application that saves a file:

slurp

The README says it works well with grim, and grim is the capture tool it is designed to work with. The pairing is the point. Where grim alone gives you a whole monitor, slurp gives you the rectangle, and the composition of the two gives you a cropped screenshot.

The distinction matters for a class of user who has never met a Wayland screenshot workflow. On X11, screenshot tooling has been around long enough that the region selection is often baked into the same application that takes the picture. On Wayland, the compositor is the client-facing layer and screen capture is a separate protocol, so the region selection tends to be its own program, and the capture is a different one. slurp is the selection half.

The practical consequence is that slurp on its own produces coordinates, not pixels. A user who runs it and expects a file will get text. That is not a limitation so much as a consequence of the Unix style the project is written in, and it is the reason the README spends more words on example pipelines than on flags.

The format string is the output, and one placeholder is documented

The selection is printed using a format string, which is what makes the tool composable with other commands.

The documented example selects an output and prints its name:

slurp -o -f "%o"

The -o flag selects an output rather than a region, and the -f flag supplies the format, where %o stands for the output name. The README documents that one placeholder and stops there, which is worth knowing before you write a pipeline: the rest of the format vocabulary is not written down in the README, and the man page generated from slurp.1.scd is the place to look for the complete set.

There is also a mode for a single point rather than a region:

slurp -p

That is the mode you want when the thing you are asking for is a position rather than an area, for instance the coordinates of a window under the pointer, and it is what makes the tool usable for status bar and script driven workflows rather than only for screenshots.

The combination of -o, -p and -f covers the three things a shell script needs from a selection: which output was chosen, whether the user picked a point or a box, and how the result should be rendered for the next command. That is a small API, and it is complete enough to build on.

Sway pipelines are the real workflow

The two most useful examples in the README are not about slurp at all. They are about feeding it geometry from swaymsg, and they show the difference between a window rectangle and a window without its border.

Selecting a window under Sway, using swaymsg and jq:

swaymsg -t get_tree | jq -r '.. | select(.pid? and .visible?) | .rect | "\(.x),\(.y) \(.width)x\(.height)"' | slurp

And the same thing without the border:

swaymsg -t get_tree | jq -r '.. | select(.pid? and .visible?) | "\(.rect.x+.window_rect.x),\(.rect.y+.window_rect.y) \(.window_rect.width)x\(.window_rect.height)"' | slurp

The first pipeline takes the rectangle from the tree node directly, which is the frame geometry including the border decoration. The second adds the window_rect offsets to the frame position and uses the window rectangle's size, which gives the client area without the border. Getting that wrong is the classic Sway screenshot bug, and slurp accepts either geometry because the selection itself is just a rectangle the user then adjusts with the mouse.

That last point is the design decision that makes the tool work. slurp does not try to decide what the user meant. It presents a rectangle, seeded by whatever the pipeline supplied, and lets the person move and resize it. A pipeline that computes a rough area and a person who confirms it is a better division of labour than either one alone.

The two examples are also the clearest statement of slurp's place in a workflow. It is the human confirmation step at the end of a machine computed region.

Building it needs meson and four libraries

There is no package recipe in the README, so building from source is the documented path. The dependencies are meson, wayland, cairo, libxkbcommon, and scdoc as an optional dependency for the man pages.

The build itself is the standard meson sequence, and the last line runs the freshly built binary:

git clone https://github.com/emersion/slurp
cd slurp
meson setup build
ninja -C build
build/slurp

The dependency list tells you what the program actually does. Wayland is the protocol library, cairo is the rendering backend for the selection overlay, and libxkbcommon handles keyboard input, which matters for a selection tool because the keyboard is how you cancel or confirm. The optional scdoc dependency is for generating the man page from slurp.1.scd, and it is optional in the sense that the program builds without it, at the cost of not having the manual page installed.

The repository layout is small and flat, which is what a focused utility looks like. There is main.c for the entry point and option handling, box.c for the selection box, lock.c for handling the grab and the interaction, pool-buffer.c for the Wayland shared buffer handling, and render.c for the drawing, plus an include/ directory for headers and a protocol/ directory for the generated Wayland protocol code. The build definition is meson.build with a meson_options.txt for feature toggles, and .build.yml is the CI configuration.

Where slurp is the wrong tool

There are three cases where this is the wrong program, and they are all about the environment or the expectation.

The first is X11. slurp is a Wayland program, and the Wayland screenshot ecosystem exists the way it does because X11's model of screen capture was permissive enough that a client could read any window. On X11 you would use the screenshot tool of your desktop environment, and slurp has nothing to offer there.

The second is the expectation that slurp saves a file. It does not. It writes a selection to standard output, and the README's own example of using it is the bare command with no redirection. A user who wants a file has to compose slurp with the capture tool, and if they do not know that, the program appears broken.

The third is automation that does not want a person in the loop. Every invocation of slurp presents a selection overlay and waits for a human to adjust and confirm. If your script needs a region computed without interaction, slurp is in the way, and you would compute the geometry yourself and feed it to the capture tool directly. The swaymsg examples come close, but they still end in a slurp invocation that waits for the user.

The compositor's own support for whatever the selection overlay needs is worth checking too, since the README does not list compositor requirements, so this is one of the details to confirm on your own desktop.

MIT, a small release history and two contribution routes

The licence is MIT, and the repository carries the LICENSE file at the top level, which is the simplest thing to say about the legal side and there is not much more to add beyond the fact that it is permissive and the file settles the terms.

The release history is short and slow. The published tags are 1.5.0 from December 2023, 1.4.0 from December 2022 and 1.3.2 from April 2021. The repository itself is not archived, and the last push was on 2026-05-10, so work is still landing on the master branch even though the tagged releases have not moved for a while. For a utility of this size that is not a bad sign, since the amount of code that can change in a screenshot region selector is limited, but it does mean a distribution that packages a recent version may be ahead of the last tag.

Contributions go two ways, either GitHub pull requests or patches on the mailing list, and the mailing list is at lists.sr.ht. There is also an IRC channel on Libera Chat, which is the older end of the communication options and a useful sign of the project community.

The build is reproducible in the ordinary sense, with meson and ninja and a CI configuration in .build.yml, and the man page is written as slurp.1.scd in scdoc format, which means the documentation lives in the repository next to the code rather than on a website that can drift from it.

Editorial conclusion

slurp suits a Wayland desktop user who wants a screenshot of a region rather than a whole output, and who is comfortable composing shell pipelines. It does not suit an X11 user, since it is a Wayland program, and it is not a screenshot tool on its own, since it writes a selection to standard output and never a file. Verify first that the format string your pipeline uses matches what your version of slurp supports, since the README documents only the output name placeholder, and confirm on your own compositor that the selection overlay appears, because the README does not list compositor requirements.

Frequently asked questions

Official sources

1. emersion/slurp on GitHub
2. License: MIT
3. Project website
4. README
5. Releases