Neo Simple X Image Viewer
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
NRK c03ec39437
ci/woodpecker/push/spell Pipeline was successful Details
ci/woodpecker/push/build Pipeline was successful Details
ci/woodpecker/push/analysis Pipeline was successful Details
update documentation (#448)
the fedora copr repo is no longer being updated since the maintainer of
it, mamg22, no longer uses nsxiv in his daily setup (and thus stopped
contributing to nsxiv as well).

he has requested the repo and his email to be removed from the project.
so go ahead and honor that request.

also take this as an opportunity to remove some long inactive
maintainers from the CURRENT MAINTAINERS section of the manpage.

Reviewed-on: #448
Reviewed-by: explosion-mental <>
1 week ago
.github/workflows [ci]: fix things (#400) 5 months ago
etc update documentation (#448) 1 week ago
icon Embed new nsxiv icon (#163) 2 years ago
.editorconfig editorconfig: only apply to .c and .h files (#433) 2 months ago
.gitignore Embed new nsxiv icon (#163) 2 years ago
LICENSE Added LICENSE 13 years ago
Makefile add support for long-opts (#332) 10 months ago update documentation (#448) 1 week ago
autoreload.c apply clang-format 3 months ago
commands.c add a pick quit keybind (#432) 2 months ago
commands.h add a pick quit keybind (#432) 2 months ago
config.def.h add a pick quit keybind (#432) 2 months ago make assertions opt-in (#447) 1 week ago
image.c set a default delay if delay is 0 (#445) 2 weeks ago
main.c move load/cache messages to right side (#446) 2 weeks ago
nsxiv.h make assertions opt-in (#447) 1 week ago
options.c apply clang-format 3 months ago
optparse.h add support for long-opts (#332) 10 months ago
thumbs.c apply clang-format 3 months ago
utf8.h code-style: general cleanups (#137) 2 years ago
util.c apply clang-format 3 months ago
window.c fix: memory leak in `win_draw_bar` (#444) 2 weeks ago


CodeBerg tags license loc

Neo (or New or Not) Simple (or Small or Suckless) X Image Viewer

nsxiv is a fork of the now-unmaintained sxiv with the purpose of being a (mostly) drop-in replacement for sxiv, maintaining its interface and adding simple, sensible features. nsxiv is free software licensed under GPLv2 and aims to be easy to modify and customize.

Please file a bug report if something does not work as documented or expected on Codeberg after making sure you are using the latest release. Contributions are welcome, see CONTRIBUTING to get started.


  • Basic image operations like zooming, panning, rotating
  • Basic support for animated/multi-frame images
  • Thumbnail mode: grid of selectable previews of all images
  • Ability to cache thumbnails for fast re-loading
  • Automatically refreshing modified images
  • Customizable keyboard and mouse mappings via config.h
  • Scriptability via key-handler
  • Displaying image information in status bar via image-info & thumb-info
  • Customizable window title via win-title


Image mode with default colors:


Thumbnail mode with custom colors:


Installing via package manager

nsxiv is available on the following distributions/repositories. If you don't see your distro listed here, either contact your distro's package maintainer or consider packaging it yourself and adding it to the respective community repo.


nsxiv requires the following software to be installed:

  • Imlib2
  • X11

The following dependencies are optional.

  • inotify*: Used for auto-reloading images on change. Disabled via HAVE_INOTIFY=0.
  • libXft, freetype2, fontconfig: Used for the status bar. Disabled via HAVE_LIBFONTS=0.
  • libexif: Used for auto-orientation and exif thumbnails. Disable via HAVE_LIBEXIF=0.

The following dependencies are only used if your imlib2 version is lower than v1.8.0. If your imlib2 version is v1.8.0 (or above) then the following dependencies are unused and won't be built (even if you enable it explicitly).

  • giflib: Used for animated gif playback. Disabled via HAVE_LIBGIF=0.
  • libwebp: Used for animated webp playback. (NOTE: animated webp also requires Imlib2 v1.7.5 or above) Disabled via HAVE_LIBWEBP=0.

Please make sure to install the corresponding development packages in case that you want to build nsxiv on a distribution with separate runtime and development packages (e.g. *-dev on Debian).

* inotify is a Linux-specific API for monitoring filesystem changes. It's not natively available on *BSD systems but can be enabed via installing and linking against libinotify-kqueue.


nsxiv is built using the commands:

$ make

You can pass HAVE_X=0 to make to disable an optional dependency. For example:


will disable libexif support. Alternatively they can be disabled via editing OPT_DEP_DEFAULT=0 can be used to disable all optional dependencies.

Installing nsxiv:

# make install

Installing desktop entry:

# make install-desktop

Installing icons:

# make install-icon

Installing all of the above:

# make install-all

Please note, that these requires root privileges. By default, nsxiv is installed using the prefix /usr/local, so the full path of the executable will be /usr/local/bin/nsxiv, the .desktop entry will be /usr/local/share/applications/nsxiv.desktop and the icon path will be /usr/local/share/icons/hicolor/{size}/apps/nsxiv.png.

You can install nsxiv into a directory of your choice by changing this command to:

$ make PREFIX="/your/dir" install

Example scripts are installed using EGPREFIX which defaults to /usr/local/share/doc/nsxiv/examples. You can change EGPREFIX the same way you can change PREFIX shown above.

The build-time specific settings of nsxiv can be found in the file config.h. Please check and change them, so that they fit your needs. If the file config.h does not already exist, then you have to create it with the following command:

$ make config.h


Refer to the man-page for the documentation:

$ man nsxiv

You may also view the man-page online. However, note that the online man-page might not accurately represent your local copy.


  • Can I open remote urls with nsxiv?
    Yes, see nsxiv-url

  • Can I open all the images in a directory?
    Yes, see nsxiv-rifle

  • Can I set default arguments for nsxiv?
    Yes, see nsxiv-env

  • Can I pipe images into nsxiv?
    Yes, see nsxiv-pipe

You may also wish to see the known issues.


The main method of customizing nsxiv is by setting values for the variables in config.h, or by using Xresources as explained in the manual. If these options are not sufficient, you may implement your own features by following this guide.

Due to our limited project scope, certain features or customization cannot be merged into nsxiv mainline. Following the spirit of suckless software, we host the nsxiv-extra repo where users are free to submit whatever patches or scripts they wish.

If you think your custom features can be beneficial for the general user base and is within our project scope, please submit it as a pull request on this repository, then we may merge it to mainline.

Description on how to use or submit patches can be found on nsxiv-extra's README.


You can browse the source code repository on CodeBerg or get a copy using git with the following command:

$ git clone

You can view the changelog here

Similar projects

If nsxiv isn't able to fit your needs, check out the image viewer section of suckless rocks to find other minimal image viewers to try out.

Below are a couple other lesser known projects not listed in suckless rocks.

  • MAGE: A smaller/more-suckless version of sxiv.
  • div: Minimal and extensive, aimed at C devs willing to build their own features.
  • mpv-image-viewer: Lua script to turn mpv into an image viewer. Supports thumbnails via mpv-gallery-view.