Tutorial: Integrating ranger and sxiv with Advanced Features

This tutorial combines all the necessary steps to seamlessly integrate sxiv and ranger, including:

Launching a gallery view from ranger
Configuring keybindings in ranger
Creating an interactive “Open with…” menu in sxiv
Opening ranger from within sxiv
Navigating and using shortcuts in sxiv
Increasing thumbnail sizes by recompiling sxiv

Prerequisites

Arch Linux (or a similar distro; this guide refers to pacman and the AUR)
sxiv and ranger installed
A terminal emulator (e.g., xterm, urxvt, alacritty, kitty)
Standard command-line tools (file, grep, sed, etc.)
gtk-launch (usually available via xdg-utils or a similar package)

1. Set Up the ranger Keybinding (Launch Gallery)

Open your ranger configuration file: ~/.config/ranger/rc.conf.
Add a line to open sxiv in thumbnail mode recursively using a key combination. For example, gG:
```
# Open sxiv in thumbnail mode (-t) recursively (-r) in the current directory (%d)
map gG shell sxiv -tr %d &
```
- -t enables thumbnail mode.
- -r searches subdirectories recursively.
- The trailing & ensures that ranger does not wait for sxiv to close.
Save the file and reload the configuration in ranger with:
```
:reload_config
```
or simply restart ranger.

2. Navigating in sxiv

Open Gallery View: Use sxiv -tr /path/to/your/folder to start directly in thumbnail mode.
Open a Single Image: Highlight an image in the gallery and press Enter.
Switch Between Images (Single-Image Mode):
- n or Space: Next image
- p or Backspace: Previous image
- ]: 10 images forward
- [: 10 images backward
- g: First image, G: Last image
- Right mouse click: Next image, Left mouse click: Previous image
Zoom in the Gallery:
- +: Zoom in
- -: Zoom out
To increase the maximum zoom level, you need to recompile sxiv (see Section 4).

3. Interactive “Open with…” and Ranger Integration in sxiv

We will create a key-handler script that allows the following:

Ctrl-x r: Opens ranger in a new terminal, selecting the current file.
Ctrl-x o (or any other key): Displays an interactive menu of all suitable applications and opens the image with the selected one.

3.1. Create the Script

Create the directory:
```
mkdir -p ~/.config/sxiv/exec
```

Create the file ~/.config/sxiv/exec/key-handler and paste the following content in its entirety:

#!/usr/bin/env sh
#
# ~/.config/sxiv/exec/key-handler
# Interactive script for sxiv:
# - Ctrl-x r → opens ranger in a new terminal with the current file selected
# - Ctrl-x o (and others) → opens an "Open with…" menu to choose an application
# Robust handling of spaces, logging, and i3-compatible terminals

# Logfile for debugging and tracking
LOG=/tmp/sxiv-open.log
echo "=== key-handler started $(date) ===" >>"$LOG"

# Terminal emulator used to open the selection menu
# Possible options: xterm, urxvt, alacritty, kitty …
TERMWIN=${TERMWIN:-urxvt}
echo "TERMWIN set to: $TERMWIN" >>"$LOG"

# $1 contains the key pressed after Ctrl-x
cmd="$1"
echo "Command argument: $cmd" >>"$LOG"

# Remove the prefix argument; all image paths follow via stdin
shift

# Process each file individually (handles paths with spaces)
while IFS= read -r img; do
  echo "Processing file: '$img'" >>"$LOG"

  # === Ranger Integration (Ctrl-x r) ===
  if [ "$cmd" = "r" ]; then
    echo "Ranger Integration: Opening ranger in terminal for '$img'" >>"$LOG"
    # Ranger needs a terminal, so launch it via a terminal emulator
    "$TERMWIN" -e ranger --selectfile="$img" &
    continue
  fi

  # === Default Open-with… Menu (Ctrl-x o or other keys) ===
  # 1) Determine the MIME type of the file
  mime=$(file --mime-type -b "$img")
  echo " MIME-Type: $mime" >>"$LOG"

  # 2) Find matching .desktop files for this MIME type
  mapfile -t apps < <(
    grep -Rl "MimeType=.*$mime" \
      /usr/share/applications ~/.local/share/applications 2>/dev/null \
    | xargs -r -n1 basename \
    | sort -u
  )
  if [ ${#apps[@]} -eq 0 ]; then
    echo " No matching applications found for MIME '$mime'" >>"$LOG"
    continue
  fi
  echo " Found applications: ${apps[*]}" >>"$LOG"

  # 3) Create temporary files for the list and the choice
  list_file=$(mktemp)
  tmp_choice=$(mktemp)
  printf "%s\n" "${apps[@]}" >"$list_file"
  echo " List file: $list_file" >>"$LOG"
  echo " Choice file: $tmp_choice" >>"$LOG"

  # 4) Open the terminal selection menu
  "$TERMWIN" -e bash -lc '
    PS3="Open with: "
    # Read all entries into an array
    IFS=$'\''\n'\'' read -rd "" -r -a options < "'"$list_file"'"
    select opt in "${options[@]}"; do
      # Write the choice to the temp file
      echo "$opt" > "'"$tmp_choice"'"
      break
    done
  '

  # 5) Read the choice and clean up
  choice=$(<"$tmp_choice")
  rm -f "$list_file" "$tmp_choice"
  echo " Selected: $choice" >>"$LOG"
  [ -n "$choice" ] || continue

  # 6) Find the full .desktop file path
  desktop=""
  for d in /usr/share/applications ~/.local/share/applications; do
    if [ -f "$d/$choice" ]; then
      desktop="$d/$choice"
      break
    fi
  done
  echo " Desktop entry: $desktop" >>"$LOG"

  # 7) Read the Exec line and remove placeholders
  exec_cmd=$(grep -m1 '^Exec=' "$desktop" \
             | cut -d= -f2- \
             | sed -E 's/ %[fFuUdDnNickvm]//g')
  echo " Exec command: $exec_cmd" >>"$LOG"

  # 8) Execute the program with the image path
  eval "$exec_cmd \"$img\"" &
  echo " Application started for '$img'" >>"$LOG"
done

# End of log
echo "=== key-handler finished ===" >>"$LOG"

Make the script executable:

chmod +x ~/.config/sxiv/exec/key-handler

TERMWIN variable (optional): If you want to use a terminal other than urxvt, like alacritty, add this to your ~/.bashrc / ~/.profile:
```
export TERMWIN=alacritty
```

4. Thumbnail Sizes (Optional: Recompiling sxiv)

By default, the available thumbnail sizes in sxiv are limited to { 32, 64, 96, 128, 160 } px. If 160px is too small, you can increase them as follows:

Get the sources from the AUR (example using sxiv-git):

git clone https://aur.archlinux.org/sxiv-git.git
cd sxiv-git

Generate config.h:
```
make config.h
```

Adjust Thumbnail Sizes: Open the config.h file and find the _THUMBS_CONFIG section. Change the block to something like this:

#ifdef _THUMBS_CONFIG

/* thumbnail sizes in pixels (width == height): */
static const int thumb_sizes[] = { 32, 64, 96, 128, 160, 256, 320, 400 };

/* default thumbnail size on startup (index in thumb_sizes[]): */
static const int THUMB_SIZE = 5;  // starts at 256 px
#endif

Compile and install:
```
make
sudo make install
```
Use the New Thumbnail Sizes: In sxiv, sizes up to 400px are now available. Use + to increase and - to decrease the size.

5. Summary of Keybindings

In ranger:
- gG: Start the sxiv gallery in the current directory.
In the sxiv gallery:
- Enter: Open single-image view.
- m: Mark an image (for multi-selection).
- + / -: Zoom in/out (limited to preset sizes).
- Ctrl-x o: “Open with…” menu (interactive).
- Ctrl-x r: Open ranger in a new terminal with the file selected.
In sxiv single-image view:
- n or Space: next image.
- p or Backspace: previous image.
- [ / ]: 10 images forward/backward.
- g / G: first / last image.

6. Debugging & Logs

All actions from the key-handler script are logged to /tmp/sxiv-open.log. There you can see:

The key that was used (ctrl-x r or ctrl-x o).
The detected MIME type.
The found .desktop entries.
The chosen application and the executed command.
The ranger call.

Example:

=== key-handler started Mon Apr 28 18:01:20 CEST 2025 ===
TERMWIN set to: xterm
Command argument: o
Processing file: '/home/.../Example.png'
 MIME-Type: image/png
 Found applications: gimp.desktop firefox.desktop ...
 List file: /tmp/tmp.XXXXXX
 Choice file: /tmp/tmp.YYYYYY
 Selected: gimp.desktop
 Desktop entry: /usr/share/applications/gimp.desktop
 Exec command: gimp-3.0
 Application started for '/home/.../Example.png'
=== key-handler finished ===

If something goes wrong, you can check the log:

less /tmp/sxiv-open.log

CATEGORIES

TAGS

OBLIGATORY GIFS

Tutorial: Integrating ranger and sxiv with Advanced Features

Table of Contents 📑

Prerequisites

1. Set Up the ranger Keybinding (Launch Gallery)

2. Navigating in sxiv

3. Interactive “Open with…” and Ranger Integration in sxiv

3.1. Create the Script

4. Thumbnail Sizes (Optional: Recompiling sxiv)

5. Summary of Keybindings

6. Debugging & Logs

WEBSITE LOADED

STATUS 🚧

VISITOR STATS

LINKS