swappy: Wayland Screenshot Editing with grim and slurp

Why swappy belongs in a Wayland screenshot pipeline

swappy solves the editing step between screen capture and saving or forwarding a snapshot. The README describes it as a Wayland native snapshot and editor tool inspired by Snappy on macOS. Its intended users are people running Wayland sessions, particularly Sway users who already use grim and slurp to select a screen region. The project is not a general-purpose image editor and does not replace the capture utility. Instead, it accepts an image supplied by another program and provides a GTK-based interface for marking up that image.

The most consequential design choice is support for standard input and standard output. The documented pipeline sends grim output to swappy, which lets the edited PNG continue to another command. That makes swappy useful for keyboard-driven Sway setups, scripts, and command-line workflows where opening a separate capture application is inconvenient. It also means the application can work with tools other than grim, provided they output an image file or image data that swappy accepts.

The editor provides brush, text, rectangle, ellipse, arrow, and blur modes. Color selection includes red, green, blue, and a custom color. Users can undo and redo edits, clear all paint, control stroke size, toggle transparency, center selected shapes, and enable shape filling. These controls cover common annotation tasks, but the scope remains narrower than a general raster editor.

How grim, slurp, and swappy pass image data

The documented capture flow separates selection, capture, and editing. In a Sway-oriented setup, slurp supplies a selected geometry, grim captures that geometry and writes an image to stdout, and swappy receives it through its file option. The basic command is:

grim -g "$(slurp)" - | swappy -f -

The dash after `-f` tells swappy to read from standard input. The edited result can be saved by the application according to its configuration, copied to the clipboard, or written back to stdout. The latter mode turns swappy into a pipeline stage:

grim -g "$(slurp)" - | swappy -f - -o - | pngquant -

Here, the final surface is passed to pngquant instead of being written directly to a file. This differs from applications that own both capture and editing. swappy can also open an existing PNG:

swappy -f "~/Desktop/my-gnome-saved-file.png"

That example makes the input contract less compositor-specific. The README also provides a Sway command that uses `swaymsg` and `jq` to select the rectangle of a visible window with a process ID, passes that rectangle to `slurp`, and sends the resulting capture through grim and swappy. The project therefore supports both a simple interactive selection and more selective Sway workflows, but it leaves compositor-specific geometry generation to external tools.

Building swappy from source and launching a first capture

For users whose distribution does not provide a package, the README lists meson, ninja, cairo, pango, gtk, glib2, and scdoc as build dependencies. `wl-clipboard` is optional when copied content must remain available after swappy closes. `otf-font-awesome` is optional but needed for proper icon rendering. Distribution package names can differ, so the README explicitly gives Arch Linux dependency names rather than universal package identifiers.

After installing the dependencies, configure and compile the project with meson and ninja:

meson setup build
ninja -C build

`meson setup build` creates the build directory and Meson configuration. `ninja -C build` compiles the project there. The README does not document the exact executable path or a separate installation command, so it should not be assumed that these commands install a system-wide binary.

With the binary available in the command path, the first documented use is a selected grim capture:

grim -g "$(slurp)" - | swappy -f -

A user should see the selected screenshot in swappy's editor. The listed shortcuts include `b` for Brush, `e` or `t` for Text, `r` or `s` for Rectangle, `c` or `o` for Ellipse, `a` for Arrow, and `d` for Blur. `Ctrl+z` undoes an edit, while `Ctrl+Shift+z` or `Ctrl+y` redoes it. `Ctrl+s` saves to a file, `Ctrl+c` copies to the clipboard, and `Escape`, `q`, or `Ctrl+w` quits.

Configuration for save paths and editor defaults

swappy reads the GLib `conf` file at `$XDG_CONFIG_HOME/swappy/config` or `$HOME/.config/swappy/config`. The README points to the man page for format details and provides a default configuration. This gives the project a useful degree of control over automated saves, but it also means adoption requires checking whether the existing desktop configuration already uses these keys.

A minimal starting configuration can follow the documented defaults:

[Default]
save_dir=$HOME/Desktop
save_filename_format=swappy-%Y%m%d-%H%M%S.png
show_panel=false
line_size=5
text_size=20
text_font=sans-serif
paint_mode=brush
early_exit=false
fill_shape=false
auto_save=false
custom_color=rgba(193,125,17,1)
transparent=false
transparency=50

`save_filename_format` accepts `strftime(3)` date formats. If a date format is absent, the filename has no timestamp. `line_size` must be between 1 and 50, `text_size` must be between 10 and 50, and `paint_mode` must be `brush`, `text`, `rectangle`, `ellipse`, `arrow`, or `blur`. Matching for the mode is case-insensitive.

The save directory is created when it does not exist, but the README states that swappy does not abort if creation fails. That detail matters for scripts. A user who assumes a failed directory operation will stop the application may instead receive a later save error. `early_exit` controls whether the application exits after saving or copying, while `auto_save` controls saving the final buffer to `save_dir` when the application exits.

Clipboard, fonts, PNG output, and operational limits

swappy has three documented constraints that should be checked before selecting it for a desktop workflow. First, clipboard persistence depends on `wl-clipboard` being installed. The README explains that swappy uses `wl-copy` when available and falls back to GTK when it is not. Without `wl-copy`, clipboard content can be lost when swappy closes because the GTK 3.24 Wayland backend does not provide persistent storage for this use case. A pipeline that needs clipboard content to survive process exit should therefore install `wl-clipboard`.

Second, the interface relies on Font Awesome 5 for its paint icons. The README gives this Arch Linux package example:

sudo pacman -S otf-font-awesome

That command is distribution-specific. Its presence here documents the missing dependency rather than a portable installation instruction for every Linux system. Missing icons affect presentation, not the core capture pipeline.

Third, swappy supports only PNG output. That restriction is compatible with the documented grim workflow and existing PNG files, but it prevents a direct JPEG or WebP export. Passing output through pngquant is an example of post-processing, not an alternate output format supplied by swappy. The blur tool is also an editor operation on the screenshot, not evidence that swappy provides general non-destructive image processing.

Maintenance, licensing, and the alternative workflow

The repository is not archived, and its recorded last push was on 2026-10-15. Recent releases listed for the project include `v1.8.0` on 2025-08-27, `v1.7.1` on 2025-08-18, and `v1.7.0` on 2025-08-18. The README describes the release process as relying on `standard-version`, with release tarballs signed using a listed PGP key. These facts indicate a defined release and source-build path, while they do not establish compatibility with every future Wayland toolkit release.

The project is licensed under MIT. That identifier permits use and modification under the terms of the MIT license, but this review does not interpret the legal text or provide legal advice. Developers should inspect `LICENSE` in the repository before redistributing a modified build or embedding the code in a product.

A real alternative is to use a full image editor after grim writes the capture to a file. That approach supports a wider range of file formats and editing controls, but it introduces a separate file and a second application invocation. swappy takes a narrower route: accept PNG from a capture tool, provide a focused annotation interface, and optionally return the edited surface to stdout. The choice is therefore about pipeline fit rather than feature count. Swappy is a better fit for a Sway binding that pipes a selected capture through annotation. A separate image editor is a better fit when format conversion, layer-oriented workflows, or broader editing capability matters.

Editorial conclusion

swappy is a practical choice for Sway and other Wayland workflows that produce PNG screenshots, especially when annotations must pass through a pipe. It is less suitable for users who need formats other than PNG, persistent clipboard behavior without wl-clipboard, or a screenshot application that owns the capture process itself. Verify first that your compositor and capture tools provide compatible output, install wl-clipboard if copying must survive closing swappy, and confirm the configured save directory and filename format before adopting an unattended workflow.

Frequently asked questions

Official sources

1. Issues
2. jtheoof/swappy on GitHub
3. License: MIT
4. README
5. Releases