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
- Known Problems
- Image display
- Ranger in action
- Further readings
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
- Download iTerm2 test version here.
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
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
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
If you are using ranger for the first time, generate the ranger config files.
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 around columns? set draw_borders true
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.