The ranger file manager is already a powerful tool for navigating your filesystem, but with the addition of fzf (fuzzy finder) and bat (syntax highlighter), you can supercharge your file searching capabilities. This guide will show you how to integrate these tools for a seamless and visually appealing search experience.

Changelog

DateChange
2025-07-18Initial Version: Created guide for integrating fzf and bat with ranger

1. Prerequisites

Before we begin, ensure you have the following tools installed on your system:

  • ranger: The terminal file manager
  • fzf: Command-line fuzzy finder
  • bat: A cat clone with syntax highlighting

Installation on Various Distributions

# For Debian/Ubuntu
sudo apt update && sudo apt install ranger fzf bat

# For Arch Linux
sudo pacman -S ranger fzf bat

# For Fedora
sudo dnf install ranger fzf bat

Note: On some distributions, bat might be packaged as batcat. You can create an alias in your shell configuration file:

alias bat='batcat'

2. Creating the Custom fzf_select Command

The integration requires adding a custom command to ranger. This command will use fzf for searching and bat for file previews.

2.1. Create or Edit commands.py

First, navigate to your ranger configuration directory and create or edit the commands.py file:

mkdir -p ~/.config/ranger
touch ~/.config/ranger/commands.py

If you don’t have a commands.py file yet, you can generate a template with:

ranger --copy-config=commands

2.2. Add the fzf_select Command

Open the commands.py file in your favorite text editor and add the following code:

from ranger.api.commands import Command
import os
import subprocess

class fzf_select(Command):
    """
    :fzf_select

    Find a file or directory using fzf with preview using bat, excluding certain directories unless currently in them.
    """
    def execute(self):
        exclude_dirs = ['Remote', 'USBmount', 'NFSshares', 'Games_ROMS']  # List of directories to exclude
        current_dir = os.getcwd()
        base_name = os.path.basename(current_dir)

        # Check if the current directory is in the list of directories to exclude
        if base_name in exclude_dirs:
            find_command = "find . -type f -o -type d"
        else:
            # Construct the find command with exclusion criteria
            exclude_opts = ' '.join(f"-path './{d}' -prune -o" for d in exclude_dirs)
            find_command = f"find . \\( {exclude_opts} -false \\) -o \\( -type f -o -type d \\) -print"

        command = f"{find_command} | fzf --preview '[[ -f {{}} ]] && bat --style=numbers --color=always {{}} || echo {{}} is a directory' --preview-window=right:70%:wrap --exact"

        fzf = subprocess.Popen(command, stdout=subprocess.PIPE, shell=True, text=True, cwd=current_dir)
        selected, _ = fzf.communicate()

        if fzf.returncode == 0:
            selected = selected.strip()
            selected_path = os.path.abspath(selected)
            if os.path.isdir(selected_path):
                # Change to the directory if it's a directory
                self.fm.cd(selected_path)
            else:
                # Open the file if it's a file
                self.fm.select_file(selected_path)

            # Explicitly refresh the ranger window
            self.fm.ui.redraw_window()

This command will:

  1. Exclude specific directories from the search (unless you’re already in one of them)
  2. Use bat for file previews and show a simple message for directories
  3. Execute fzf with the appropriate options
  4. Navigate to the selected file or directory
  5. Explicitly refresh the ranger window after selection

3. Creating a Keyboard Shortcut

Now that we have our custom command, let’s create a keyboard shortcut to invoke it easily.

3.1. Edit rc.conf

Open your ranger configuration file:

vim ~/.config/ranger/rc.conf

If you don’t have this file yet, you can generate it with:

ranger --copy-config=rc

3.2. Add the Keyboard Mapping

Add the following line to map the fzf_select command to a keyboard shortcut. In this example, we’ll use zi (which stands for “zoom in”):

map zi fzf_select

This shortcut is easy to remember as zi stands for “zoom in” - which is exactly what this command does: it zooms into your file structure to quickly find what you’re looking for.

ShortcutDescription
ziStart fuzzy search with fzf and bat preview (“zoom in” to your files)

4. Advanced Configuration

4.1. Customize Directory Exclusions

You can modify the list of directories to exclude from the search by changing the exclude_dirs list in the fzf_select command:

exclude_dirs = ['Remote', 'USBmount', 'NFSshares', 'Games_ROMS', 'VirtualMachines']  # Add or remove directories as needed

4.2. Show Hidden Files

If you want to include hidden files in your search, modify the find_command variable:

find_command = "find . -type f -o -type d -name '.*' -o -type f -o -type d"

4.3. Customize Preview Options

You can customize how bat displays file previews by modifying the preview part of the command:

command = f"{find_command} | fzf --preview '[[ -f {{}} ]] && bat --style=full --color=always --line-range :150 {{}} || echo {{}} is a directory' --preview-window=right:60%:wrap --exact"

This example:

  • Uses the “full” style for bat (includes line numbers, Git modifications, etc.)
  • Shows up to 150 lines in the preview
  • Sets the preview window width to 60% of the terminal

5. Usage

Once everything is set up, you can use your new fuzzy search capability:

  1. Open ranger in your terminal
  2. Press your configured shortcut (e.g., zi)
  3. Type to search for files
  4. Use arrow keys to navigate through results
  5. Press Enter to select a file or directory

6. Troubleshooting

6.1. Command Not Found

If you get a “Command not found” error when trying to use the shortcut:

  • Make sure you’ve saved the commands.py file correctly
  • Restart ranger to load the new command
  • Check that fzf and bat are installed and in your PATH

6.2. Preview Not Working

If file previews aren’t displaying:

  • Verify that bat is installed correctly
  • Try using batcat instead of bat if you’re on Debian/Ubuntu
  • Check if your terminal supports the preview feature

Summary

With this integration, you’ve significantly enhanced ranger’s search capabilities:

✅ Lightning-fast file searching with fuzzy matching
✅ Beautiful syntax-highlighted previews
✅ Seamless navigation to selected files
✅ Customizable interface and behavior

This setup combines the best of three powerful tools: ranger’s file management, fzf’s search capabilities, and bat’s beautiful syntax highlighting.

📚RANGER CUSTOM COMMANDS 🔍FZF DOCUMENTATION 🦇BAT DOCUMENTATION