One of ranger’s most powerful features is its ability to preview various file types directly in the terminal. This guide shows you how to customize the preview system to support a wide range of media files with optimal display settings.

Changelog

DateChange
2025-07-18Initial Version: Created guide for customizing media previews in ranger

1. Understanding Ranger’s Preview System

Ranger uses a script called scope.sh to generate previews for different file types. This script determines how to handle each file based on its MIME type or extension, then calls the appropriate external tools to generate a preview.

1.1. The Preview Process

When you select a file in ranger:

  1. Ranger calls the scope.sh script
  2. The script identifies the file type
  3. It selects an appropriate preview method
  4. The preview is displayed in the preview pane

1.2. Default Configuration

By default, ranger comes with a sample scope.sh file, but it’s not automatically installed. You need to copy it to your configuration directory and customize it for your needs.

2. Setting Up the Preview Script

2.1. Copy the Default scope.sh

First, create your ranger configuration directory if it doesn’t exist:

mkdir -p ~/.config/ranger

Then, copy the default scope.sh script:

ranger --copy-config=scope

This will create ~/.config/ranger/scope.sh with the default configuration.

2.2. Make the Script Executable

Ensure the script is executable:

chmod +x ~/.config/ranger/scope.sh

3. Installing Preview Dependencies

To get the most out of ranger’s preview capabilities, you’ll need to install various tools for different file types:

# For Debian/Ubuntu
sudo apt update && sudo apt install highlight atool lynx mediainfo poppler-utils \
    ffmpegthumbnailer imagemagick transmission-cli odt2txt \
    python3-pygments catdoc docx2txt fontforge

# For Arch Linux
sudo pacman -S highlight atool lynx mediainfo poppler ffmpegthumbnailer \
    imagemagick transmission-cli python-pygments catdoc fontforge

# For Fedora
sudo dnf install highlight atool lynx mediainfo poppler-utils ffmpegthumbnailer \
    ImageMagick transmission python3-pygments catdoc fontforge

# Optional: Install xlsx2csv for spreadsheet previews
pip install xlsx2csv

4. Customizing the Preview Script

Now let’s customize the scope.sh script to enhance the preview capabilities. Open the file in your favorite text editor:

vim ~/.config/ranger/scope.sh

4.1. Image Preview Configuration

Find the section that handles images and customize it:

case "${mimetype}" in
    # Image previews
    image/*)
        # Use preview size of 1920px for large images
        local geometry="1920x1080"
        if [[ "${mimetype}" == "image/svg+xml" ]]; then
            convert -- "${FILE_PATH}" "${IMAGE_CACHE_PATH}" && exit 6
        else
            exiftool -b -PreviewImage -w "${IMAGE_CACHE_PATH}" "${FILE_PATH}" && exit 6
            # If exiftool failed, try standard conversion
            convert -- "${FILE_PATH}[0]" -resize "${geometry}" "${IMAGE_CACHE_PATH}" && exit 6
        fi
        ;;

4.2. Video Preview with FFmpegthumbnailer

Enhance the video preview section:

video/*)
    # Video preview using ffmpegthumbnailer
    ffmpegthumbnailer -i "${FILE_PATH}" -o "${IMAGE_CACHE_PATH}" -s 0 -q 10 && exit 6
    exit 1
    ;;

4.3. PDF Preview Configuration

Improve PDF preview with higher resolution:

application/pdf)
    # Higher quality PDF preview (first page)
    pdftoppm -f 1 -l 1 -scale-to 1024 -singlefile -jpeg "${FILE_PATH}" "${IMAGE_CACHE_PATH%.*}" && exit 6
    exit 1
    ;;

4.4. Office Documents Preview

Add better support for office documents:

# Office documents
application/vnd.openxmlformats-officedocument.wordprocessingml.document|application/vnd.oasis.opendocument.text)
    # Convert to plain text
    docx2txt "${FILE_PATH}" - && exit 5
    odt2txt "${FILE_PATH}" && exit 5
    exit 1
    ;;
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet|application/vnd.oasis.opendocument.spreadsheet)
    # Convert to CSV
    xlsx2csv "${FILE_PATH}" && exit 5
    exit 1
    ;;

4.5. Archive Content Preview

Enhance archive preview:

# Archives
application/zip|application/x-rar|application/x-7z-compressed|application/x-tar|application/x-bzip2|application/x-gzip|application/x-xz)
    # List archive contents
    atool --list -- "${FILE_PATH}" && exit 5
    bsdtar --list --file "${FILE_PATH}" && exit 5
    exit 1
    ;;

4.6. Syntax Highlighting for Code

Improve code syntax highlighting:

# Syntax highlighting for code
text/*)
    # Try to use pygmentize for syntax highlighting
    env COLORTERM=8bit bat --color=always --style=plain "${FILE_PATH}" && exit 5
    pygmentize -f terminal -O style=monokai -g "${FILE_PATH}" && exit 5
    # Fallback to cat if pygmentize is not available
    cat "${FILE_PATH}" && exit 5
    exit 1
    ;;

5. Advanced Customizations

5.1. Custom Preview Size

You can adjust the preview size by modifying your rc.conf:

# Add to ~/.config/ranger/rc.conf
set preview_images true
set preview_images_method kitty  # or use: w3m, iterm2, terminology, urxvt, sixel
set preview_max_size 10485760    # Don't preview files larger than 10MB

5.2. Font Preview

Add font preview capability:

# Add to scope.sh under the case statement
# Note: This requires FontForge to be installed for the fontimage command
font/*|application/font*|application/x-font*)
    preview_png="/tmp/$(basename "${IMAGE_CACHE_PATH%.*}").png"
    if fontimage -o "${preview_png}" \
                 --pixelsize "120" \
                 --fontname \
                 --pixelsize "80" \
                 --text "  ABCDEFGHIJKLMNOPQRSTUVWXYZ  " \
                 --text "  abcdefghijklmnopqrstuvwxyz  " \
                 --text "  0123456789.:,;(*!?')  " \
                 --text "  The quick brown fox jumps over the lazy dog.  " \
                 "${FILE_PATH}";
    then
        convert -- "${preview_png}" "${IMAGE_CACHE_PATH}" \
            && rm "${preview_png}" \
            && exit 6
    else
        exit 1
    fi
    ;;

5.3. Audio File Preview

Add audio file metadata preview:

# Add to scope.sh under the case statement
audio/*)
    # Show audio metadata
    mediainfo "${FILE_PATH}" && exit 5
    exiftool "${FILE_PATH}" && exit 5
    exit 1
    ;;

6. Configuring Image Preview Methods

Ranger supports several methods for displaying image previews in the terminal. You’ll need to configure both scope.sh and rc.conf to use them properly.

6.1. Available Preview Methods

Add this to your rc.conf:

# Choose one of these methods:
set preview_images true
set preview_images_method kitty  # Options: kitty, ueberzug, w3m, iterm2, terminology, urxvt, sixel

Different methods work with different terminals:

  • kitty: For the kitty terminal
  • ueberzug: Works with most terminals (requires python-ueberzug)
  • w3m: Works with most terminals that support w3m
  • iterm2: For iTerm2 on macOS
  • terminology: For the Terminology terminal
  • urxvt: For urxvt with pixbuf support
  • sixel: For terminals with sixel support

For the best image preview experience across different terminals, install UeberzugPP. Note that the original Ueberzug project is no longer maintained, and UeberzugPP is the modern replacement with Wayland support:

# For Arch Linux (via AUR)
yay -S ueberzugpp

# For other distributions (compile from source)
git clone https://github.com/jstkdng/ueberzugpp.git
cd ueberzugpp
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make
sudo make install

# Alternative: Install via pip (if available)
pip install ueberzugpp

Then set in rc.conf:

set preview_images true
set preview_images_method ueberzug

Note: Even though we’re using UeberzugPP, the method name in ranger’s configuration remains ueberzug for compatibility.

7. Testing Your Configuration

After making changes to scope.sh, restart ranger and test the preview functionality:

  1. Navigate to different file types
  2. Check if the previews are displayed correctly
  3. Adjust the configuration as needed

7.1. Debugging Preview Issues

If previews aren’t working as expected:

  1. Run ranger with the --debug flag:

    ranger --debug

  2. Check the output for errors related to the preview script

  3. Make sure all required dependencies are installed

  4. Verify that scope.sh is executable

8. Practical Examples

With proper image preview configuration, you can use ranger as an image browser:

  1. Navigate to a directory with images
  2. Use arrow keys to browse through images
  3. See high-quality previews directly in the terminal

8.2. Code Review

With syntax highlighting enabled:

  1. Navigate to source code files
  2. See syntax-highlighted code in the preview pane
  3. Quickly scan through multiple files

8.3. Document Management

With document preview support:

  1. Browse through PDF documents
  2. See previews of the first page
  3. View plain text content of office documents

9. Troubleshooting

9.1. Missing Dependencies

If certain file types don’t preview correctly, you might be missing dependencies:

# Check if a command is available
which ffmpegthumbnailer
which convert
which pdftoppm

Install any missing tools using your package manager.

9.2. Terminal Compatibility

Not all terminals support all preview methods:

  • If images don’t display, try a different preview_images_method in rc.conf
  • For kitty terminal, make sure you’re using the kitty method
  • For other terminals, try ueberzug or w3m

9.3. Large Files

If ranger becomes slow when previewing large files:

# Add to rc.conf
set preview_max_size 5242880  # Don't preview files larger than 5MB

Summary

With these customizations to ranger’s preview system, you’ve enhanced your terminal file manager with rich media preview capabilities:

✅ High-quality image previews
✅ Video thumbnails
✅ PDF document previews
✅ Office document text extraction
✅ Syntax highlighting for code
✅ Archive content listing
✅ Font previews

This setup transforms ranger from a simple file manager into a powerful media browser that lets you quickly preview and navigate through various file types without leaving your terminal.

🖼️RANGER IMAGE PREVIEWS 🔧RANGER CUSTOM COMMANDS 📚UEBERZUG DOCUMENTATION