NSXIV(1)

👑 NSXIV(1) — General Commands Manual 👑

okay bestie, sit down, hydrate, because we're about to talk about nsxiv — the manual page, her whole lore, every single flag. no skimming, we're doing this properly. 💅

---

✨ NAME ✨

nsxiv — Neo Simple X Image Viewer. that's her. that's the whole name. iconic behavior honestly. 🦋

---

🌸 SYNOPSIS 🌸

nsxiv [-abcfHhiopqrtvZ0] [-A FRAMERATE] [-e WID] [-G GAMMA] [-g
GEOMETRY] [-N NAME] [-n NUM] [-S DELAY] [-s MODE] [-z ZOOM] FILE...

like. look at her. a whole alphabet of options and then a pile of files at the end. she's organized. she's got range. 🎀

---

💖 DESCRIPTION 💖

nsxiv is a simple image viewer for X. simple!! but do not let that word fool you, she is doing a LOT under the hood, and we're gonna appreciate every bit of it.

she has two modes of operation: image mode and thumbnail mode.

• the default is image mode, where only the current image is shown. one image. main character energy. 👑
• in thumbnail mode, you get a whole grid of tiny previews, so it's super easy to pick which image you wanna open. it's giving Pinterest board but make it local files.

ok important note before we go any further: the fullscreen mode requires an EWMH/NetWM-compliant window manager. no compliant WM, no fullscreen. that's not a vibe, that's a requirement. 😭

---

💅 OPTIONS 💅

every single flag, no crumbs left behind:

• -A, --framerate FRAMERATE — play animations with a constant frame rate set to FRAMERATE. and bestie listen, if FRAMERATE is set to 0, then animation playback is disabled. zero means bye-bye animation.
• -a, --animate — play the animations of multi-frame images. let them move, let them live. ✨
• -b — do not show the statusbar.
• --bar, --no-bar — turns the statusbar on or off. and btw --no-bar is exactly equivalent to -b, no difference at all.
• -c, --clean-cache — removes all orphaned cache files from the thumbnail cache directory, then exits. a lil spring cleaning, then she leaves. 🧹
• -e, --embed WID — embeds the nsxiv window inside the window whose ID is WID. yes, she can live inside another window. nesting, slay.
• -f, --fullscreen — starts in fullscreen mode. immediately. no build-up.
• -G, --gamma GAMMA — set image gamma to GAMMA, and the range is -32..32. mind the range bestie.
• -g, --geometry GEOMETRY — sets the window position and size. for the full tea on the GEOMETRY argument, check the GEOMETRY SPECIFICATIONS section of X(7).
• -H, --hidden[=no] — includes hidden files and directories. and the long option takes an optional "no" if you want to disable it again. so no means yes-no. 🙈
• -h, --help — prints brief usage info to standard output and exits. the quick lil "what do I do" button.
• -i, --stdin — reads the names of files to open from standard input. and this also happens if FILE is -. yes literally the single dash.
• -N, --name NAME — sets the window name to NAME — that's specifically the "Instance" name of WM_CLASS as described in ICCCM, not just any name. very specific. very official.
• -n, --start-at NUM — starts at picture number NUM. skip the line, go straight to your fave.
• -o, --stdout — writes the list of all marked files to standard output when quitting. and if you pair this with -i, --stdin, you can use nsxiv as a visual filter/pipe. hello?? that's so clever?? 🔥
• -p, --private — enables private mode. in private mode nsxiv writes no cache or temporary files at all. incognito era. 🫥
• -q, --quiet — be quiet: disables warnings to the standard error stream. she's not gonna complain, she's gonna sit there and behave.
• -r, --recursive — searches the given directories recursively for images to view. deep dive mode.
• -S, --ss-delay DELAY — starts in slideshow mode, with the delay between images set to DELAY seconds. and DELAY may be a floating-point number, so 2.5 is totally valid, we love precision. ⭐
• -s, --scale-mode MODE — sets the scale mode according to the MODE character. the supported modes are: [d]own, [f]it, [F]ill, [w]idth, [h]eight. case matters, bestie, f and F are different girls.
• -t, --thumbnail[=no] — starts in thumbnail mode. the long option accepts an optional "no" to disable it.
• -v, --version — prints version info to standard output and exits.
• -Z, --zoom-100 — the same as -z 100. just a shortcut, she's efficient.
• -z, --zoom ZOOM — sets the zoom level to ZOOM percent.
• -0, --null — use NULL-separator. with this option, the output of -o, the file-list sent to the key-handler, and the input of -i will all be separated by a NULL character. everything, all at once. 💀
• --anti-alias[=no] — enables anti-aliasing, and if you hand it no as an argument, it disables it instead.
• --alpha-layer[=no] — enables a checkerboard background for the alpha layer, and if you hand it no as an argument, it disables it instead.
• --assume-files — skips directory traversal. it's intended for when the list is known to contain only files. this avoids some initial disk operations and may reduce startup time on slow disks. speedrun strat. 🏃‍♀️
• --cache-allow, --cache-deny CACHE-PATHS — a list of directories to whitelist or blacklist for thumbnail caching. peep the THUMBNAIL CACHING section for the tea on the argument format. these two options are mutually exclusive, and if you specify them more than once, only the final one takes effect. so don't play games, the last one wins. 🎀
• --update-cache — updates the thumbnail cache (creating them if necessary) of the given arguments and exits. and yes, it can be used along with --clean-cache. combo move. ✨

---

⌨️ KEYBOARD COMMANDS ⌨️

🦋 General 🦋

these ones work in both image mode and thumbnail mode, so no matter where you are, they've got you:

• 0-9 — prefix the next command with a number (this is called count). it's like a little multiplier you attach to whatever's coming next.
• q — quit nsxiv.
• Q — quit nsxiv, but additionally prints the current filename when -o is active and no files have been marked. very specific conditions, very specific behavior.
• Return — switch to thumbnail mode / open the selected image in image mode. depends where you are, she adapts.
• f — toggle fullscreen mode.
• b — toggle the visibility of the statusbar at the bottom of the window.
• Ctrl-x — send the next key to the external key-handler. see the EXTERNAL KEY HANDLER section for more.
• g — go to the first image.
• G — go to the last image, or to image number count. the number prefix does something here!! use it!!
• r — reload image.
• D — remove the current image from the file list and go to the next image. bye bestie. 👋
• Ctrl-h, Ctrl-Left — scroll left one screen width.
• Ctrl-j, Ctrl-Down — scroll down one screen height.
• Ctrl-k, Ctrl-Up — scroll up one screen height.
• Ctrl-l, Ctrl-Right — scroll right one screen width.
• + — zoom in.
• - — zoom out.
• m — mark/unmark the current image.
• M — mark/unmark all images starting from the last marked/unmarked image up to the current one. it's a range mark, very satisfying.
• Ctrl-m — reverse all image marks.
• Ctrl-u — remove all image marks.
• N — go count marked images forward.
• P — go count marked images backward.
• { — decrease gamma correction by count steps.
• } — increase gamma correction by count steps.
• Ctrl-g — reset gamma correction.
• Ctrl-[ — decrease brightness correction by count steps.
• Ctrl-] — increase brightness correction by count steps.
• ( — decrease contrast by count steps.
• ) — increase contrast by count steps.

🌸 Thumbnail mode 🌸

these are only available in thumbnail mode, so switch over if you want them:

• h, Left — move selection left count times.
• j, Down — move selection down count times.
• k, Up — move selection up count times.
• l, Right — move selection right count times.
• R — reload all thumbnails.

💜 Image mode 💜

these are only available in image mode, bestie:

Navigate image list:

• n, Space — go count images forward.
• p, Backspace — go count images backward.
• [ — go count * 10 images backward. yes that's a multiplication, do the math.
• ] — go count * 10 images forward.
• Ctrl-6 — go to the previously viewed image. the "wait go back" key.

Handle multi-frame images:

• Ctrl-n — go count frames of a multi-frame image forward.
• Ctrl-p — go count frames of a multi-frame image backward.
• Ctrl-a, Ctrl-Space — play/stop animations of multi-frame images.

Panning:

• h, Left — scroll image 1/5 of window width or count pixels left.
• j, Down — scroll image 1/5 of window height or count pixels down.
• k, Up — scroll image 1/5 of window height or count pixels up.
• l, Right — scroll image 1/5 of window width or count pixels right.
• H — scroll to left image edge.
• J — scroll to bottom image edge.
• K — scroll to top image edge.
• L — scroll to right image edge.
• z — scroll to image center.

Zooming:

• = — set zoom level to 100%, or count%.
• w — set zoom level to 100%, but fit large images into the window.
• W — fit image to window.
• F — fill image to window.
• e — fit image to window width.
• E — fit image to window height.

Rotation:

• < — rotate image counter-clockwise by 90 degrees.
• > — rotate image clockwise by 90 degrees.
• ? — rotate image by 180 degrees.

Flipping:

• | — flip image horizontally.
• _ — flip image vertically.

Miscellaneous:

• a — toggle anti-aliasing.
• A — toggle visibility of the alpha-channel, i.e. image transparency.
• s — toggle slideshow mode and/or set the delay between images to count seconds.

---

🖱️ MOUSE COMMANDS 🖱️

🎀 Thumbnail mode 🎀

these mouse mappings live in thumbnail mode:

• Button1 — select the image. and if you double-click it, you go into image mode. double-click = commitment. 💖
• Button3 — mark/unmark the image. and if you drag while holding Button3 down, you'll mark/unmark multiple images. drag selection, we love to see it.
• Button4 — scroll up by one row.
• Button5 — scroll down by one row.
• Ctrl-Button4 — scroll up by one page.
• Ctrl-Button5 — scroll down by one page.

💅 Image mode 💅

these mouse mappings live in image mode:

• Button1 — go to the next image if the mouse cursor is in the right part of the window, or to the previous image if it's in the left part.
• Ctrl-Button1 — pan the image relative to the mouse cursor.
• Button2 — pan the image according to the mouse cursor position in the window while keeping this button pressed down.
• Button3 — switch to thumbnail mode.
• Button4 — zoom in.
• Button5 — zoom out.

---

🌈 CONFIGURATION 🌈

the following X resources are supported under "Nsxiv" (like, for example, Nsxiv.bar.font):

• window.background — color of the window background
• window.foreground — color of the window foreground
• bar.font — name of the Xft bar font
• bar.background — color of the bar background. defaults to window.background
• bar.foreground — color of the bar foreground. defaults to window.foreground
• mark.foreground — color of the mark foreground. defaults to window.foreground

peep xrdb(1) for how to actually change them. 🫶

and listen: an X resources entry with an empty value means the default (which is defined in config.h) will be used. empty = fallback, not broken.

---

⭐ WINDOW TITLE ⭐

the window title can be replaced with the output of a user-provided script, which nsxiv calls whenever any of the relevant information changes. the path of this script is:

$XDG_CONFIG_HOME/nsxiv/exec/win-title

and the arguments given to it are (where "Optional" arguments might be empty):

• $1 — resolved absolute path of the current file
• $2 — current file number
• $3 — total file count
• $4 — image width (Optional: Disabled on thumbnails mode)
• $5 — image height (Optional: Disabled on thumbnails mode)
• $6 — current zoom (Optional: Disabled on thumbnails mode)

and why does she say file instead of image? because nsxiv does not precheck that the input files are valid images. so the total file count may be different from the actual count of valid images. she's honest about it, respect. 💀

there's also an example script installed together with nsxiv as:

/usr/share/doc/nsxiv/examples/win-title

---

okay we're not done yet — part 2 is coming, so don't go anywhere bestie 💖

✨ STATUS BAR ✨

Okay so you know that lil strip at the bottom? The info sitting on the left side of the status bar can be fully swapped out for whatever a user-provided script spits out. Yes bestie, your bar, your rules. 💅

The script that nsxiv hits up every time an image gets loaded lives at $XDG_CONFIG_HOME/nsxiv/exec/image-info, and the args it gets handed are:

• $1 — path to image file (as provided by the user)
• $2 — image width
• $3 — image height
• $4 — fully resolved path to the image file

When you're in thumbnail mode, the script it calls instead is at $XDG_CONFIG_HOME/nsxiv/exec/thumb-info, and the args look like this:

• $1 — path to image file (as provided by the user)
• $2 — empty
• $3 — empty
• $4 — fully resolved path to the image file

Also there are example scripts installed right alongside nsxiv at /usr/share/doc/nsxiv/examples/image-info and /usr/share/doc/nsxiv/examples/thumb-info. Steal from them, that's literally what they're there for 🫶

---

🎹 EXTERNAL KEY HANDLER 🎹

Wanna define extra external keyboard commands? Say less. You do it with a handler program living at $XDG_CONFIG_HOME/nsxiv/exec/key-handler, and it gets invoked when you press Ctrl+x. The next key combo you press gets passed to it as its first argument.

And what comes in via stdin? The images to act upon, which are: all marked images, but only if you're in thumbnail mode and at least one image has been marked — otherwise, just the current image. That's the rule, periodt.

nsxiv(1) will block until the handler terminates. Then it checks which images have been modified and reloads them. Iconic behavior honestly 🌈

By default nsxiv(1) sends one image per-line to stdin, but the moment you use -0 the image list becomes NULL separated and the environment variable "$NSXIV_USING_NULL" gets set to 1. Noted 📝

The key combo argument looks like this: "[C-][M-][S-]KEY" — where C/M/S mean the Ctrl/Meta(Alt)/Shift modifier states, and KEY is the X keysym as listed in /usr/include/X11/keysymdef.h without the "XK_" prefix.

Now the fun part: if KEY has an uppercase equivalent, S-KEY gets resolved into it. So like, K replaces S-k and Scedilla replaces S-scedilla — but S-Delete is sent as-is. No glow-up for that one, sorry 💀

There's also an example script installed together with nsxiv at /usr/share/doc/nsxiv/examples/key-handler. Go look, bestie.

---

🖼️ THUMBNAIL CACHING 🖼️

nsxiv stores all thumbnails under $XDG_CACHE_HOME/nsxiv/. Cozy little home for them.

Use the command line option -c to remove all orphaned cache files. And after that, run this command inside the cache directory to clean out the empty subdirectories too:

find . -depth -type d -empty ! -name '.' -exec rmdir {} \;

The options --cache-allow or --cache-deny let you whitelist or blacklist certain directories from being cached. The argument is a : separated list of paths, and a * at the beginning of a path means that path should be matched recursively.

For example: --cache-allow "/user/pictures:*/media/pictures" whitelists the "/user/pictures" directory non-recursively and the "/media/pictures" directory recursively. Nothing outside these two directories will be cached. And --cache-deny "*/secret" enables blacklist mode and will not cache anything inside "/secret" or it's subdirectories. 🕵️♀️

Heads up: those paths are shown exactly as the original page has them — /user/pictures and so on. Copy carefully, no cap.

---

👑 ORIGINAL AUTHOR 👑

• Bert Muennich — <ber.t at posteo.de>

---

💜 CURRENT MAINTAINERS 💜

• NRK — <nrk at disroot.org>
• Berke Kocaoğlu — <berke.kocaoglu at metu.edu.tr>
• TAAPArthur — <taaparthur at gmail.com>
• eylles — <ed.ylles1997 at gmail.com>
• Stein Gunnar Bakkeby — <bakkeby at gmail.com>
• explosion-mental — <explosion0mental at gmail.com>

The whole squad carrying this thing, we love to see it 🫶✨

---

🌈 CONTRIBUTORS 🌈

For a list of contributors, run git shortlog -s in the nsxiv git repository. Main character energy from everyone who ever sent a patch, fr fr 💖

---

🌸 HOMEPAGE 🌸

Website:

https://nsxiv.codeberg.page/

Source code:

https://codeberg.org/nsxiv/nsxiv

---

🔍 SEE ALSO 🔍

X(7), xrdb(1)

---

And that's the whole page, bestie — literally all of it 🎀 This was nsxiv-34, the NSXIV(1) manual page, and you survived the whole read. Genuinely proud of you for making it all the way to the bottom. Now go press Ctrl+x and write a key-handler like the icon you are 💅🦋