SWAYIMG(1)

📦
version 5.7 · 8 versions
, in arch rolling, fedora 44, nixpkgs unstable, ubuntu stonking

💖 SWAYIMG 💖

okay bestie, pull up a chair, we're talking about swayimg — that's the star of the Swayimg manual, and she's an image viewer for Wayland/DRM with Lua scripting support. yes. Lua. scripting. she's got range. 🦋

✨ NAME ✨

swayimg — image viewer for Wayland/DRM with Lua scripting support. that's the whole vibe. short, sweet, absolutely iconic. 💅

🌸 SYNOPSIS 🌸

swayimg [OPTION]... [FILE]...

so here's the tea: if you don't hand her any input files or directories, she'll just try to read all the files in the current directory. she's nosy like that. no cap. 👀

  • use - as FILE to read image data from stdin. yes, pipe it straight in, she'll take it. 🫶
  • use the prefix exec:// to get image data from stdout printed by an external command. she'll run it and slurp up whatever comes out. iconic behavior fr fr.

🎀 DESCRIPTION 🎀

Swayimg is a lightweight Wayland-native image viewer optimized for the Sway and Hyprland window managers. and like… she's got an overlay mode that simulates terminal image display?? the way that works is genuinely so cool. 😭

she supports slideshow and gallery modes, reads from stdin and external commands, and is highly customizable via Lua scripting. she's giving main character energy, honestly. 🔥

💅 OPTIONS 💅

every single one. no skipping. we don't do that here. 💖

  • -h, --help — Display help message and exit. the "who are you and what do you want" flag.
  • -V, --version — Display version information and list of supported image formats. she'll tell you everything she can read. flex. ✨
  • -v, --viewer — Force start in viewer mode.
  • -g, --gallery — Force start in gallery mode.
  • -s, --slideshow — Force start in slideshow mode.
  • -f, --from-file=FILE — Load file list from text FILE.
  • -P, --position=X,Y — Set initial position of the window (Sway/Hyperland only). yep, that's what it says. 😌
  • -S, --size=W,H — Set initial size of the window.
  • -F, --fullscreen — Start in full screen mode. cinema. 🎬
  • -c, --config=FILE — Load the specified Lua FILE instead of default one.
  • -e, --execute=LUA — Execute the specified Lua script after loading the configuration.
  • --appid=ID — Set application Id.
  • --verbose — Enable verbose output. she will NOT stop talking and honestly? we love that for her. 🗣️

⌨️ KEYS ⌨️

👑 Viewer and Slideshow

  • Esc: Exit from application
  • Enter: Switch to gallery mode
  • s: Enable/disable to slideshow mode
  • Insert: Mark/unmark currently displayed image
  • Delete: Skip image (remove from the image list)
  • f: Enable/disable full screen mode
  • a: Enable/disable anti-aliasing
  • ]: Rotate the image 90 degrees clockwise
  • [: Rotate the image 90 degrees counterclockwise
  • m: Flip image vertically
  • Shift-m: Flip image horizontally
  • t: Show/hide text info layer
  • PgDown: Show next image
  • PgUp: Show previous image
  • Shift-PgDown: Show next frame
  • Shift-PgUp: Show previous frame
  • +: Zoom in
  • -: Zoom out
  • Left/Right/Up/Down: Move around the image
  • Backspace: Reset scale and image position to defaults

Mouse bindings:

  • ScrollUp/ScrollDown/ScrollLeft/ScrollRight: Move image
  • Ctrl-ScrollUp: Zoom in
  • Ctrl-ScrollDown: Zoom out
  • MouseLeft: Move image (drag)
  • MouseRight: Drag-and-drop image to external applications
  • Esc: Exit from application
  • Home: Select first thumbnail in image list
  • End: Select last thumbnail in image list
  • Left: Select the thumbnail to the left of the current one
  • Right: Select the thumbnail to the right of the current one
  • Up: Select the thumbnail above the current one
  • Down: Select the thumbnail below the current one
  • PgUp: Select the thumbnail on the previous page
  • PgDown: Select the thumbnail on the next page
  • Enter: Switch to viewer mode
  • s: Switch to slideshow mode
  • Insert: Mark/unmark currently selected image
  • Delete: Skip image (remove from the image list)
  • f: Enable/disable full screen mode
  • a: Enable/disable anti-aliasing
  • +: Increase thumbnail size
  • -: Decrease thumbnail size
  • t: Show/hide text info layer

Mouse bindings:

  • MouseLeft: Open currently selected image in viewer
  • MouseRight: Drag-and-drop image to external applications
  • Ctrl-ScrollUp: Increase thumbnail size
  • Ctrl-ScrollDown: Decrease thumbnail size
  • ScrollUp/ScrollDown/ScrollLeft/ScrollRight: Select next image

🌈 ENVIRONMENT 🌈

the vibes she reads from the air around her. 🌬️

  • SWAYSOCK — Path to the socket file used for Sway IPC.
  • HYPRLAND_INSTANCE_SIGNATURE, XDG_RUNTIME_DIR — Path to the socket file used for Hyprland IPC.
  • XDG_CONFIG_HOME, XDG_CONFIG_DIRS, HOME — Prefix for the path to the default application config file.
  • SHELL — Shell used for executing an external command and loading an image from stdout.

⚡ SIGNALS ⚡

  • SIGUSR1, SIGUSR2 — Perform the actions specified in the config file. so you can poke her from the outside and she'll do the thing. 🫰

🍓 EXIT STATUS 🍓

The exit status is 0 if the program completed successfully and 1 if an error occurred. Other codes can be specified via Lua script. so like, slay, but also you can script your own exit codes. she trusts you. 💜

⭐ EXAMPLES ⭐

Viewing multiple files:

swayimg photo.jpg logo.png

Displaying an image received via a pipe:

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

Loading stdout from external commands:

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"

look at that. two external commands. two different tools. same penguin. 🐧✨

🌸 FILES 🌸

The application searches for and processes the init.lua file at startup. The file is a Lua script that sets initial parameters, adds hooks and changes the behavior of the program. so she's literally a whole customizable girlie. 😌

Possible file locations:

  • $XDG_CONFIG_HOME/swayimg/init.lua
  • $HOME/.config/swayimg/init.lua
  • $XDG_CONFIG_DIRS/swayimg/init.lua
  • /etc/xdg/swayimg/init.lua

💀 BUGS 💀

For suggestions, comments, bug reports, etc. visit the project homepage https://github.com/artemsen/swayimg. she's not mad, she's just disappointed. no wait — she's not even disappointed, she wants to hear from you. bestie behavior only. 🫶

okay so this is the part where I remind you: the manual is SWAYIMG(1), it's the Swayimg manual, and this whole thing is from swayimg dated 2026-03-08. mwah. go look at some pictures. 💖✨🎀🦋🌸💅
📦 where this page comes from