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)

1. Open your ranger configuration file: ~/.config/ranger/rc.conf.

2. 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.

3. 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

1. Create the directory:

   mkdir -p ~/.config/sxiv/exec
   

2. 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"
   

3. Make the script executable:

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

4. 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:

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

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

2. Generate config.h:

   make config.h
   

3. 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
   

4. Compile and install:

   make
   sudo make install
   

5. 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

5.1 Ranger Shortcuts

5.2 sxiv Gallery Mode Shortcuts

5.3 sxiv Single-Image Mode Shortcuts

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