pqiv(1)

📦
version 2.13.3 · 4 versions
, in arch rolling, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 pqiv(1) 💖

✨ NAME ✨

pqiv — powerful quick image viewer 👑

🌈 SYNOPSIS 🌈

pqiv [options] [filename(s)...]

🦋 DESCRIPTION 🦋

Okay bestie, so pqiv is a simple command line image viewer that got its whole vibe from qiv. It's highly customizable and it supports a whole variety of formats. It's giving "I just want to look at my pictures" but make it ✨iconic✨.

💅 OPTIONS 💅

  • -c, --transparent-background — Draws pqiv's window borderless and transparent. When you're in window mode, a mouse click is what activates and deactivates the window decorations. Fancy, lowkey.
  • -d, --slideshow-interval=SECONDS — In slideshow mode (which you get to by --slideshow or by hitting key s by default), it cycles through your images at this rate. Floating point values are supported, so like, use 0.5 and you're moving through images at a rate of two images per second. Speedy girlie 🏃♀️
  • -f, --fullscreen — Starts in fullscreen mode. You can toggle fullscreen at runtime by pressing f by default. Main character energy, obviously.
  • -F, --fade — Fades between images. See also --fade-duration for the whole ✨aesthetic✨.
  • -i, --hide-info-box — Initially hides the info box. Whether the box is visible can be toggled by pressing i at runtime by default.
  • --font=FONT — Specify the Pango font string for the info box. Heads up: the font size will be scaled to the window. Not me getting resized 💀
  • -l, --lazy-load — Normally pqiv processes all command line arguments before displaying its main window. With this option, the window is shown as soon as the first image has been found and loaded. Impatient? Valid. 🫶
  • -n, --sort — Instead of storing images in the order they're given on the command line and found within directories, it sorts them. The default order is by name (natural order). See --sort-key to change the order.
  • -P, --window-position=POSITION — Sets the initial window position. POSITION may either be
    • x,y — screen coordinates, or
    • off — to not position the window at all.
  • -r, --additional-from-stdin — Reads additional filenames/folders from the standard input. ⚠️ This option conflicts with --actions-from-stdin.
  • -s, --slideshow — Starts in slideshow mode. Slideshow mode can be toggled at runtime by pressing s by default. Set it and forget it, bestie.
  • -t, --scale-images-up — Scales images up to fill the whole screen. This can be toggled at runtime by pressing t by default. See also --disable-scaling.
  • -T, --window-title=TITLE — Sets the title of the window. pqiv substitutes several variables into TITLE:
    • $BASEFILENAME — The base file name of the current file (e.g. image.png),
    • $FILENAME — The file name of the current file (e.g. /home/user/image.png),
    • $WIDTH — The width of the current image in pixels,
    • $HEIGHT — The height of the current image in pixels,
    • $ZOOM — The current zoom level,
    • $IMAGE_NUMBER — The index of the current image,
    • $IMAGE_COUNT — The total number of images.

The default is pqiv: $FILENAME ($WIDTHx$HEIGHT) $ZOOM% [$IMAGE_NUMBER/$IMAGE_COUNT].

  • -z, --zoom-level=FLOAT — Sets the initial zoom level as a floating point value, i.e., 1.0 is 100%. This only applies to the first image — other images are scaled according to the scale mode (see --scale-images-up and --disable-scaling) and the window size.
  • -1, --command-1=COMMAND — Binds the external COMMAND to key 1. You can use 2..9 to bind further commands. The ACTIONS feature (see below) allows one to bind further keys to other commands. COMMAND is executed using the default shell processor. $1 is substituted with the current file name. Unless COMMAND begins with | or -, if $1 is not present, the file name is appended to the command line.

If COMMAND begins with >, its standard output is displayed in a popup window.

If COMMAND begins with |, the current image is piped to its standard input, and its standard output is loaded as an image. This can be used to e.g. process images.

If COMMAND begins with -, a list of currently marked images is piped to its standard input.

  • --action=ACTION — Executes a specific ACTION when starting pqiv. The syntax is
command(parameter); command(parameter);

See the ACTIONS section below for available commands.

  • --actions-from-stdin — Like --action, but reads actions from the standard input. See the ACTIONS section below for syntax and available commands. ⚠️ This option conflicts with --additional-from-stdin.
  • --allow-empty-window — pqiv normally does not display the main window until one image has been found, and it quits when it cannot load any of the images anymore. With this option, both of those situations result in an empty pqiv window being shown. Empty but present, we love a stable queen 💅
  • --auto-montage-mode — Automatically enters montage mode if pqiv is started with more than one image.
  • --background-pattern=PATTERN — pqiv draws a checkerboard as transparent images' background. Use this option to alternatively use a white or black background. Valid values are checkerboard, white and black.
  • --bind-key=KEY BINDING — Rebinds a key to an action. The syntax is
key sequence { command(parameter); command(parameter); }

A key sequence may be one or more characters, or special characters supplied as <name>, where name is a GDK key specifier or a mouse button (Mouse-1) or a scrolling direction (Mouse-Scroll-1). If you e.g. use a<Control>b, then a user must hit a followed by control + b to trigger the command. It is possible to bind a and ab as well. The action bound to a will then be slightly delayed to allow a user to hit b. The semicolon separating commands is optional. See ACTIONS below for available commands.

If you need to know the name of a key specifier, you can run xev and press the desired key. The name of the keysym will be printed in parentheses, preceded by keysym and a hexadecimal representation. An alternative is to run xmodmap -pk. The command outputs the symbolic names in parentheses. Or use the list at https://git.gnome.org/browse/gtk+/plain/gdk/gdkkeysyms.h.

pqiv groups key bindings into different contexts. Currently, montage mode is the only context other than the default one: in montage mode, different key bindings are used. To switch the context while binding key sequences, write

@MONTAGE { ... }

and insert the special key bindings within the curly braces.

  • --box-colors=FOREGROUND COLOR:BACKGROUND COLOR — Customize the colors used to draw the info box and montage mode borders. Colors can be specified either as a comma separated list of RBG-values in the range from 0 to 255 or as a hexvalue, e.g., #aabbcc. The default value is #000000:#ffff00.
  • --browse — For each command line argument, additionally loads all images from the image's directory. pqiv will still start at the image that was given as the first parameter.
  • --disable-backends=LIST OF BACKENDS — Use this option to selectively disable some of pqiv's backends. You can supply a comma separated list of backends here. Non-available backends are silently ignored. Disabling backends you don't want will speed up recursive loading significantly, especially if you disable the archive backend. Available backends are:
    • archive — generic archive file support
    • archive_cbx — *.cb? comic book archive support
    • libav — video support, works with ffmpeg as well
    • gdkpixbuf — images
    • poppler — PDF
    • spectre — PS/EPS
    • wand — ImageMagick, various formats, e.g. PSD
    • webp — WebP format
  • --disable-scaling — Completely disables scaling. This can be toggled at runtime by pressing t by default. See also --scale-images-up.
  • --end-of-files-action=ACTION — If all files have been viewed and the next image is to be viewed — either by the user's request or because a slideshow is active — pqiv by default cycles and restarts at the first image. This parameter can be used to modify this behaviour. Valid choices for ACTION are:
    • quit — Quit pqiv,
    • wait — Wait until a new image becomes available. This only makes sense if used with e.g. --watch-directories,
    • wrap (default) — Restart at the first image. In shuffle mode, choose a new random order,
    • wrap-no-reshuffle — As wrap, but do not reshuffle in random mode.
  • --enforce-window-aspect-ratio — Tells the window manager to enforce the aspect ratio of the window. If this flag is set, then a compliant window manager will not allow users to resize pqiv's window to a different aspect ratio. This used to be the default behaviour, but window managers tend to have bugs in the code handling forced aspect ratios 😭. If the flag is not set and the aspect ratios of the window and image do not match, then the image will be still be drawn with the correct aspect ratio, with black borders added at the sides.
  • --fade-duration=SECONDS — With --fade, makes each fade this long. Floating point values are accepted, e.g. 0.5 makes each fade take half a second. Soft launch ✨
  • --low-memory — Tries to keep memory usage to a minimum. pqiv by default e.g. preloads the next and previous image to speed up navigation and caches scaled images to speed up redraws. This flag disables such optimizations.
  • --max-depth=LEVELS — For parameters that are directories, pqiv searches recursively for images. Use this parameter to limit the depth at which pqiv searches. A level of 0 disables recursion completely, i.e. if you call pqiv with a directory as a parameter, it will not search it at all.
  • --negate — Displays negatives of images. You can toggle this feature at runtime by pressing n. Inverted girlie era 🌈
  • --shuffle — bestie, this is the chaos mode 💅 it shows your files in a random order. Lowkey important: it conflicts with --sort, so pick one, you can't have both. Once every image has been shown, the files get reshuffled again — but within one single cycle the order stays stable, so it's not reshuffling mid-vibe. You can turn that reshuffling off with --end-of-files-action if you want. And at runtime you can hit Control + R (that's the default binding) to toggle shuffle mode on and off, and here's the cute part: it retains the shuffled order, meaning you can turn shuffle off, look at a few images, turn it back on, and it picks up right after the last image you saw in shuffle mode. obsessed actually ✨
  • --show-bindings — prints out all the keyboard and mouse bindings and then exits. It shows them in the exact format that --bind-key accepts, so it's giving you copy-paste-able receipts. Check out --bind-key and the ACTIONS section for what all those actions actually do. 🎀
  • --sort-key=PROPERTY — tells pqiv which key to sort by. The supported values for PROPERTY are:
    • name — sorts by filename in natural order, so like abc32d comes before abc112d, but b1 comes after both of them. iykyk, it's not just plain alphabetical 💀
    • mtime — sorts by file modification date. ⏰
  • --thumbnail-size=WIDTHxHEIGHT — resizes your thumbnails in montage mode. The default is 128x128. 🌸
  • --thumbnail-preload=COUNT — preloads COUNT thumbnails that sit adjacent to the current image, while you're displaying images or while they're selected in montage mode. Great for making montage mode snappier, but heads up: it will lead to high CPU loads. speed vs. your fan spinning, your choice bestie 😭
  • --thumbnail-persistence=DIRECTORY/STATUS — saves (persists) thumbnails to disk so you don't have to regenerate them every single time. The easiest way to use it is just passing a value of yes. Thumbnails then get stored according to the Thumbnail Managing Standard, inside $XDG_CACHE_HOME/thumbnails/*. The standard only allows storing thumbnails in the sizes 128x128, 256x256, 512x512 and 1024x1024 — exclusively — and it does not say how to store thumbnails for files inside archives or multi-page documents. Any thumbnails that break those rules get stashed in a special x-pqiv subfolder instead. Pass standard if you want to store only standard-compliant thumbnails. If you don't use this option at all, then thumbnails won't be loaded from the cache either — every thumbnail gets regenerated each time you use montage mode. 😮‍💨 A value of read-only lets you load thumbnails but never store them, and read-only is the default. If you pass local, pqiv stores thumbnails in a subfolder called .sh_thumbnails, relative to the images, as specified by the Thumbnail Managing Standard. Your third option is to hand it the name of a directory, and pqiv will use that directory to store thumbnails in. > The folder must be given as an absolute path — relative paths do not work. Also note that any folder not named .sh_thumbnails will be considered in --watch-directories. And one more thing: even while pqiv stores thumbnails to another folder, it will still try to load them from the standard folders as well. 🫶
  • --recreate-window — a workaround for window managers that just don't handle resize requests correctly 🙈 Instead of resizing, pqiv recreates the window every time the image changes. Note it does not redraw images when only the zoom changes.
  • --scale-mode-screen-fraction=FRACTION — controls how much screen space pqiv uses when it auto-scales images outside of fullscreen mode. Defaults to 0.8 (that's 80%). ✨
  • --wait-for-images-to-appear — if no images are found in the directories you gave on the command line, instead of just exiting, pqiv waits for some to show up. This option only works in conjunction with --lazy-load and --watch-directories, so don't expect it to do anything solo. ⭐
  • --watch-directories — makes pqiv watch every directory you passed as a parameter for new files, adding them as they appear. In --sort mode, files get sorted into the correct position; otherwise they're just appended to the end of the list. See also --watch-files, which handles what happens when the image you're currently viewing changes. 👑
  • --watch-files=VALUE — watches files for changes on disk. Valid choices for VALUE are:
    • on (default) — watches files for changes, reloads upon a change, and skips to the next file if a file is removed.
    • changes-only — watches files for changes and reloads upon a change, but does nothing if a file is removed.
    • off — does not watch files for changes at all. 💀
Note that a file that has been removed will still be removed from pqiv's image list when it has been unloaded, i.e. if a user moves more than one image away from it. (See also --low-memory.)

✨ ACTIONS ✨

okay bestie, so actions are literally the building blocks for controlling pqiv 🎀. The syntax for entering an action is:

COMMAND(PARAMETER)

where COMMAND is one of the commands described below and PARAMETER is the command's parameter. Strings are not quoted. Instead, the closing parenthesis must be escaped by a backslash if it is used in a string. E.g., command(echo \)) will output a single ). The available commands are:

  • add_file(STRING) — Add a file or directory. 🗂️
  • animation_step(INT) — Stop an animation, and advance by the given number of frames plus one. ⏩
  • animation_continue() — Continue a stopped animation. ▶️
  • animation_set_speed_relative(DOUBLE) — Scale the animation's display speed. 🌀
  • animation_set_speed_absolute(DOUBLE) — Set the animation's display speed scale level to an absolute value. 1.0 is the animation's natural speed. 🏃‍♀️
  • bind_key(STRING) — Override a key binding. Remember to quote closing parenthesis inside the new definition by prepending a backslash. Useful in conjunction with send_keys(STRING) to set up cyclic bindings. 🔗
  • clear_marks() — Clear all marks. 🧹
  • command(STRING) — Execute the given shell command. The syntax of the argument is the same as for the --command-1 option. 💻
  • flip_horizontally() — Flip the current image horizontally. ↔️
  • flip_vertically() — Flip the current image vertically. ↕️
  • goto_directory_relative(INT) — Jump to the n'th next or previous directory. 📁
  • goto_earlier_file() — Return to the image that was opened before the current one. ⏪
  • goto_file_byindex(INT) — Jump to a file given by its number. 🔢
  • goto_file_byname(STRING) — Jump to a file given by its displayed name. 🏷️
  • goto_file_relative(INT) — Jump to the n'th next or previous file. ⏭️
  • goto_logical_directory_relative(INT) — Jump to the n'th next or previous logical directory. Any multi-page documents, such as PDFs or archive files, are regarded as logical directories. Directories within archive files, recognizable by a slash in the archive member's file name, are regarded as directories too. Basically, the rule is that two images are in the same logical directory if no character following the common prefix of their file names in either name is a slash or a hash symbol. 🧠
  • hardlink_current_image() — Hardlink the current image to ./.pqiv-select/, or copy it if hardlinking is not possible. 🔗
  • jump_dialog() — Display the jump dialog. 🪟
  • montage_mode_enter() — Enter montage mode, a view for interactive selection of images. 🖼️
  • montage_mode_follow(KEYS) — Set up "follow" mode: Bind a sequence composed of the keys in KEYS to each visible thumbnail, such that typing that sequence moves the cursor to said position. At the same time, turn on binding overlays, increase the keyboard timeout, and revert everything after an image has been selected. 👀
  • montage_mode_return_proceed() — Leave montage mode, and goto the currently selected image. ✅
  • montage_mode_return_cancel() — Leave montage mode, and return to the last image viewed before entering montage mode. ↩️
  • montage_mode_set_shift_x(INT) — Set the horizontal cursor position in montage mode to an absolute value, indexed from 0. ➡️
  • montage_mode_set_shift_y(INT) — Set the vertical cursor position in montage mode to an absolute value, indexed from 0. ⬇️
  • montage_mode_set_wrap_mode(INT) — Adjust how wrapping around edges works when shifting the cursor position in montage mode: The default, 1, is to wrap around rows but not around the whole image list. Set this to 0 to disable wrapping entirely. A value of 2 enables full wrapping. 🔄
  • montage_mode_shift_x(INT) — Shift the cursor in montage mode in horizontal direction. Shifts wrap around edges to the adjacent vertical lines, but not around the end of the list back to its beginning. ➡️
  • montage_mode_shift_y(INT) — Shift the cursor in montage mode in vertical direction. ⬇️
  • montage_mode_show_binding_overlays(INT) — Disable (by using a parameter value of 0) or enable (by using any other value) follow mode. In follow mode, pqiv will draw mnemonics on top of each thumbnail that is reachable by typing a key (combination). Use this to realize keyboard navigation similar to vimperator/pentadactyl/vimium/etc. ⌨️
  • montage_mode_shift_y_pg(INT) — Shift the cursor in montage mode in vertical direction by n pages. 📄
  • move_window(INT, INT) — Move pqiv's window to the specified coordinates. Negative values center the window on the current monitor. 🪟
  • nop() — Do nothing. Can be used to clear an existing binding. 🚫
  • numeric_command(INT) — Execute the n'th command defined via --command-1 etc. 🔢
  • output_file_list() — Output a list of all loaded files to the standard output. 📃
  • quit() — Quit pqiv. 👋
  • reload() — Reload the current image from disk. 🔄
  • remove_file_byindex(INT) — Remove a file given by its number. 🗑️
  • remove_file_byname(STRING) — Remove a file given by its displayed name. 🗑️
  • reset_scale_level() — Reset the scale level to the default value. 🔍
  • rotate_left() — Rotate the current image left by 90°. ↺
  • rotate_right() — Rotate the current image right by 90°. ↻
  • send_keys(STRING) — Emulate pressing a sequence of keys. This action currently does not support special keys that do not have an ASCII representation. Useful in conjunction with bind_key(STRING) to set up cyclic key bindings. ⌨️
  • set_cursor_visibility(INT) — Set the visibility of the cursor; 0 disables, other values enable visibility. 👆
  • set_cursor_auto_hide(INT) — Automatically show the cursor when the pointer moves, and hide it after one second of inactivity. Set to 0 to disable this feature or any other value to enable it. Note that this enables pointer movement events, which might slow down pqiv if it is used over slow network links. 🖱️
  • set_fade_duration(DOUBLE) — Set the duration of fades between images. In contrast to the command line option, this action also implicitly enables fading. Set the duration to zero to disable the feature. 🌫️
  • set_interpolation_quality(INT) — Set the interpolation quality for resized images. Options are: 0 to cycle between the different modes, 1 for an automated choice based on the image size (small images use nearest interpolation, large ones Cairo's good mode), 2 for fast, 3 for good and 4 for best. 🎨
  • set_keyboard_timeout(DOUBLE) — Set the timeout for key sequence input. For example, if you bind something to a and another action to ab, pqiv will give you by default half a second to enter the b before assuming that you intended to type only a. Use this action to change this value. ⏱️
  • set_scale_level_absolute(DOUBLE) — Set the scale level to the parameter value. 1.0 is 100%. See also --zoom-level. 🔍
  • set_scale_level_relative(DOUBLE) — Adjust the scale level multiplicatively by the parameter value. 🔍
  • set_scale_mode_fit_px(INT, INT) — Always adjust the scale level such that each image fits the given dimensions. 📐
  • set_scale_mode_screen_fraction(DOUBLE) — Adjust how much of the available screen space is used for scaling the window outside fullscreen mode. Defaults to 0.8. This also affects the size of the montage mode window. 🖥️
  • set_shift_align_corner(STRING) — Align the image to the window/screen border. Possible parameter values are the cardinal directions, e.g. NE will align the image to the north east, i.e. top right, corner. You can prepend the parameter by an additional C to perform the adjustment only if the image dimensions exceed the available space, and to center the image elsewise. 📍
  • set_shift_x(INT) — Set the shift in horizontal direction to a fixed value. ↔️
  • set_shift_y(INT) — Set the shift in vertical direction to a fixed value. ↕️
  • set_slideshow_interval_absolute(DOUBLE) — Set the slideshow interval to the parameter value, in seconds. ⏲️
  • set_slideshow_interval_relative(DOUBLE) — Adjust the slideshow interval additively by the parameter value. See also --slideshow-interval. ⏲️
  • set_status_output(INT) — Set this to non-zero to make pqiv print status information for scripts to stdout, once upon activation and then whenever the user moves between images. The format is compatible with shell variable definitions. Variables currently implemented are CURRENT_FILE_NAME and CURRENT_FILE_INDEX. An output sweep always ends with an empty line. 📤
  • set_thumbnail_preload(INT) — Change the amount of thumbnails to be preloaded. A value of zero disables the feature. 🖼️
  • set_thumbnail_size(INT,INT) — Change the size of thumbnails. The order of the arguments is width, then height. Thumbnails are always scaled such that no side is larger than this limit. 📏
  • shift_x(INT) — Shift the current image in x direction. ↔️
  • shift_y(INT) — Shift the current image in y direction. ↕️
  • toggle_background_pattern(INT) — Toggle between the different background patterns: 0 to toggle, 1 for checkerboard pattern, 2 for black, 3 for white. 🏁
  • toggle_fullscreen(INT) — Toggle fullscreen mode: 0 to toggle, 1 to go to fullscreen, 2 to return to window mode. 🖥️
  • toggle_info_box() — Toggle the visibility of the info box. ℹ️
  • toggle_mark() — Toggle the current image's mark. ⭐
  • toggle_negate_mode(INT) — Toggle negate (color inversion) mode: 0 to toggle, 1 to enable, 2 to disable. 🌗
  • toggle_scale_mode(INT) — Change the scale mode: Use 1 to disable scaling, 2 for automated scaledown (default), 3 to always scale images up, 4 to maintain the user-set zoom level, and 5 to maintain the window's size. 0 cycles through modes 1-3. 🔍
  • toggle_shuffle_mode(INT) — Toggle shuffle mode. Use 0 to cycle through the possible values, 1 to enable shuffle, and any other value to disable it. 🔀
  • toggle_slideshow() — Toggle slideshow mode. 🎞️

⌨️ DEFAULT KEY BINDINGS ⌨️

Okay bestie, these are the keys that just work the second you open pqiv. No setup, no config, just vibes 💅

  • Backspace/Space — previous/next file. The classic. The moment.
  • ctrl-a — links the current image into ./.pqiv-select/, or copies it if hardlinking isn't possible. (It tries the link first, bestie, it's efficient like that ✨)
  • f — toggle fullscreen mode. Main character energy, activate.
  • h/v — flip the image horizontally or vertically. Mirror mirror 🪞
  • k/l — rotate the image right or left.
  • i — toggle visibility of the info box.
  • j — pops up a dialog with a list of all your files for quick selection. No scrolling in the file manager, we're doing it in pqiv 💖
  • m — toggle montage mode, which is an interactive image selection mode. Use the cursor keys or your mouse to select an image, and Return to go back to single image view. Hit g to quickly navigate to a thumbnail. It's giving contact sheet 🌈
  • o — toggle a mark on an image. Use ctrl-R to reset all marks. This one's used together with commands starting with a -.
  • q — quit pqiv. Bye bestie 😭
  • r — reload the current image.
  • s — toggle slideshow mode.
  • t — toggle the scale mode; it cycles between scaling all images up, scaling large images down, and no scaling at all.
  • ctrl-t — maintain the user-set scale level.
  • mod-t — maintain the window's size.
  • Plus/Minus — zoom. In and out, in and out 🔍
  • Period, ctrl-Period — stop, single-step and continue animated images.
  • mod-Plus, mod-Minus — alter animation speed.
  • ctrl-r — toggle shuffle mode. Chaos, but make it aesthetic 🎀
  • ctrl-p — go to the image you were viewing before the current one. The way that history works 🫶
  • ctrl-Space, ctrl-Backspace — go to the next/previous logical directory.
  • ctrl-Plus, ctrl-Minus — alter the slideshow interval.
  • b — toggle the background pattern for transparent images.
  • n — toggle negate ("negative") mode.
  • Mouse buttons (fullscreen) — goto the next and previous files.
  • Mouse drag (fullscreen) — move the image.
  • Mouse drag with right button (fullscreen) — zoom.
  • Arrow keys — move the image.
Heads up: this list omitted some advanced default bindings, no cap. The descriptions of the actions above are annotated with those bindings, so go look there. You can also run pqiv --show-bindings to display a complete list, and honestly? Iconic behaviour.

⚙️ CONFIGURATION FILE ⚙️

Upon startup, pqiv parses the file ~/.config/pqivrc. It should be an INI-style key/value file with an options section. All long form parameters are valid keys. To set a boolean flag, set the value to 1. A set flag inverts the meaning of the associated parameter — so like, if you set fullscreen=1, then pqiv will start in fullscreen mode unless you supply -f upon startup. Sneaky, right? 🐍

As an example,

[options]
fullscreen=1
sort=1
command-1=|convert - -blur 20 -

will make pqiv start in fullscreen by default, sort the file list and bind a blur filter to key 1. The -f flag on the command line will make pqiv not start in fullscreen, and -n will make it not sort the list. Flip the flip, bestie ✨

You can place key bindings in the format of the --bind-key parameter in a special [keybindings] section. E.g.,

[keybindings]
q { goto_file_relative(-1); }
w { goto_file_relative(1); }

x { send_keys(#1); }
<numbersign>1 { set_scale_level_absolute(1.); bind_key(x { send_keys(#2\); }); }
<numbersign>2 { set_scale_level_absolute(.5); bind_key(x { send_keys(#3\); }); }
<numbersign>3 { set_scale_level_absolute(0.25); bind_key(x { send_keys(#1\); }); }

will remap q and w to move between images, and set up x to cycle through 100%, 50% and 25% zoom levels. Look at her go 💅

Similarly, you can also specify (multiple) actions to be executed each time pqiv is started, in a section called [actions].

For backwards compatibility with old versions of pqiv, if the file does not start with a section definition, the first line will be parsed as command line parameters. Nostalgia era fr fr 🦋

You may place comments into the file by beginning a line with ; or #. Comments at the end of a line are not supported — full-line comments only, bestie, don't try it.

Other supported paths for the configuration file are ~/.pqivrc, /etc/xdg/pqivrc and /etc/pqivrc. pqiv will use whichever file it finds first. You can use the environment variable PQIVRC_PATH to override the configuration file. Your config, your rules 👑

🌟 EXAMPLES 🌟

Let's get practical, bestie. Real commands, real results:

pqiv --bind-key="a { goto_file_byindex(0) }" --bind-key='c {
command(echo -n $1 | xclip) }' --sort foo bar.pdf

Rebinds a to go back to the first image, c to store the path to the current image to the clipboard using xclip, and loads all files from the foo folder and bar.pdf, sorted. Clipboard game: unmatched 📋✨

pqiv --slideshow --watch-directories --end-of-files-action=wait
--slideshow-interval=0.001 test

Load all files from the test folder in a slideshow progressing very fast, and in the end wait until new files become available. This effectively displays new images as they appear in a directory and is useful e.g. if you output images from a script that you later intent to combine into a movie and wish to monitor progress. Basically a live progress bar but make it ✨ pictures ✨

pqiv --slideshow --allow-empty-window --watch-directories
--wait-for-images-to-appear --lazy-load test

Set up a slideshow that displays all images from the test folder such that it is possible to remove all images from the directory and place new ones into it afterwards without pqiv exiting. She simply cannot be killed 💀🔥

echo "output_file_list(); quit()" | pqiv --actions-from-stdin test

Output a list of all files from the test folder that pqiv can handle and quit. One and done, no notes 🎀

🐛 BUGS 🐛

Please report any bugs on github, on https://github.com/phillipberndt/pqiv

(Not me asking you to file a good issue with reproduction steps... okay yes, me asking that 🙈)

👑 AUTHOR 👑

Phillip Berndt (phillip dot berndt at googlemail dot com)

And that's the whole page, bestie — pqiv version 2.13.3, dated November 2025, section pqiv(1). You read all of it, which means you're officially built different 🫶💖 Go look at some pictures.

📦 where this page comes from