qiv(1)

📦
version 3.0.4 · 5 versions
, in nixpkgs unstable, ubuntu stonking

💖 qiv — the fast gdk3/gdk2 image viewer for X 💖

okay bestie, so qiv is literally an image viewer built with gdk3/gdk2, and that's the whole reason it's faster than the old-school traditional image viewers like xv or xli. no cap. it just eats. 🔥

Version: 3.0.4, released on 2026-04-19 by Andy Spiegl — http://qiv.spiegl.de/ — qiv.andy@spiegl.de originally by Adam Kopacz / KLOGRAFX.DE Network — http://www.klografx.net/qiv/ — adam.k@klografx.de

✨ SYNOPSIS ✨

qiv [options] file ...

🦋 DESCRIPTION 🦋

qiv is an image viewer developed with gdk3/gdk2. bc of that, qiv is faster than those traditional image viewers such as xv or xli. it's giving main character energy tbh. 💅

🎀 OPTIONS 🎀

yes bestie there are a LOT of them. every single one is here. do not panic. we go through them one by one, periodt.

  • -h, --help — prints out a brief help message for you. 🫶
  • --display disp — opens the qiv window on display disp.
  • -F, --file file | stdin — reads file names from file or stdin, one name per line. you can specify this option multiple times to read from several files, and it will not affect other file names passed on the command line.
  • -u, --recursivedir — changes qiv's behaviour so it recursively descends into the directories given on the command line.
  • -L, --followlinks — with --recursivedir, this lets a symlink point to a directory. super useful for organizing photo dirs into categories, but it is up to you to ensure that there are no symlink loops that would cause an infinite scan. like, protect your machine bestie. 😭
  • -e, --center — disables window centering.
  • -w, --fixed_width x — window with fixed width x.
  • -W, --fixed_zoom x. — window with fixed zoom factor (percentage x).
  • --highDPIfactor FLOAT — resizes everything by this factor to compensate for high (or also low) DPI screens.
  • -x, --root file — sets file as the current desktop background (centered) and exits.
  • -y, --root_t file — sets file as the current desktop background (tiled) and exits.
  • -z, --root_s file — sets file as the current desktop background (stretched) and exits.
  • -m, --maxpect — expands image(s) to fit screen size while preserving aspect ratio.
  • -t, --scale_down — shrinks image(s) which are larger than screen size to fit.
  • -b, --brightness x — sets brightness to x (-50..50).
  • -c, --contrast x — sets contrast to x (-50..100).
  • -g, --gamma x — sets gamma to x (-50..100).
  • -n, --no_filter — disables filtering of images by extension. normally qiv will only load images with an image extension such as .jpg, .png, .gif ... but this option lets you load any file as an image. chaotic but iconic.
  • -i, --no_statusbar — disables statusbar.
  • -I, --statusbar — enables statusbar.
  • -J, --showJPEGcomments — enables display of JPEG comments.
  • -E, --showArtistName — enables display of artist (author) name (in JPEG images).
  • --artist_ignore STRING — does NOT show artist name if it is equal to this string.
  • -p, --transparency — enables transparency for transparent images.
  • -a, --do_grab — grabs the pointer in windowed mode.
  • -G, --disable_grab — disables grabbing the pointer/kbd in fullscreen mode. useful e.g. if qiv displays images on a display other than where it was invoked from. Use with caution!
  • -v, --version — prints version information.
  • -o, --bg_color x — sets root background color to named color x or 24 bit hex RGB triple in the format #RRGGBB.
  • -C, --cycle — changes cycle behaviour. qiv will exit after last picture has been shown.
  • -s, --slide — starts slideshow immediately. this can also be used for the desktop background (x/y/z).
  • -r, --random — randomizes slideshow.
  • -R, --readonly — disables the deletion feature.
  • -S, --shuffle — shuffles images (random order with next/previous functionality).
  • -d, --delay x — sets slideshow delay to x seconds.
  • -f, --fullscreen — uses fullscreen window on start-up.
  • -P, --ignore_path_sort — sorts all the image files by just their filename, ignoring the path.
  • -M, --merged_case_sort — sorts all the image files in merged-case order (AaBbCc...).
  • -K, --mtime_sort — sorts files by their modification time.
  • -N, --numeric_sort — a "smart" numeric sort that attempts to sort filenames with numbers in a logical manner. for instance: 2.jpg sorts before 10.jpg; 1foo.jpg through 10foo.jpg sorts after 1bar.jpg through 15bar.jpg (because "foo" comes after "bar"); and baz0001.jpg through baz0010.jpg sorts after baz01.jpg through baz99.jpg (because the longer group of zero-padded digits indicates that they shouldn't be intermingled). she's smart, she's organized, she ate. 👑
  • -D, --no_sort — does not apply any sorting to the list of files.
  • -T, --watch — reloads the image if it has changed on disk.
  • -A, --select_dir dir — stores the selected files in dir (default is .qiv-select).
  • -q, --rotate x — rotates each image 90 (x=1), 180 (x=2), 270 (x=3) degrees clockwise. if x=11 or x=13, the 90 or 270 degree rotation is conditional on the image fitting better if rotated. e.g. if the display is wide and a tall image is too tall to fit on the screen, it will be rotated.
  • -l, --autorotate — does NOT autorotate JPEGs according to EXIF rotation tag. default is ON.
  • -X, --xineramascreen x — uses monitor x as preferred screen.
  • -Y, --source_profile x — uses color profile file x as source profile for all images.
  • -Z, --display_profile x — uses color profile file x as display profile for all images.
  • -B, --browse — this option is useful when configuring qiv to be used with a file manager. qiv will scan the directory of the clicked image and allow you to scroll through those images.
  • --trashbin — uses user's trash bin instead of .qiv-trash. undeleting an image will not work, open the trash bin and restore the image instead.
  • --vikeys — enables movement with h/j/k/l, vi-style (HJKL will do what hjkl previously did).

🌸 EXAMPLES 🌸

run these bestie, they're cute:

qiv -atsd2 *.jpg
qiv --maxpect --root image.png
qiv --maxpect --slide --random --delay=2 *
qiv --maxpect --scale_down --slide --delay=2 `find / *`
qiv --bg_color 0000FF --root image.png
qiv --bg_color blue --root image.png

💅 KEYS 💅

okay so the keys are the whole personality of this app. memorize them, no cap.

space/left mouse/wheel right       next picture
backspace/right mouse/wheel left   previous picture
PgDn/wheel down                    5 pictures forward
PgUp/wheel up                      5 pictures backward
q/ESC/middle mouse                 exit
  • 0-9 — run qiv-command <key> <current-img>
  • ^...<return> — run qiv-command ^... <current-img> where ... can be any string
  • ?/F1 — show keys
  • F11/F12 — in/decrease slideshow delay (1 second)
  • a — copy picture to .qiv-select
  • A — artist (author) info on/off
  • d/D/del — move picture to .qiv-trash (-R disables this feature). (if started with --trashbin picture is moved to user's trash bin)
  • u — undelete the previously trashed image (not working if --trashbin is used)
  • +/=/mouse btn 9 — zoom in (+10% / +50% if above 100%)
  • -/mouse btn 8 — zoom out (10%)
  • e — center mode on/off
  • f — fullscreen mode on/off
  • m — scale to screen size on/off
  • t — scale down on/off
  • X — cycle through monitors
  • s — slide show on/off
  • p — transparency on/off
  • r — random order on/off
  • b — - brightness
  • B — + brightness
  • c — - contrast
  • C — + contrast
  • g — - gamma
  • G — + gamma
  • o — reset brightness, contrast, gamma
  • h — flip horizontally
  • v — flip vertically
  • k — rotate right
  • l — rotate left
  • jtx<return> — jump to image number x
  • jfx<return> — jump forward x images
  • jbx<return> — jump backward x images
  • enter/return — reset zoom, rotation and color settings
  • E — display Exif information
  • i — statusbar on/off
  • J — JPEG comments on/off
  • I — iconify window
  • w — watch file on/off
  • x — center image on background
  • y — tile image on background
  • z — stretch image on background
  • , — grab on/off
  • < — turn on/off magnifying window
  • arrow keys/wheel — move image (in fullscreen mode)
  • arrow keys/wheel+Shift — move image faster (in fullscreen mode)
  • NumPad-arrow keys+NumLock — move image faster (in fullscreen mode)

🖱️ MOUSE CONTROLS 🖱️

  • Button 1 — next picture
  • Button 1 (hold down) & Mouse-Move — moving picture
  • Button 2 — quit
  • Button 3 — previous picture
  • Wheel Up/Dn — move image vertically
  • Wheel Left/Right — move image horizontally
  • Extra mouse buttons (8,9) — zoom out/in (10%)

🗑️ DELETING 🗑️

okay so important: qiv doesn't actually delete files. it creates a directory named .qiv-trash and moves the images to that directory. qiv maintains the directory structure of your "deleted" images. you can also undelete the most recently trashed images in reverse order, which moves each file back into its original directory. there is a limit to how many deletions can be undone, but it should be pretty large (currently 1024 items). sometimes this feature might be unwanted. to prevent accidents you can specify the -R option to disable this feature. if the --trashbin option is used qiv will move the deleted pictures to the user's trash bin. in that case undeleting with pressing u will not work. open the trash bin and restore the image instead. 📌

lowkey the whole thing is reversible-ish but bestie, don't be reckless with your photos. 💀

🖲️ IMWHEEL SUPPORT 🖲️

with XFree86 3.3.2+ server, using the wheel is seen as button 4 and 5 pressed. you only have to use "IMPS/2" or "Intellimouse" for protocol and add "ZAxisMapping 4 5 " in the "Pointer" section of XF86Config.

if imwheel (a program used to emulate key pressed when wheel is used for program not supporting wheel), the following two lines must be add to imwheel config file:

"qiv"
@Exclude

✨ USER-DEFINED KEYBOARD ACTIONS ✨

okay bestie this is the part where qiv lets you drive 😌💅

The keys 0 through 9 will invoke qiv-command with the key you pressed as the first argument and the current image filename as the second argument. So yeah, you get ten whole custom slots and qiv will just hand it the key number and the file. iconic.

Real talk though: qiv-command is not distributed with qiv. it's not included, it's not bundled, it's to be supplied by the user. you have to write it yourself, bestie. the feature gets enabled by dropping a simple shell script in your command search path (for example, in the user's ~/bin directory) 🫶

and like, it could literally look something like this:

#!/bin/sh
# Argument sanity checking eliminated for brevity
case $1 in
  0|1|2|3|4|5|6|7|8|9) mkdir -f dir$1; mv "$fname" dir$1 ;;
  *) echo "unrecognized command"; exit ;;
esac
heads up: that "Argument sanity checking eliminated for brevity" comment is doing a LOT of heavy lifting in that script. it's the original's own little disclaimer, not mine 😭

now here's the ✨magic trick✨ — if the first line of the output looks like NEWNAME=xxxxxxx then qiv thinks that the filename of the currently displayed image has changed to this new name and updates its internal filelist. so if your qiv-command renames files, qiv keeps up with you instead of getting confused. it's giving main character energy, no cap 🔥

also please check out the example that came together with qiv, it's right there and it's helpful 🌸

👑 AUTHORS 👑

the absolute legends, the founding mothers and fathers of the vibe, the whole squad that made this happen — every single one of them, in order, no skips:

  • Adam Kopacz <adam.k@klografx.de>
  • Andy Spiegl <qiv.andy@spiegl.de>
  • Darren Smith <darren.smith@juno.com>
  • Pavel Andreev <paxvel@vumsoft.cz>
  • Decklin Foster <decklin@red-bean.com>
  • Holger Mueller <hmueller@hrzpub.tu-darmstadt.de>
  • Scott Sams <sbsams@eos.ncsu.edu>
  • Serge Winitzki <winitzki@geocities.com>
  • Frederic Crozat <fcrozat@mail.dotcom.fr>
  • Rutger Nijlunsing <rutger@wingding.demon.nl>
  • John Knottenbelt <jak97@doc.ic.ac.uk>
  • Danny <dannys@mail.com>
  • Tomas Ogren <stric@ing.umu.se>
  • Erik Jacobsen <erik@openix.com>
  • Alfred Weyers <alfred@otto.gia.RWTH-Aachen.DE>
  • Daniel <danad157@student.liu.se>
  • Henning Kulander <hennikul@ifi.uio.no>
  • Ask Bjoern Hansen <ask@valueclick.com>
  • Adrian Lopez <adrian2@caribe.net>
  • Y Furuhashi <y_furuhashi@ot.olympus.co.jp>
  • Wayne Davison <wayned@users.sourceforge.net>
  • Johannes Stezenbach <js@convergence.de>
  • OEyvind Kolaas <pippin@users.sourceforge.net>
  • Matthieu Castet <castet.matthieu@free.fr>
  • Geoffrey T. Dairik <dairiki@dairiki.org>
  • Leopoldo Cerbaro <redbliss@aliceposta.it>
  • Heikki Lehvaslaiho <heikki@sanbi.ac.za>
  • Larry Doolittle <ldoolitt@boa.org>
  • S. Dobrev <sdobrev@sistechnology.com>
  • Thomas Wiegner <wiegner@gmx.de>
  • Barry deFreese <bdefreese@debian.org>
  • Peter deWachter <pdewacht@gmail.com>
  • Akos Pasztory <akos.pasztory@gmail.com>

thirty-two whole humans. a whole community. we love to see it 💖

🌈 MISC 🌈

the random-but-important section, aka the vibes checklist:

  • qiv homepage: http://qiv.spiegl.de/
  • homepage of original author Adam Kopacz <adam.k@klografx.de> — http://www.klografx.net/qiv/
  • Mail bug, reports and comments to Andy Spiegl <qiv.andy@spiegl.de> 📬
  • Sending a SIGUSR1 to qiv will cause the program to flip to next picture. SIGUSR2 will move to previous. so you can yeet signals at it from the outside and it'll still land on beat 😌
  • This program is covered by the GNU GPL; see the file COPYING for details 📄
fr fr, that GPL line is load-bearing — go read your COPYING file, bestie.

and that's a wrap on qiv(1), the fast image viewer for X, section 1, name qiv — that little footer line at the bottom of the page, the one that says qiv in the middle and qiv(1) on the right? that's it, that's the source and version and the date stamp of this whole masterpiece, and honestly it ate. slay, go look at some pictures 💅🦋👑

📦 where this page comes from