Image Previews

hut edited this page Jan 31, 2017 · 12 revisions

Since 1.6.0, ranger can preview images in full color. This works by calling a program named w3mimgdisplay that's included in the w3m web browser, which draws images directly into the terminal.

If you use iTerm2, a Mac OS X terminal replacement, you can enable a method that takes advantage of the built-in drawing functionality so you won't need w3m.

Steps to enable it:

With w3mimgdisplay

  • Get a compatible terminal. Terminals that are known to work are rxvt-unicode, xterm and st (at least since st 0.6).
  • install w3m with the image drawing feature. On Arch Linux, the package is called "w3m", on Debian it's "w3m-img".
  • Add the line set preview_images true to your ~/.config/ranger/rc.conf.
  • In the most recent git version, you also need to get the scope.sh configuration file by running ranger --copy-config=scope
  • Restart ranger and navigate to an image file. \o/

With urxvt

The image preview methods urxvt and urxvt_full can be used with the urxvt terminal and are typically more reliable. They use a special escape sequence to change the background of the terminal in order to render the image.

  • Run urxvt with pixbuf support (some operating systems ship it without pixbuf support, but for example ArchLinux has an AUR package called rxvt-unicode-pixbuf which should work)
  • Add the line set preview_images true to your ~/.config/ranger/rc.conf.
  • Add the line set preview_images_method urxvt to your ~/.config/ranger/rc.conf. You can also choose urxvt_full if you would like the image to fill the whole terminal rather than just the preview pane.
  • Restart ranger and navigate to an image file. \o/

With iTerm2

NOTE: You need at least iTerm2 version 2.9 for the image preview feature to work.

  • Add the line set preview_images true to your ~/.config/ranger/rc.conf.
  • Add the line set preview_images_method iterm2 to your ~/.config/ranger/rc.conf.
  • Restart ranger and navigate to an image file. \o/

Troubleshooting

If the w3m program doesn't show images itself, then ranger won't show them either in the w3mimgdisplay mode. Try w3m xkcd.com for example.

Sometimes black stripes are drawn over the images when using w3mimgdisplay. This is due to the unreliable drawing mechanism, and for some people it helps to set the option draw_borders to true.

Sometimes it helps trying a different terminal emulator.

w3mimgdisplay appears not to work with compositing managers like xcompmgr.

If your image previews broke after upgrading ranger's git after september 2015, you need to update scope.sh for image previews to work. See https://github.com/hut/ranger/wiki/Upgrading#image-previews-stopped-working-after-updating-ranger-git

ASCII previews

Oldschool ASCII art previews can be enabled like this:

  • install libcaca (or whatever package provides the "img2txt" executable)
  • get a current scope.sh config, e.g. with ranger --copy-config=scope
  • The following ~/.config/ranger/rc.conf settings are also essential, though the default rc.conf already includes them, so usually you don't need to change anything.
set preview_images false
set use_preview_script true
set preview_script ~/path/to/your/scope.sh

set preview_images false is necessary because otherwise ranger might use full color previews instead.