SWAYIMGRC(5)

📦

version 4.7 · 6 versions

4.7 · fedora 43, nixos 26.05, ubuntu resolute (latest)
1.6 · ubuntu jammy
4.5 · fedora 43
2.1 · ubuntu noble
1.10 · debian bookworm
3.8 · debian trixie, ubuntu questing

, in fedora 43, nixos 26.05, ubuntu resolute

✨ SWAYIMGRC(5) — the Swayimg config glow-up ✨

okay bestie, listen up 💖 this is the manual page for swayimgrc — the configuration file for the Swayimg viewer. it's giving "little text file, huge main character energy" and honestly? we're obsessed.

🌸 NAME 🌸

swayimgrc — the configuration file for the Swayimg viewer. yeah, that's the whole name section, she's short but she's iconic 💅

🎀 SYNOPSIS 🎀

so the Swayimg configuration file is a text-based INI file, and its whole job is to override the default settings. that's it, that's the gig. lowkey powerful fr fr ✨

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

🦋 LOCATION 🦋

Swayimg goes looking for a config file in these exact spots, in this exact order — no skipping, no shuffling, she's very methodical about it:

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

first one she finds wins, periodt. 💅

🌈 DESCRIPTION 🌈

okay so here's the tea ☕ — the structure of the INI file is made of key-value pairs for properties, plus sections that organize those properties. simple, clean, no drama.

💬 Comments and blank lines

a number sign (#) at the beginning of a line means "this is a comment, ignore her." empty lines and comments? straight up ignored. they're just vibing, contributing nothing, and that's fine 🫶

🔑 Keys (a.k.a. properties)

the basic element inside the INI file is the key, also called a property. every key has a name and a value, and they're separated by an equals sign (=). the name lives on the left of the equals sign. the value can contain literally any characters — she's unbothered, she's free, she's expansive ✨

📦 Sections

keys get grouped into named sections. the section name sits on a line by itself, wrapped in square brackets. every key that comes after the section declaration belongs to that section. so basically sections are friend groups and the keys are the members 💖

📥 The `include` directive

there's a special directive called include that lets you load another config file. the directive has to contain the path or the name of the file you want to load the configuration from. it's giving "bring your friend to the party" energy 🎀

🛠️ Overriding stuff from the command line

any option can be overridden using the --config argument on the command line. for instance:

swayimg  --config="general.mode=gallery"

see how easy that was? slay. 👑

ngl, that's a lot of ground covered already and we're only getting started. more sections incoming, bestie — don't go anywhere 💜

✨ SECTIONS ✨

okay bestie, this is the big one — all the config sections you can tweak. it's giving "control freak but make it cute" 💅 let's go section by section, no cap.

🌸 General 🌸

This is the main character config for the whole app, fr. Everything here lives under [general] and sets the vibe for how swayimg starts up. ✨

mode = viewer|slideshow|gallery — which mode we're in when you launch. default is viewer, obviously. 😌
size = fullscreen|image|W,H — how big the window is when it pops off:
- 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, bestie. where the window starts:
- 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 option 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.

🌀 DRM mode settings 🌀

Configuration used to initialize DRM mode, under [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).

👑 Viewer 👑

Configuration specific to the viewer mode, under [viewer]. this is where you make it look iconic. 💅

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.

🎬 Slide show 🎬

Configuration specific to the slide show mode, under [slideshow]. it's giving automatic vibes. ✨

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.

🖼️ Gallery 🖼️

Configuration specific to the gallery mode, under [gallery]. thumbnail time, bestie. 📸

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

📋 Image list 📋

Configuration of the image list, under [list]. sorting and monitoring, periodt. 🗂️

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 🖋️

Font configuration, under [font]. make your text look cute. 💖

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, under [info]. the tea on your on-screen 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.

🧐 Text info: viewer mode 🧐

Layout of fields for displaying text info in viewer mode, under [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).

🎞️ Text info: slide show mode 🎞️

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

🖼️ Text info: gallery mode 🖼️

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

⌨️ Key bindings ⌨️

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.

💖 Actions 💖

okay bestie, this is the fun part — these are literally all the things you can make swayimg do when you press a key. every single one, no skipping, we're doing this properly ✨

`none`

Dummy action. does absolutely nothing. zero. nada. its whole job is to sit there so you can yeet a default key binding into the void by assigning it this 🫶

`help`

Show or hide the help.

`first_file`

Jump to the first file.

`last_file`

Jump to the last file.

`prev_file`

Go to the previous file.

`next_file`

Go to the next file.

`prev_dir`

Viewer/Slideshow modes only. Go to the previous directory.

`next_dir`

Viewer/Slideshow modes only. Go to the next directory.

`rand_file`

Viewer/Slideshow modes only. Go to a random file. chaos mode, we love her 🎲

`step_left`

Gallery mode only. Select the previous image.

`step_right`

Gallery mode only. Select the next image.

`step_up`

Gallery mode only. Select the image above.

`step_down`

Gallery mode only. Select the image below.

`page_up`

Gallery mode only. Scroll the page up.

`page_down`

Gallery mode only. Scroll the page down.

`skip_file`

Viewer/Gallery modes only. Skip the current file — which literally means removing it from the image list. it's gone bestie, so be sure that's what you meant 💀

`prev_frame`

Viewer mode only. Show the previous frame.

`next_frame`

Viewer mode only. Show the next frame.

`animation`

Viewer mode only. Stop or continue the animation.

`fullscreen`

Toggle full-screen mode. main character energy, maximised 👑

`mode [viewer|slideshow|gallery]`

Switch between modes. give it an empty value and it hops back to the previous mode you were in.

`step_left [PERCENT]`

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

`step_right [PERCENT]`

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

`step_up [PERCENT]`

Viewer mode only. Move the viewport up, default is 10%.

`step_down [PERCENT]`

Viewer mode only. Move the viewport down, default is 10%.

`zoom [SCALE [POSITION]]`

Viewer mode only. This one handles all the scaling, and SCALE can be:

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

and 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 the image position. POSITION can be any of the viewer.position directions, or empty to switch to the next position.

`rotate_left`

Viewer mode only. Rotate the image anticlockwise.

`rotate_right`

Viewer mode only. Rotate the image clockwise.

`flip_vertical`

Viewer mode only. Flip the image vertically.

`flip_horizontal`

Viewer mode only. Flip the image horizontally.

`thumb SIZE`

Gallery mode only. Resize the thumbnails, where SIZE is:

a delta in pixels with a + or - sign (like +10);
an absolute size in pixels, like 200.

`reload`

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

`antialiasing [MODE]`

Viewer/Gallery modes only. Set the anti-aliasing mode, or switch it if it's on/off. MODE is:

one of the viewer.antialiasing modes (none/mks13/etc);
an empty value to toggle AA on/off.

`info [MODE]`

Switch or cycle through the text info modes.

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

if MODE is a single mode name (like viewer), it switches to that mode. if MODE is a comma-separated list (like viewer,off), it cycles through the modes you listed. spaces around the commas are ignored, she's chill like that 💅

each entry has to be either off or the name of a configured scheme.

`exec COMMAND`

Run an external command. use % to substitute the full path to the current image, and %% to escape a %. Swayimg waits for child processes to finish — so if you want to "detach" the child process from Swayimg, call another launcher instead, for example:

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

`drag`

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

`export FILE`

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

`pause`

Slideshow mode only. Pause or continue the slideshow.

`status TEXT`

Display text in the status field.

`exit`

Exit the application. bye bestie 🦋

🌸 EXAMPLES 🌸

there's a sample file chilling in the project repository: https://github.com/artemsen/swayimg/blob/master/extra/swayimgrc — or locally after installation at /usr/share/swayimg/swayimgrc. go look, it's giving inspo ✨

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

👀 SEE ALSO 👀

swayimg(1)

🐛 BUGS 🐛

got suggestions, comments, bug reports, literally anything? come hang out at the project homepage: https://github.com/artemsen/swayimg. they wanna hear from you fr fr 💜

and that's the whole thing, bestie — you made it to the end of SWAYIMGRC(5) from swayimg, dated 2026-01-13. slay, go configure something iconic 💖✨

📦 where this page comes from

fedora 43: swayimg 4.7-1.fc43 · MIT
nixos 26.05: swayimg 4.7
ubuntu resolute: swayimg 4.7-1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms

SWAYIMGRC(5)

✨ SWAYIMGRC(5) — the Swayimg config glow-up ✨

🌸 NAME 🌸

🎀 SYNOPSIS 🎀

🦋 LOCATION 🦋

🌈 DESCRIPTION 🌈

💬 Comments and blank lines

🔑 Keys (a.k.a. properties)

📦 Sections

📥 The include directive

🛠️ Overriding stuff from the command line

✨ SECTIONS ✨

🌸 General 🌸

🌀 DRM mode settings 🌀

👑 Viewer 👑

🎬 Slide show 🎬

🖼️ Gallery 🖼️

📋 Image list 📋

🖋️ Font 🖋️

📝 Text info: general configuration 📝

🧐 Text info: viewer mode 🧐

🎞️ Text info: slide show mode 🎞️

🖼️ Text info: gallery mode 🖼️

⌨️ Key bindings ⌨️

💖 Actions 💖

none

help

first_file

last_file

prev_file

next_file

prev_dir

next_dir

rand_file

step_left

step_right

step_up

step_down

page_up

page_down

skip_file

prev_frame

next_frame

animation

fullscreen

mode [viewer|slideshow|gallery]

step_left [PERCENT]

step_right [PERCENT]

step_up [PERCENT]

step_down [PERCENT]

zoom [SCALE [POSITION]]

position [POSITION]

rotate_left

rotate_right

flip_vertical

flip_horizontal

thumb SIZE

reload

antialiasing [MODE]

info [MODE]

exec COMMAND

drag

export FILE

pause

status TEXT

exit