swayimgrc - Man Page

configuration file for the Swayimg viewer

Synopsis

The Swayimg configuration file is a text-based INI file used to override the default settings.

Location

Swayimg searches for a config file in the following locations, in this order:

$XDG_CONFIG_HOME/swayimg/config
$HOME/.config/swayimg/config
$XDG_CONFIG_DIRS/swayimg/config
/etc/xdg/swayimg/config

Description

The structure of the INI file consists of key-value pairs for properties and sections that organize properties.

The number sign (#) at the beginning of the line indicates a comment. Empty lines and comments are ignored.

The basic element contained in the INI file is the key or property. Every key has a name and a value, delimited by an equals sign (=). The name appears to the left of the equals sign. The value can contain any characters.

Keys are grouped into named sections. The section name appears on a line by itself, in square brackets. All keys after the section declaration are associated with that section.

Any option can be overridden using the --config argument in the command line, for instance: swayimg --config="general.mode=gallery".

Sections

General

General configuration for the entire application: [general].

mode = viewer|gallery

Mode used at startup, viewer by default.

position = parent|X,Y

Initial window position, this option valid only in Sway WM:

parent: set position from parent (currently active) window (default);
X,Y: absolute coordinates of the top left corner, e.g. 100,200.

size = fullscreen|parent|image|W,H

Initial window size:

fullscreen: use full screen mode;
parent: [Only in Sway WM] set size from parent (currently active) window (default);
image: set size from the first loaded image;
W,H: absolute size of the window in pixels, e.g. 320,240.

decoration = yes|no

Use window decoration (borders and title), no by default.

sigusr1 = ACTION

Action to be performed when the SIGUSR1 signal is triggered, reload by default.

sigusr2 = ACTION

Action to be performed when the SIGUSR2 signal is triggered, next_file by default.

compositor = yes|no

Only Sway and Hyprland: Enable or disable integration with the compositor, yes by default. This feature provides some features such as setting the window position, this allows to create an "overlay" above the currently active window.

app_id = NAME

Application ID used as window class name, swayimg by default.

Viewer

Configuration specific to the viewer mode: [viewer].

window = blur|#COLOR

Window background:

blur: fill window with the current image and blur it, can be useful for slideshow mode;
#COLOR: solid color in RGB or RGBA, #00000000 by default;

transparency = grid|#COLOR

Background for transparent images:

grid: draw chessboard (default);
#COLOR: solid color in RGB or RGBA, e.g #10ff4280.

scale = MODE

Initial image scale:

optimal: 100% or less to fit to window (default);
width: fit image width to window width;
height: fit image height to window height;
fit: fit to window;
fill: crop image to fill the window;
real: real size (100%);
keep: keep the same scale as for previously viewed image.

position = POSITION

Initial image position on the window:

top: move image to top and center by width;
center: center by width and height (default);
bottom: move to bottom and center by width;
left: move to left and center by height;
right: move to right and center by height;
topleft: move to top and left;
topright: move to top and right;
bottomleft: move to bottom and left;
bottomright: move to bottom and right;
free: like center, but freely movable (not fixed).

antialiasing = METHOD

Anti-aliasing method when scaling images. In general, the methods improve in quality and decrease in performance from top to bottom:

none: nearest-neighbor, or no anti-aliasing;
box: nearest-neighbor on upscale, average in a box on downscale;
bilinear: bilinear;
bicubic: bicubic with the Catmull-Rom spline;
mks13: Magic Kernel with the 2013 Sharp approximation (default).

slideshow = yes|no

Run slideshow at startup, no by default.

slideshow_time = SECONDS

Slideshow image duration in seconds, 3 by default.

history = SIZE

Number of previously viewed images to store in cache, 1 by default.

preload = SIZE

Number of images to preload in a separate thread, 1 by default.

Gallery

Configuration specific to the gallery mode: [gallery].

size = PIXELS

Height and width of each thumbnail in pixels, 200 by default.

cache = SIZE

Max number of invisible thumbnails stored in memory cache, 100 by default.

preload = yes|no

Load not only visible but also adjacent thumbnails, no by default. The cache parameter limits the number of preloaded thumbnails.

pstore = yes|no

Enable/disable storing thumbnails in persistent storage, no by default. If enabled, thumbnails will be stored in XDG_CACHE_HOME/swayimg.

fill = yes|no

Fill the entire tile with thumbnail, yes by default.

antialiasing = METHOD

Anti-aliasing method when scaling images. In general, the methods improve in quality and decrease in performance from top to bottom:

none: nearest-neighbor, or no anti-aliasing;
box: nearest-neighbor on upscale, average in a box on downscale;
bilinear: bilinear;
bicubic: bicubic with the Catmull-Rom spline;
mks13: Magic Kernel with the 2013 Sharp approximation (default).

window = #COLOR

Window background color in RGB or RGBA format, #00000000 by default.

background = #COLOR

Background color of non-selected tiles, #202020ff by default.

select = #COLOR

Background color of the selected tile, #404040ff by default.

border = #COLOR

Border color of the selected tile, #000000ff by default.

shadow = #COLOR

Shadow color of the selected tile, #000000ff by default.

Image list

Configuration of the image list: [list].

order = ORDER

Order of the image list:

none: unsorted;
alpha: sorted alphabetically (default);
numeric: sorted numerically;
mtime: sorted by file modification time;
size: sorted by file size;
random: randomize list.

reverse = yes|no

Reverse sort order, no by default.

loop = yes|no

Looping file list mode, yes by default.

recursive = yes|no

Read directories recursively, no by default.

all = yes|no

Add all files from the same directory as the first file. This option is ignored if more than one input file is specified. Default value is no.

fsmon = yes|no

Enable file system monitoring to automatically update the image list, yes by default.

Font

Font configuration: [font].

name = NAME: Font name, monospace by default.
size = SIZE: Font size (in pt), 14 by default.
color = #COLOR: Text color, #ccccccff by default.
shadow = #COLOR: Text shadow color, #000000d0 by default. To disable shadow use fully transparent color #00000000.
background = #COLOR: Text background color, #00000000 (fully transparent) by default.

Text info: general configuration

General configuration of the displayed text layer: [info].

show = yes|no

Enable or disable info text at startup, yes by default.

info_timeout = SECONDS

Timeout of image information displayed on the screen, 0 to always show, 5 by default.

status_timeout = SECONDS

Timeout of the status message displayed on the screen, 3 by default.

Text info: viewer mode

Layout of fields for displaying text info in viewer mode: [info.viewer]. The layout describes what metadata should be displayed in each corner of the window. The list can contain any number of fields separated by commas. A plus sign preceding a field name adds the field title to the display.

top_left = LIST: Top left corner of the window. Default is +name,+format,+filesize,+imagesize,+exif.
top_right = LIST: Top right corner of the window. Default is index.
bottom_left = LIST: Bottom left corner of the window. Default is scale,frame.
bottom_right = LIST: Bottom right corner of the window. Default is status.

Avalable fields:

name: File name of the currently viewed/selected image.
dir: Parent directory name of the currently viewed/selected image.
path: Absolute path or special source string of the currently viewed/selected image.
filesize: File size in human-readable format.
format: Brief image format description.
imagesize: Size of the image (or its current frame) in pixels.
exif: List of EXIF data.
frame: Current and total number of frames.
index: Current and total index of image in the image list.
scale: Current image scale in percent.
status: Status message.
none: Empty field (ignored).

Text info: gallery mode

Layout of fields for displaying text info in gallery mode: [info.gallery]. The format is the same as [info.viewer]:

top_left = LIST: Top left corner of the window. Default is none.
top_right = LIST: Top right corner of the window. Default is none.
bottom_left = LIST: Bottom left corner of the window. Default is none.
bottom_right = LIST: Bottom right corner of the window. Default is name,status.

Key bindings

Key bindings configurations are stored in sections [keys.viewer] and [keys.gallery]. Each line associates a key with a list of actions and optional parameters. Actions are separated by semicolons. One or more key modifiers (Ctrl, Alt, Shift) can be specified in the key name. The key name can be obtained with the xkbcli tool: xkbcli interactive-wayland.

Predefined names for mouse scroll:

ScrollUp: Mouse wheel up;
ScrollDown: Mouse wheel down;
ScrollLeft: Mouse scroll left;
ScrollRight: Mouse scroll right.

Actions

none Dummy, can be used to remove a built-in action.

help Show/hide help.

first_file Go to the first file.

last_file Go to the last file.

prev_dir (Viewer mode only) Go to previous directory.

next_dir (Viewer mode only) Go to next directory.

prev_file Go to previous file.

next_file Go to next file.

rand_file (Viewer mode only) Go to random file.

step_left (Gallery mode only) Select previous image.

step_right (Gallery mode only) Select image above.

step_up (Gallery mode only) Select image above.

step_down (Gallery mode only) Select image below.

page_up (Gallery mode only) Scroll page up.

page_down (Gallery mode only) Scroll page down.

skip_file Skip the current file (remove it from the image list).

prev_frame (Viewer mode only) Show previous frame.

next_frame (Viewer mode only) Show next frame.

animation (Viewer mode only) Start/stop animation.

slideshow (Viewer mode only) Start/stop slideshow.

fullscreen Toggle full-screen mode.

mode [viewer|gallery]

Switch between viewer and gallery modes.

step_left [PERCENT]

(Viewer mode only) Move viewport left, default is 10%.

step_right [PERCENT]

(Viewer mode only) Move viewport right, default is 10%.

step_up [PERCENT]

(Viewer mode only) Move viewport up, default is 10%;

step_down [PERCENT]

(Viewer mode only) Move viewport down, default is 10%;

zoom [SCALE]

(Viewer mode only) Manage scaling, SCALE is:

one of the viewer.scale modes (fit/fill/etc);
percentage number with + or - sign (e.g. +10) to zoom in or out;
absolute value in percentage to set the scale, e.g. 200;
empty value to switch to the next available scaling mode.

rotate_left (Viewer mode only) Rotate image anticlockwise.

rotate_right (Viewer mode only) Rotate image clockwise.

flip_vertical (Viewer mode only) Flip image vertically.

flip_horizontal (Viewer mode only) Flip image horizontally.

thumb SIZE

(Gallery mode only) Resize thumbnails, SIZE is:

delta in pixels with + or - sign (e.g. +10);
absolute size in pixels, e.g. 200.

reload Reset cache and reload current image.

antialiasing [MODE]

Set anti-aliasing mode or cycle through them, MODE is:

one of the viewer.antialiasing modes (none/mks13/etc);
next or empty value: switch to next mode;
prev: switch to previous mode.

info [MODE]

Set text info mode or cycle through them, MODE is on of off/viewer/gallery or empty value to switch to next mode.

exec COMMAND

Execute an external command, use % to substitute the full path to the current image, %% to escape %. Swayimg waits for child processes to complete, to "detach" the child process from Swayimg, call any another launcher, for example:

Sway: `swaymsg exec ...`;
Hyprland: `hyprctl dispatch exec ...`;
Niri: `niri msg action spawn ...`.

export FILE

Export currently displayed image to PNG file.

status TEXT

Set and show status text.

exit Exit the application.

Examples

Sample file is available on the project repository: https://github.com/artemsen/swayimg/blob/master/extra/swayimgrc or locally after installation: /usr/share/swayimg/swayimgrc.

  # comment
  [list]
  order = random
  [font]
  size = 16
  [keys]
  Ctrl+Alt+e = exec echo "%" > mylist.txt

Bugs

For suggestions, comments, bug reports, etc. visit the project homepage https://github.com/artemsen/swayimg.

Referenced By

swayimg(1).

2025-06-09 Swayimg configuration