nsxiv: a maintained sxiv fork for the X11 desktop

Why sxiv needed a fork in the first place

nsxiv is a fork of sxiv, and the README is blunt about the reason: the original is "now-unmaintained". The upstream project by xyb3rt stopped receiving work, and the fork describes its own purpose as being "a (mostly) drop-in replacement for sxiv, maintaining its interface and adding simple, sensible features."

That framing matters for anyone deciding between the two. nsxiv is not a redesign with a different key layout and a new opinion about how image viewers should behave. The explicit goal is interface compatibility, which is what makes it a plausible replacement for a keyboard-driven workflow rather than a switch to a different tool.

The repository itself is also unusual. The GitHub repository is a read-only mirror, and the badge in the README points at Codeberg as the host, with the project homepage and the issue tracker on Codeberg as well. Bug reports are asked for on Codeberg, and only after checking that the reporter is on the latest release.

The licence is GPL-2.0-or-later, and the stated aim is to be easy to modify and customise. Written in C, with the file list in the repository root showing the small, flat structure typical of this kind of program: main.c, image.c, window.c, thumbs.c, commands.c, options.c and autoreload.c, with a single Makefile and a config.def.h.

The feature set nsxiv adds over sxiv

The README lists the features, and the additions are modest and specific.

Thumbnail mode gives a grid of selectable previews of all images, and the ability to cache thumbnails is listed separately so re-loading a directory is fast. Automatically refreshing modified images means a file replaced on disk is picked up without a restart. Displaying image information in the status bar is handled through the `image-info` and `thumb-info` options, and the window title can be customised through `win-title`.

Scriptability comes through `key-handler`, which lets a key run an external command. That is the hook for anything the program itself does not do, and it is also the reason the project leans on small shell scripts for the cases it does not want to build in.

Alongside those sit the basics: zooming, panning, rotating, and basic support for animated or multi-frame images. Keyboard and mouse mappings are customisable through `config.h`.

There is one more feature worth flagging because it depends on a third party service. The README notes that nsxiv-extra exists as a separate repository for patches and scripts, following the spirit of suckless software, and that the project scope is deliberately limited so that certain features or customisations cannot be merged into the mainline.

Dependencies, and the ones you can switch off

Two packages are required: X11, and Imlib2 version 1.11 or later built with X11 support. Imlib2 is the image loading and scaling library, and the X11 requirement is the reason this viewer belongs on an X11 session rather than a modern Wayland desktop.

Three optional dependencies can each be disabled at compile time.

`inotify` is used for auto-reloading images on change, and is disabled via `HAVE_INOTIFY=0`. The README explains that inotify is a Linux-specific API for monitoring filesystem changes, not natively available on BSD systems, though it can be enabled there by installing and linking against libinotify-kqueue.

`libXft`, `freetype2` and `fontconfig` are used for the status bar and are disabled via `HAVE_LIBFONTS=0`. `libexif` is used for auto-orientation and exif thumbnails, disabled via `HAVE_LIBEXIF=0`.

The Makefile shows how these become compile flags: `nsxiv_cppflags` passes `-DHAVE_LIBEXIF`, `-DHAVE_LIBFONTS` and `-DHAVE_INOTIFY` into every translation unit, and the link line pulls `-lImlib2 -lX11` plus the optional `-lexif` and `-lXft -lfontconfig`. A single `OPT_DEP_DEFAULT=0` disables all optional dependencies at once, which is a useful starting point on a system where one of the development packages is missing.

The README also asks users to install the corresponding development packages where a distribution separates runtime and development packages, for example the `*-dev` packages on Debian.

Building and installing from source

The build is a plain make invocation with no configure step. The Makefile targets a `.POSIX` layout and includes config.mk.

$ make

That produces the `nsxiv` binary in the working directory. The first target in the Makefile is `all: nsxiv`, and the link step compiles the object list `autoreload.o commands.o image.o main.o options.o thumbs.o util.o window.o` against `-lImlib2 -lX11`.

Installation is the same system.

# make install
# make install-desktop
# make install-icon
# make install-all

`install-all` combines the other three, and all of them require root privileges. By default the prefix is `/usr/local`, so the executable lands at `/usr/local/bin/nsxiv`, the desktop entry at `/usr/local/share/applications/nsxiv.desktop` and the icon under `/usr/local/share/icons/hicolor/{size}/apps/nsxiv.png`. A different prefix is a variable on the make line.

$ make PREFIX="/your/dir" install

Example scripts are installed under `EGPREFIX`, which defaults to `/usr/local/share/doc/nsxiv/examples` and can be changed the same way.

The build-time settings live in `config.h`. If that file does not exist yet, the Makefile generates it by copying `config.def.h`, and the `make config.h` target does it explicitly. The README asks you to check and change it so the settings fit your needs, which is the point of the program.

What config.h and Xresources actually control

Customization is the heart of this kind of viewer, and nsxiv documents two routes. The primary one is setting values for the variables in `config.h`, which is compiled into the binary. The secondary one is Xresources, described in the manual, which allows changes without a rebuild for the options it covers.

The Makefile reveals one detail that matters: `config.h` is a dependency of every object file, so changing it triggers a full rebuild. The file itself is created from `config.def.h`, and the README tells you to edit it after generation rather than to rely on the defaults.

Beyond that, the README points to a guide in the nsxiv-extra repository for implementing features the program does not have. The reasoning is explicit: the project scope is limited, so custom work is hosted separately where users are free to submit patches and scripts rather than having them folded into mainline.

That split has a practical consequence. A feature you want may exist as a patch somewhere in the extra repository, which means you are applying and maintaining it yourself rather than receiving it through an update. The manual page is the reference for the runtime options, and it is available online, though the README warns that the online version might not accurately represent a local copy.

Features that live in separate scripts rather than the binary

The F.A.Q. section of the README answers four practical questions, and in every case the answer points at a script hosted in the nsxiv-extra repository rather than a built-in option.

Opening remote urls is handled by `nsxiv-url`. Opening all the images in a directory is `nsxiv-rifle`. Setting default arguments for the viewer is `nsxiv-env`, and piping images into the viewer is `nsxiv-pipe`.

These are the answer to a fair criticism of small viewers: they display images from the local filesystem and little else. The scripts extend that reach without adding dependencies to the C program, which keeps the binary small and the build simple. The cost is that each capability lives outside the main program and outside its release notes.

The README also links to a list of known issues on the issue tracker, which is worth reading before assuming a behaviour is a bug in your own setup.

Where nsxiv is the wrong choice

The clearest limitation is the X11 dependency. nsxiv needs X11 and an Imlib2 built with X11 support, so on a modern desktop that runs only Wayland, it either needs XWayland or it does not run at all. That is not a preference, it is a hard dependency listed in the README.

The second limitation is that Imlib2 must be version 1.11 or later. A system with an older Imlib2 in its repositories cannot use the program without upgrading a core image library, which on a long term distribution can be a large change.

The third is the fork relationship itself. A mostly drop-in replacement still is not identical to the original, and the repository ships a MIGRATION document in etc/MIGRATION.md specifically for people coming from sxiv. Any workflow that depends on exact sxiv behaviour, including scripts written against its output or its option names, needs checking.

The fourth is the absence of GitHub releases. The project metadata says the repository has no GitHub releases, and the README asks users to make sure they are on the latest release before filing a bug, without naming a release channel on GitHub. Tags exist on Codeberg, but the release process is not described in the README.

The last push was on 2026-09-15, so the project is being worked on, but a fork that promises to be a drop-in replacement has to keep that promise indefinitely, which is a long commitment for a volunteer project.

Comparing nsxiv with feh and qiv

feh is the closest competitor in spirit. It is also a small X11 image viewer written in C, it is scriptable, and it is popular as a scriptable thumbnailer and wallpaper setter. The difference in approach is that feh is built around a general command line interface, with an image mode, a thumbnail mode and a large set of flags for output and behaviour, so automation goes through feh's own options. nsxiv is built around the keyboard, with `key-handler` as the extension point and the whole customisation surface in `config.h`.

qiv is the other frequent comparison. It offers a similar thumbnailing approach and sits in the same lightweight C viewer category, and it can be used as a thumbnailer for desktops. The distinctions are again in the configuration model and the script ecosystem around it, which is where the two projects have grown apart over the years.

Against the larger desktops, both nsxiv and feh win on startup time and memory use and lose on everything a modern image application provides, including RAW development, colour management, side-by-side comparison and metadata editing.

For a migration decision, the practical comparison is between sxiv and nsxiv. Same interface, same config file approach, a maintained upstream in place of an abandoned one, plus thumbnails with caching and auto-reload. The extra repository is where the differences live.

Editorial conclusion

nsxiv fits an X11 user who wants one small image viewer, wants the sxiv key bindings, and is willing to spend an afternoon in config.h to get the colours and behaviour right. It is not a fit for a Wayland-only desktop, where the underlying X11 libraries may not be present at all, nor for anyone who wants remote and piped input without installing the separate nsxiv-extra scripts. Before switching from sxiv, read the MIGRATION document in etc/, since the fork keeps the interface deliberately but changes details that a long term sxiv user will notice.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. nsxiv/nsxiv on GitHub
4. Project website
5. README