SWAYIMGRC(5) Swayimg configuration SWAYIMGRC(5)

swayimgrc - configuration file for the Swayimg viewer

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

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

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.

Special directive include allows one to load another config file. The directive must contain the path or name of the file to load the configuration.

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

General configuration for the entire application: [general].

mode = viewer|slideshow|gallery

Mode used at startup, viewer by default.

size = fullscreen|image|W,H

Initial window size:
  • fullscreen: use full screen mode;
  • image: set size from the first frame of the first image;
  • W,H: absolute size of the window in pixels, default is 1280,720.

position = auto|X,Y

Only Sway and Hyprland: Initial window position:
  • auto: let the window manager control the window position (default);
  • X,Y: absolute coordinates of the top left corner, e.g. 100,200.

overlay = yes|no

Only Sway and Hyprland: Create a floating window with the same coordinates and size as the currently focused window. This options overrides position and size parameters. Default value is no.

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.

app_id = NAME

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

Configuration used to initialize DRM mode: [drm].

path = auto|PATH

Path to the DRM device, e.g. /dev/dri/card1, auto by default (use first available).

connector = auto|NAME

Connector name e.g. DP-1, auto by default (use first available).

mode = auto|MODE

Display resolution and frequency, e.g. 1920x1080@60, auto by default (use preferred or first available).

Configuration specific to the viewer mode: [viewer].

window = auto|extend|mirror|#COLOR

Window background:
  • auto: fill the window background in extend or mirror mode depending on the image aspect ratio;
  • extend: fill window with the current image and blur it;
  • mirror: fill window with the mirrored current image and blur it;
  • #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:
  • center: center of the window (default);
  • top: top and center horizontally;
  • bottom: bottom and center horizontally;
  • left: left and center vertically;
  • right: right and center vertically;
  • top_left: upper left corner of the window;
  • top_right: upper right corner of the window;
  • bottom_left: lower left corner of the window;
  • bottom_right: lower right corner of the window;
  • 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).

loop = yes|no

Loop image list: jump to first image when end of list is reached, yes 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.

Configuration specific to the slide show mode: [slideshow].

time = SECONDS

Slideshow image duration in seconds, 3 by default.

window

Same format as for viewer.window.

transparency

Same format as for viewer.transparency.

scale

Same format as for viewer.scale.

position

Same format as for viewer.position.

antialiasing

Same format as for viewer.antialiasing.

Configuration specific to the gallery mode: [gallery].

size = PIXELS

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

selected_scale = FLOAT

Scale of the selected tile, 1.15 by default.

aspect = fit|fill|keep

Thumbnail aspect ratio, fill by default.
  • fit: Fit image into a square thumbnail, maintaining its aspect ratio;
  • fill: Fill square thumbnail with the image, cropping its larger dimension;
  • keep: Adjust thumbnail size to the aspect ratio of the image.

padding = PIXELS

Padding between thumbnails in pixels, 5 by default.

select = #COLOR

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

background = #COLOR

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

border_color = #COLOR

Border color of the selected tile, #aaaaaaff by default.

border_width = PIXELS

Border width of the selected tile, 5 pixels by default.

window = #COLOR

Window background color in RGB or RGBA format, #00000000 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.

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

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.

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

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

show = yes|no

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

padding = PADDING

Text padding from window edges (in px), 10 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.

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.

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

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

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

Key bindings configurations are stored in sections [keys.viewer], [keys.slideshow] 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 buttons/scroll:

  • MouseLeft: Left button;
  • MouseRight: Right button;
  • MouseMiddle: Middle button;
  • MouseSide: Side button;
  • MouseExtra: Extra button;
  • ScrollUp: Mouse wheel up;
  • ScrollDown: Mouse wheel down;
  • ScrollLeft: Mouse scroll left;
  • ScrollRight: Mouse scroll right.

none

Dummy, does nothing. Can be used to remove default key bindings.

help

Show/hide help.

first_file

Go to the first file.

last_file

Go to the last file.

prev_file

Go to previous file.

next_file

Go to next file.

prev_dir

Viewer/Slideshow modes only. Go to previous directory.

next_dir

Viewer/Slideshow modes only. Go to next directory.

rand_file

Viewer/Slideshow modes only. Go to random file.

step_left

Gallery mode only. Select previous image.

step_right

Gallery mode only. Select next image.

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

Viewer/Gallery modes only. 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. Stop/continue animation.

fullscreen

Toggle full-screen mode.

mode [viewer|slideshow|gallery]

Switch between modes. Empty value to switch to previous mode.

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 [POSITION]]

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.

POSITION is one of:

  • center to zoom into and out of the center of the viewport [default];
  • mouse to zoom into and out of the mouse cursor position.

position [POSITION]

Viewer mode only. Change image position; POSITION can be one of the viewer.position directions, or empty to switch to the next position.

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

Viewer/Gallery modes only. Reset cache and reload current image.

antialiasing [MODE]

Viewer/Gallery modes only. Set anti-aliasing mode or switch if on/off, MODE is:
  • one of the viewer.antialiasing modes (none/mks13/etc);
  • empty value to toggle AA on/off.

info [MODE]

Switch or cycle text info modes.

With no MODE, the mode cycles through: off/viewer/slideshow/gallery.

If MODE is a single mode name (e.g. viewer), switch to that mode. If MODE is a comma-separated list (e.g. viewer,off), cycle through the listed modes. Spaces around commas are ignored.

Each entry must be either off or the name of a configured scheme.

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

drag

Mouse buttons in viewer mode only. Set the button for drag operation.

export FILE

Viewer mode only. Export currently displayed image to PNG file.

pause

Slideshow mode only. Pause/continue slideshow.

status TEXT

Display text in status field.

exit

Exit the application.

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

swayimg(1)

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

2026-01-13 swayimg