swayimg(1)

Usage

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

Overview

Swayimg is a lightweight Wayland-native image viewer optimized for the Sway and Hyprland window managers, featuring an overlay mode that simulates terminal image display. The application supports slideshow and gallery modes, reads from stdin and external commands, and is highly customizable via Lua scripting.

Options

-h, --help: Display help message and exit.

-V, --version: Display version information and list of supported image formats.

-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).

-S, --size=W,H: Set initial size of the window.

-F, --fullscreen: Start in full screen mode.

-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.

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

Gallery

`•`	`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

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.

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.

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"

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.

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

Releases

3 releases since Debian 12 (Bookworm); the text changed 2 times.

--appid since Arch Linux 2026-11-01; --config since Debian 13 (Trixie); --execute since Arch Linux 2026-11-01; --from-file since Arch Linux 2026-11-01; --gallery since Debian 13 (Trixie); --position since Debian 13 (Trixie); --size since Debian 13 (Trixie); --verbose since Arch Linux 2026-11-01; --viewer since Arch Linux 2026-11-01; -F since Arch Linux 2026-11-01; -P since Arch Linux 2026-11-01; -S since Arch Linux 2026-11-01; -V since Arch Linux 2026-11-01; -e since Arch Linux 2026-11-01.

--all until Debian 12 (Bookworm); --background until Debian 12 (Bookworm); --class until Debian 13 (Trixie); --geometry until Debian 12 (Bookworm); --info until Debian 12 (Bookworm); --mark until Debian 12 (Bookworm); --no-sway until Debian 12 (Bookworm); --order until Debian 13 (Trixie); --recursive until Debian 13 (Trixie); --scale until Debian 13 (Trixie); --window until Debian 12 (Bookworm); -a until Debian 13 (Trixie); -b until Debian 12 (Bookworm); -i until Debian 12 (Bookworm); -l until Debian 13 (Trixie); -m until Debian 12 (Bookworm); -n until Debian 12 (Bookworm); -o until Debian 13 (Trixie); -p until Debian 13 (Trixie); -r until Debian 13 (Trixie); -w until Debian 13 (Trixie).

Referred to by

swayimgrc(5) configuration file for the Swayimg viewer