IMV(1)

📦
version 5.0.1 · 8 versions
, in alpine 3.24

💖 IMV(1) — the imv manual, bestie edition 💅

okay so welcome to imv(1), the manual page. yes you're reading a manpage, and yes it's gonna be fun, because this one is genuinely a slay. grab a snack 🍓

✨ NAME ✨

imv — image viewer for X11 and Wayland. that's it, that's the icon.

🌸 DESCRIPTION 🌸

imv is an image viewer for X11 and Wayland, aimed at users of tiling window managers (yes, the tiling girlies are the main characters here, no cap 👑). it supports a wide variety of image file formats — including animated gif files, hello?? — and it will automatically reload the current image if it is changed on disk. it just knows. it's giving attentive bestie energy fr fr.

🎀 SYNOPSIS 🎀

imv [options] [paths...]

✨ OPTIONS ✨

  • -h — show help message and quit. short and sweet.
  • -v — show version and quit. also short, also sweet.
  • -b <background> — set the background colour. it can either be a 6-digit hexadecimal colour code, or checks to show a chequered background. pick your vibe 🎨
  • -c <command> — specify a command to be run on launch, after the configuration has been loaded. you can use it to configure custom keys with the bind command. this option can be used multiple times (stack 'em, bestie), and commands are run in the order that they have been passed to imv.
  • -d — start with overlay visible. show it off from the jump.
  • -f — start fullscreen. main character energy, immediately.
  • -i <id> — set the X11 resource name / wayland app id of the created window. name your window, it deserves it.
  • -l — list open files to stdout at exit. receipts, on the way out 🧾
  • -n <path|index> — start with the given path, or index, selected.
  • -r — load directories recursively. go deep 🌀
  • -s <none|shrink|full|crop> — set scaling mode to use. none will show each image at its actual size. shrink will scale down the image to fit inside the window. full will both scale up and scale down the image to fit perfectly inside the window. crop will scale and crop the image to fill the window. defaults to full. pick your fighter 💅
  • -t <slideshow_duration> — start in slideshow mode, with each image shown for the given number of seconds. set the vibe, walk away.
  • -u <linear|nearest_neighbour> — set upscaling method used by imv.
  • -w <windowtitle> — set window title when starting imv. label your creation 🏷️
  • -x — disable looping of input paths. no more round trips.
  • -W <width> — initial width of window.
  • -H <height> — initial height of window.

👑 COMMANDS 👑

commands can be entered by pressing :. then it's go time. imv supports the following commands:

  • quit — quit imv. aliased to q.
  • pan <x> <y> — pan the view by the given amounts. move it, move it 🕺
  • next <offset> — move forwards by a given number of images. aliased to n
  • prev <offset> — move backwards by a given number of images. aliased to p
  • goto <index> — select an image by index. 1 is the first image, 2 the second, etc. the last image can be indexed as -1, the second last as -2. aliased to g.
  • zoom <amount|actual> — zoom into the image by the given amount. negative values zoom out. actual resets the zoom to 100%, showing the image at its actual size. aliased to z.
  • rotate <'to'|by> <angle> — rotate image clockwise by/to the given amount in degrees. 🔄
  • flip <'horizontal'|vertical> — flip image horizontally/vertically (across vertical/horizontal axis).
  • open [-r] <paths ...> — add the given paths to the list of open images. if the -r option is specified, do so recursively. shell expansions may be used. aliased to o.
  • close [index|all] — close the currently selected image, or the image at the given index, or all images. bye bestie 👋
  • fullscreen — toggle fullscreen.
  • overlay — toggle the overlay.
  • exec <command> — execute a shell command. imv provides various environment variables to the command executed. these are documented in the Environment Variables section. (yes, that's later, keep reading 🫶)
  • center — recenter the selected image.
  • reset — reset the view, centering the image and using the current scaling mode to rescale it. factory settings, iconic.
  • next_frame — if an animated gif is currently being displayed, load the next frame.
  • toggle_playing — toggle playback of the current image if it is an animated gif.
  • scaling <none|shrink|full|crop|next> — set the current scaling mode. setting the mode to next advances it to the next mode in the list.
  • upscaling <linear|nearest_neighbour|next> — set the current upscaling method. setting the method to next advances it to the next method in the list.
  • slideshow <+amount|-amount|duration> — increase or decrease the slideshow duration by the given amount in seconds, or set its duration directly. aliased to ss.
  • background <checks|hexadecimal-code> — set the background color. checks for a chequerboard pattern, or specify a 6-digit hexadecimal color code. aliased to bg.
  • bind <keys> <commands> — binds an action to a set of key inputs. uses the same syntax as the config file, but without an equals sign between the keys and the commands. for more information on syntax, see imv(5).

🦋 DEFAULT BINDS 🦋

imv comes with several binds configured by default (they ate, honestly):

  • q — quit
  • Left arrow — previous image
  • Right arrow — next image
  • gg — go to first image
  • G — go to last image
  • j — pan down
  • k — pan up
  • h — pan left
  • l — pan right
  • x — close current image
  • f — toggle fullscreen
  • d — toggle overlay
  • p — print current image to stdout
  • Up arrow — zoom in
  • Down arrow — zoom out
  • i — zoom in
  • o — zoom out
  • + — zoom in
  • - — zoom out
  • Ctrl+r — rotate clockwise by 90 degrees
  • c — center image
  • s — next scaling mode
  • S — next upscaling mode
  • a — zoom to actual size
  • r — reset zoom and pan
  • . — next frame (for animations)
  • Space — pause/play animations
  • t — start slideshow/increase delay by 1 second
  • T — stop slideshow/decrease delay by 1 second

🌈 CONFIGURATION 🌈

the path to a config file can be given via the $imv_config environment variable. if not found, imv will search for it in the following locations (in this order, bestie):

  • $XDG_CONFIG_HOME/imv/config (recommended — the ~aesthetic~ choice ✨)
  • $HOME/.config/imv/config
  • $HOME/.imv_config
  • $HOME/.imv/config
  • /usr/local/etc/imv_config
  • /etc/imv_config

a default config file is shipped with imv into /etc/imv_config.

for documentation on the config file format, see imv(5). 📖

🧚 ENVIRONMENT VARIABLES 🧚

when imv executes a shell command, it provides a number of environment variables, exposing imv's state. these environment variables are also available when customising the window's title, or the overlay text. so many little lore drops 💜

  • $imv_pid — the pid of this instance of imv. useful for running imv-msg in scripts.
  • $imv_current_file — path of currently selected image.
  • $imv_scaling_mode — name of the current scaling mode.
  • $imv_loading — 1 if a new image is loading, 0 otherwise.
  • $imv_current_index — index of current image, from 1-N.
  • $imv_file_count — total number of files.
  • $imv_width — width of the current image.
  • $imv_height — height of the current image.
  • $imv_scale — scaling of current image in percent.
  • $imv_slideshow_duration — number of seconds each image is shown for.
  • $imv_slideshow_elapsed — how long the current image has been shown for.

💀 IPC 💀

imv can accept commands from another process over a unix socket. each instance of imv will open a unix socket named $XDG_RUNTIME_DIR/imv-$PID.sock. if $XDG_RUNTIME_DIR is undefined, the socket is placed into /tmp/ instead.

the imv-msg(1) utility is provided to simplify this from shell scripts. bestie-communication protocol, lowkey 🫶

🌟 AUTHORS 🌟

imv is written and maintained by Harry Jeffery <me@harry.pm> with contributions from other developers.

full source code and other information can be found at https://sr.ht/~exec64/imv.

🎀 SEE ALSO 🎀

imv(5) imv-msg(1) imv-dir(1)

and that's the whole page, bestie. go look at some pictures 💖

okay bye ily, this manual page was served up on 03/22/2026 as the IMV(1) edition — periodt, no cap, don't forget to hydrate 💅✨🦋

📦 where this page comes from