Ranger image preview on OSX with iTerm2

How to configure ranger image preview on OSX with iTerm2? Ranger’s image preview in iTerm2 does not work out of the box and you will need some additional scripts and config settings to get it working. Here you can see step by step how it gets done.


Install iTerm >= 2.9 and…

# Install homebrew
command -v brew > /dev/null 2&>1 || ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

# Install ranger
brew install ranger

# Add imgcat to ~/bin
test -d $HOME/bin || mkdir $HOME/bin
wget -O ~/bin/imgcat https://raw.githubusercontent.com/gnachman/iTerm2/master/tests/imgcat

# Ranger init
ranger --copy-config=all

# Ranger config
sed -e "s/set\spreview_images\s.*$/set preview_images true/" ~/.config/ranger/rc.conf > ~/.tmp.tmp \
    && mv ~/.tmp.tmp ~/.config/ranger/rc.conf && rm ~/.tmp.tmp
sed -e "s/set\spreview_images_method.*$/set preview_images_method iterm3/" ~/.config/ranger/rc.conf > ~/.tmp.tmp \
    && mv ~/.tmp.tmp ~/.config/ranger/rc.conf && rm ~/.tmp.tmp


  1. Requirements
  2. Installation
    1. iTerm
    2. Ranger
    3. imgcat
    4. Dependencies
  3. Configuration
  4. Known Problems
    1. Image display
    2. tmux
  5. Ranger in action
  6. Further readings

1. Requirements

You need to make sure to meet the following requirements.

As of now, the stable release of iTerm2 does not support image preview so you will have to download the test version here.

Also note to get the full range of previews in ranger you will need the following optional tools:

  • file for determining file types
  • The python module chardet, in case of encoding detection problems
  • sudo to use the “run as root”-feature
  • img2txt (from caca-utils) for previewing images in ASCII-art
  • highlight for syntax highlighting of code
  • atool for previews of archives
  • lynx, w3m or elinks for previews of html pages
  • pdftotext for pdf previews
  • transmission-show for viewing bit-torrent information
  • mediainfo or exiftool for viewing information about media files

2. Installation

2.1 iTerm

  • Download iTerm2 test version here.
  • Install

2.2 Ranger

On OSX most cli applications can be installed using homebrew. So we first have to install it and then simply use it to install ranger itself.

# Install homebrew
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

# Install ranger
brew install ranger

2.3 imgcat

Download the latest copy of imgcat from github and put it into a bin directory which is inside your $PATH variable. (What is PATH)

If you have a ~/bin directory, just put it there and it will work for your user only, otherwise put it into /usr/local/bin for all users.

# Download it to ~/bin
wget -O ~/bin/imgcat https://raw.githubusercontent.com/gnachman/iTerm2/master/tests/imgcat

# Download it to /usr/local/bin (requires sudo)
sudo wget -O /usr/local/bin/imgcat https://raw.githubusercontent.com/gnachman/iTerm2/master/tests/imgcat

2.4 Dependencies

For all ranger previews you can optionally install the above listed dependencies via homebrew:

brew install libcaca highlight atool lynx w3m elinks poppler transmission mediainfo exiftool

3. Configuration

If you are using ranger for the first time, generate the ranger config files.

ranger --copy-config=all

Now you can go to ~/.config/ranger and see what files have been generated:

cd ~/.config/ranger
ls -la

total 88
drwxr-xr-x 7 cytopia staff   238 Sep 23 01:02 ./
drwxr-xr-x 4 cytopia staff   136 Sep 23 01:02 ../
-rw-r--r-- 1 cytopia staff  2624 Sep 23 01:02 commands.py
-rw-r--r-- 1 cytopia staff 46073 Sep 23 01:02 commands_full.py
-rw-r--r-- 1 cytopia staff 18399 Sep 23 01:02 rc.conf
-rw-r--r-- 1 cytopia staff  9346 Sep 23 01:02 rifle.conf
-rwxr-xr-x 1 cytopia staff  3822 Sep 23 01:02 scope.sh

Let’s go over them quickly:

  • commands.py: Commands which are launched with :
  • commands_full.py: Full set of commands
  • rc.conf: Configuration and keybindings
  • rifle.conf: File associations (which program to use for opening files)
  • scope.sh: Responsible for various filet previews

Currently the only important file to us is rc.conf. Open it in your favorite editor and change the following two lines to look like this:

# Use one of the supported image preview protocols
set preview_images true

# Set the preview image method. Supported methods:
# * w3m (default):
#   Preview images in full color with the external command "w3mimgpreview"?
#   This requires the console web browser "w3m" and a supported terminal.
#   It has been successfully tested with "xterm" and "urxvt" without tmux.
# * iterm2:
#   Preview images in full color using iTerm2 image previews
#   (http://iterm2.com/images.html). This requires using iTerm2 compiled
#   with image preview support.
set preview_images_method iterm2

Now you are all set and can enjoy to have ranger image preview on iTerm2.

4. Known Problems

4.1 Image display

When the images do not show up correctly you will need to alter rc.conf and set draw_borders to true:

vim ~/.config/ranger/rc.conf
# Draw borders around columns?
set draw_borders true

4.2 tmux

The problem I have encountered and haven’t solved so far is that this does not work inside a tmux session. So if anybody knows how to make ranger preview images with iTerm2 inside tmux, please let me know.

5. Ranger in action

Here are a few slides to see ranger in action:


6. Further readings

If you want to know how to integrate ranger into vim as a file explorer with all its cool features, read: Use ranger as a file explorer in vim.


7 comments on “Ranger image preview on OSX with iTerm2”

  1. Pingback: Use Ranger as a file explorer in vim

  2. Anonymous Reply

    Hi. The imgcat script moved to another URL. You can use “sed -i” to replace in-place instead of creating a temporal file.

  3. Name Reply

    Hi. The imgcat script moved to another URL. You can use “sed -i” to replace in-place instead of creating a temporal file.

Leave a Reply

Your email address will not be published.