Swayimg: a Wayland and DRM image viewer configured in Lua

A viewer built around external codec libraries

Swayimg is a fully customizable image viewer with Lua scripting support, written in C++ and described in the repository as an image viewer for Wayland and DRM. What makes it interesting is the format list, because nearly every entry in it is an external library rather than a decoder written by the author. JPEG comes via libjpeg, JPEG XL via libjxl, JPEG 2000 via OpenJPEG, PNG via libpng, GIF via giflib, SVG via librsvg, WebP via libwebp, HEIF and HEIC via libheif, AV1F and AVIFS via libavif, TIFF via libtiff, Sixel via libsixel, camera raw formats such as CRW, CR2 and NEF via libraw, and EXR via OpenEXR. Krita files are handled through minizip-ng and libpng. Only a handful of formats are built in: BMP, PNM, TGA, XBM, QOI, DICOM and Farbfeld. The consequence is practical rather than abstract. If your images are AVIF or JPEG XL, the viewer can show them, but the dependency is a system package you have to install before the build succeeds.

It also previews things that are not images

Two entries on the feature list are not image formats at all, and they are the ones that distinguish this from a plain picture viewer. Fonts are previewed, with TTF, OTF and WOFF handled through FreeType. Video is previewed in storyboard, using FFMpeg, which means the viewer will show a strip of frames for a video file rather than refusing it. Alongside the decoding side, the viewer reads EXIF, XMP and IPTC metadata tags, which is what makes it usable as a photograph triage tool rather than just a way to look at a PNG. The rest of the feature list covers behaviour you would expect from a viewer with a gallery. There are gallery and viewer modes with a slideshow, support for image animation, loading from files, from pipes and from external programs, and preloading of images in a separate thread so the next image is ready before you ask for it. The separate preload thread is worth noting for anyone opening large directories: it is the difference between a viewer that stutters on a folder of raw files and one that does not.

Sway and Hyprland support, including the overlay trick

Support for the Sway and Hyprland window managers is listed as its own item, and it includes a feature that goes beyond simply opening a window on those compositors. The overlay feature simulates displaying an image in the currently active window, for example a terminal. In practice that means you can view an image without leaving your working context, which is the sort of thing that makes a viewer feel like part of a window manager setup rather than a standalone application. The README also states native support for Wayland and DRM output, and the project title itself names both. That last point is the hard boundary of the tool. DRM output is a different rendering path from a Wayland surface, and there is no X11 support in the feature list, so on an X11 session this is the wrong viewer regardless of how well the format support would serve you.

Running it, including from pipes and from shell commands

The command line is a single invocation with options and files, written as `swayimg [OPTIONS]... [FILE]...`, and the README gives three examples. Viewing multiple files at once is the simplest:

  swayimg photo.jpg logo.png

Reading from a pipe is the second, and it shows that the viewer accepts standard input:

  wget -qO- https://www.kernel.org/theme/images/logos/tux.png | swayimg -

The third loads the standard output of external commands directly, using an exec:// prefix on each entry:

  swayimg "exec://wget -qO- https://www.kernel.org/theme/images/logos/tux.png" \
          "exec://curl -so- https://www.kernel.org/theme/images/logos/tux.png"

That last form is the one to copy if you want to fetch an image and view it without writing it to disk first. The full option set is documented separately in USAGE.md, which the README points to for details.

The configuration file is a Lua script, not a key-value file

This is the part of the design that separates Swayimg from most viewers. The configuration file is a Lua script, and the README says the full list of available functions is described in the CONFIG.md documentation and in the Lua source at extra/swayimg.lua. Keyboard bindings, colors and many other parameters are all customised through those Lua bindings. That means the configuration is a program rather than a data file, so anything Lua can express is available, at the cost of a configuration error being a script error rather than a message about a bad value. The README also points to TIPS.md for tips and tricks, and notes that an example configuration from extra/example.lua is installed to /usr/share/swayimg/example.lua, so a working reference exists on disk once the program is installed. The repository layout supports the picture: a src directory for the C++ code, an extra directory for the Lua side, a test directory, and separate USAGE.md, CONFIG.md and TIPS.md documents, with .clang-format and .clang-tidy at the root for the C++ side.

Building it with Meson, and installing it from a distribution

The build system is Meson, and the README gives the three commands as a complete sequence:

meson setup my_build_dir
meson compile -C my_build_dir
meson install -C my_build_dir

A separate build directory keeps generated files out of the source tree, and the meson.options file at the repository root is where build options live, which is how you would disable the codec libraries you do not want to depend on. For installation, the README points to Repology for the list of supported distributions, and the packaging status badge is served from the same project page. Arch users have two routes given in the README: the extra repository or the AUR swayimg-git package. The Repology route is the general answer for everyone else, since it lists which distributions carry the package and at which version, which also tells you how quickly a new upstream release reaches your system. Nothing in the README describes a static binary or a portable build, so the distribution package or a local Meson build are the two realistic paths.

Frequent releases, MIT licensed, and the limits of the description

The project is MIT licensed and shipping steadily, with v5.6 released on 2026-09-05, v5.5 on 2026-07-26 and v5.4 on 2026-06-21, and the last push to the repository was on 2026-10-18. A viewer that releases every few weeks is one you can reasonably track, and the release numbering suggests the maintainer treats it as a finished tool rather than an experiment. Two gaps in the documentation are worth naming. The README does not enumerate the command-line options, deferring to USAGE.md, so you should read that file rather than guess at flags. It also does not document what happens with extremely large images or with directories containing many files, beyond noting the separate preload thread and that the format list leans on third-party decoders, so memory behaviour on a folder of high resolution photographs is something you will need to observe on your own hardware. What the README does give is an unusually complete format matrix, and that matrix is the honest summary of what this tool is: a viewer for people with varied image collections, on Wayland, driven from the keyboard.

Editorial conclusion

Swayimg suits someone on Sway or Hyprland who wants a keyboard-driven image viewer that opens from a terminal, handles unusual formats such as JPEG XL, AVIF and camera raw files, and can be scripted in Lua to fit an existing window manager workflow. It is the wrong tool for X11 users, since native support is for Wayland and DRM output, and it is the wrong tool if you want a graphical image editor, since the README describes a viewer with gallery mode and slideshow rather than editing features. Verify first that your compositor is one of the supported ones, since the Sway and Hyprland integration including the overlay feature is listed separately from the Wayland and DRM support, and confirm that the codec libraries for the formats you care about are present before you build, because the format list is mostly made of external library dependencies.

Frequently asked questions

Official sources

1. artemsen/swayimg on GitHub
2. Issues
3. License: MIT
4. README
5. Releases