Image Previews

Toon Nolten edited this page Oct 9, 2018 · 22 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 and Fedora it's "w3m-img".
  • Add the line set preview_images true to your ~/.config/ranger/rc.conf.
  • In the most recent versions, you no longer need to get the configuration file by running ranger --copy-config=scope, however if you do you can edit it to get graphical previews of pdfs and svgs for example.
  • 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/

With mpv

NOTE: You need at least mpv version 0.25 for the below method to work.

NOTE: Requires modification of ranger itself.

The mpv image preview method allows ranger to control an external client for viewing media. The benefit of this approach is that both images and videos share a single, separate window. Some changes are planned, so this method is not included in ranger yet. If you would like to make the changes youself, here are the steps. The rest of this section assumes $ranger is the location of your copy of ranger, not your configuration.

  • Add the following lines to the end of $ranger/ext/
import subprocess
import json
import atexit
import socket
from pathlib import Path

import logging
from logging import info
import traceback

class MPVImageDisplayer(ImageDisplayer):
    """Implementation of ImageDisplayer using mpv, a general media viewer.
    Opens media in a separate X window.

    mpv 0.25+ needs to be installed for this to work.

    def _send_command(self, path, sock):

        message = '{"command": ["raw","loadfile",%s]}\n' % json.dumps(path)
        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        info('-> ' + message)
        message = s.recv(1024).decode()
        info('<- ' + message)

    def _launch_mpv(self, path, sock):

        proc = Popen([
            * os.environ.get("MPV", "mpv").split(),
            "--input-ipc-server=" + str(sock),

        def cleanup():

    def draw(self, path, start_x, start_y, width, height):

        path = os.path.abspath(path)
        cache = Path(os.environ.get("XDG_CACHE_HOME", "~/.cache")).expanduser()
        cache = cache / "ranger"
        sock = cache / "image-slave.sock"

            self._send_command(path, sock)
        except (ConnectionRefusedError, FileNotFoundError):
            info('LAUNCHING ' + path)
            self._launch_mpv(path, sock)
        except Exception as e:
  • Edit $ranger/core/ then search for ImageDisplayer() and make the following changes:
elif self.settings.preview_images_method == "urxvt-full":
    return URXVTImageFSDisplayer()
elif self.settings.preview_images_method == "mpv":          # add this line
    return MPVImageDisplayer()                              # add this line
    return ImageDisplayer()

Additionally edit the line containing from ranger.ext.img_display import to also import MPVImageDisplayer:

from ranger.ext.img_display import (W3MImageDisplayer, ITerm2ImageDisplayer,
                                    URXVTImageDisplayer, URXVTImageFSDisplayer, ImageDisplayer,
  • Ensure the following lines appear in your ~/.config/ranger/rc.conf:
set preview_images true
set preview_images_method mpv
set use_preview_script true
set preview_script ~/path/to/your/     # or whatever your preview script is
  • Restart ranger and navigate to an image file. \o/

If you want mpv to support common image viewing features, see this gist for a sample mpv configuration.


If the w3m program doesn't show images itself, then ranger won't show them either in the w3mimgdisplay mode. Try w3m 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 or a different displaying method.

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 for image previews to work. See

ASCII previews

Oldschool ASCII art previews can be enabled like this:

  • install libcaca (or whatever package provides the "img2txt" executable)
  • get a current 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/

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

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.