IMGCAT(1)

📦 version 2.6.0, in nixos 26.05, nixpkgs unstable

💖 imgcat(1) — cat, but for images 💖

okay so picture this: you're in the meow corner of the manual, and you just want to see a picture in your terminal. bestie, this is THE tool. ✨

🌸 SYNOPSIS 🌸

imgcat [options] image
imgcat [options] < image

🦋 DESCRIPTION 🦋

imgcat prints an image to your terminal screen. that's it. that's the whole vibe. 💅

the image can either be handed over as a command line argument, or piped in through stdin. both are valid, both are iconic.

by default, the image is printed at the full width and color depth detected for your terminal. wanna override? sure, queen:

  • use -w to adjust the maximum width
  • use -R to prevent resizing entirely — even if the image is way too big to fit in the terminal 😭
  • use -d to explicitly set the color depth
  • use -r to adjust the height (the "r" stands for "number of rows", iykyk)

the image gets scaled without affecting the aspect ratio, unless you pass -P. periodt.

🌈 half-height mode, aka the glow-up

setting -H enables the use of half-height block drawing characters (as opposed to the "full height" spaces used in the default mode). this effectively doubles the vertical resolution of the terminal, so the image on your screen appears less "squished" and has a greater pixel resolution. main character energy, honestly. 🔥

⚠️ heads up bestie: this effect works best on terminals that output using a bitmapped font and have a line height of exactly 100% (example: https://git.io/vhW5F).

using anti-aliased fonts may distort the blocks, and using a taller line height will make the half-height block cover less than half of the block, which distorts the image even more (example: https://git.io/vhW5d). your millage may vary. 💀

🎀 when output isn't a terminal

if the output is not a terminal (that is, output is redirected to a file, or piped into another program), then the image is not resized and the color depth is set to 8 colors. overriding both width, height, and color depth still work though. slay. ✨

make sure your TERM environment variable is set to a terminfo with the full capabilities of your terminal! see Troubleshooting if you're having a problem with this. 🫶

✨ OPTIONS ✨

  • -d MODE, --depth=MODE — explicitly set the output color depth to one of ansi, 8 (alias of ansi), 256, 24bit, true (alias of 24bit) or iterm. if not provided, the output color depth will be inferred with tput colors.
  • -h, --help — show common options and quit. cute and quick. 💖
  • -H, --half-height — prints half-height blocks to double the vertical resolution and make for a less squished image. works best when each character cell is exactly twice as tall as it is wide, and when your terminal is using a bitmapped font.
  • -r ROWS, --height=ROWS — resizes the image to ROWS characters high. does nothing if --no-resize is provided. maintains the original image's aspect ratio if --width is NOT provided.
  • -P, --no-preserve-aspect-ratio — allows for arbitrary image resizing when specifying both --width and --height. by default, if both --width and --height are provided, the image's aspect ratio is preserved (it does not get stretched in any direction), and --width and --height specify the maximum amount of characters the image will be resized to. if you provide --no-preserve-aspect-ratio, then --width and --height are exact dimensions, and the image might get squished accordingly. 🙈
  • -R, --no-resize — does not resize the image to fit the terminal's width. overrides both --width and --height.
  • -v, --version — show version and quit.
  • -w COLS, --width=COLS — shrink the image to COLS characters wide. does nothing if --no-resize is provided, or if the image is already as small as the provided width. maintains the original image's aspect ratio if --height is NOT provided.
  • --8, --ansi — set the output colour depth to 8. same as --depth=8. (yes, "colour" with a u, she's fancy 💅)
  • --256 — set the output colour depth to 256. same as --depth=256.
  • --24bit, --true — set the output colour depth to 24 bit or "true" color. same as --depth=24bit.
  • --iterm2 — set the output to iTerm inline image mode. same as --depth=iterm2.

🍓 iTerm2 3.0

imgcat supports iTerm2's full-color inline images (use -d iterm to explicitly enable this). however — and this is the plot twist — iTerm2 is bundled with a script that is also called imgcat! 😭

to use this program in preference to the script bundled with iTerm2, edit your shell's configuration file such that, after the line that sources iTerm2's shell integration and utilities, you unalias its built-in script:

unalias imgcat

there. fixed. you're welcome. 🫶

🧚 Troubleshooting

first, test how many colors your terminal can output:

$ tput colors
256

if this is not what you expect, you might want to change your TERM environment variable. for example, iTerm2 users will probably want the following:

$ export TERM=xterm-256color

however, it's better that your terminal emulator reports itself with the proper value for TERM. for iTerm2, again, look under the current profile settings > Terminal > Terminal Emulation > and change "Report Terminal Type". ⭐

👑 BUGS

see GitHub Issues: https://github.com/eddieantonio/imgcat/issues

💜 AUTHOR

imgcat was written by Eddie Antonio Santos https://eddieantonio.ca/ and contributors.

okay bestie, that's the whole page 💖 this is the imgcat User Manual, dated December 18, 2023 — go forth and put pictures in your terminal, no cap. 🦋🎀✨

📦 where this page comes from