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.
TL;DR
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
Outline
- Requirements
- Installation
- iTerm
- Ranger
- imgcat
- Dependencies
- Configuration
- Known Problems
- Image display
- tmux
- Ranger in action
- 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 commandsrc.conf
: Configuration and keybindingsrifle.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:
ranger
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.
_
Pingback: Use Ranger as a file explorer in vim