fzf `--disabled` Option: Complete Guide to External Search Workflows

The --disabled flag in fzf disables internal fuzzy filtering, turning fzf into a passive UI layer that displays items exactly as received while allowing external commands like ripgrep to handle the actual searching.

The junegunn/fzf command-line fuzzy finder is renowned for its speed, but sometimes you need to delegate the heavy lifting to specialized search tools. The --disabled option (formerly --phony) transforms fzf from an active filter into a passive selector, enabling powerful workflows with external search commands like ripgrep or custom scripts.

What Does the --disabled Flag Do in fzf?

When you invoke fzf with --disabled, the tool sets the internal Phony option to true in src/options.go at line 2714. This initialization propagates to the terminal UI in src/terminal.go (line 1066), where the paused field inherits this state.

The critical behavior occurs in src/core.go at line 403: when paused is true, fzf skips the fuzzy-matching algorithm entirely. Instead of filtering the input list based on your query, fzf forwards the raw input directly to the selection mechanism. The query string becomes available for external use via the {q} placeholder, but fzf itself performs zero filtering.

When to Use fzf --disabled

External Incremental Filtering

The most common use case involves delegating search to external tools like ripgrep, ag, or git log. Since these tools can reload results dynamically, letting fzf also filter would be redundant and computationally wasteful.

Pattern:

RG="rg --column --line-number --no-heading --color=always --smart-case "
fzf --ansi --disabled --query "$INITIAL_QUERY" \
    --bind "start:reload:$RG {q}" \
    --bind "change:reload:sleep 0.1; $RG {q} || true" \
    --preview 'bat --color=always {1} --highlight-line {2}'

This pattern appears in ADVANCED.md at lines 76-80, demonstrating the "Ripgrep launcher" mode where fzf acts purely as the interface while ripgrep handles the actual file searching.

Preview-Only Workflows

When you need a preview window that updates on each keystroke while keeping the list static, --disabled prevents the list from shrinking as you type. The preview command can still reference {q} to display contextual information.

printf '%s\n' $(seq 1 1000) | \
    fzf --disabled \
        --preview 'echo "Query: {q}, Selected: {}"' \
        --bind "enter:execute(echo Selected: {})"

Performance Optimization for Large Datasets

For inputs containing millions of lines, fzf's internal indexing consumes significant memory and CPU. By disabling internal search and delegating to specialized tools (which often use optimized algorithms or parallel processing), you avoid the overhead of maintaining fzf's internal item list in memory for fuzzy matching.

Temporarily Suspending Search

Even when not launched with --disabled, you can bind keys to toggle the search functionality. This allows users to inspect the full unfiltered list mid-session without changing their query.

fzf --bind "ctrl-d:disable-search, ctrl-e:enable-search"

How to Re-enable Search Dynamically

The enable-search and disable-search actions allow runtime toggling of the filtering behavior. When you trigger enable-search, fzf resumes normal fuzzy matching operations; disable-search returns it to pass-through mode.

Example configuration:

fzf --disabled \
    --bind "alt-enter:enable-search+clear-query" \
    --bind "ctrl-d:disable-search"

This is particularly useful when you want to start in "browse" mode (disabled) but occasionally enable filtering for specific subsets.

Complete Code Examples

Ripgrep Integration (External Search)

#!/bin/bash
RG="rg --column --line-number --no-heading --color=always --smart-case "
INITIAL_QUERY="${*:-}"

fzf --ansi --disabled --query "$INITIAL_QUERY" \
    --bind "start:reload:$RG {q}" \
    --bind "change:reload:sleep 0.1; $RG {q} || true" \
    --delimiter : \
    --preview 'bat --color=always {1} --highlight-line {2}' \
    --preview-window 'up,60%,border-bottom,+{2}+3/3,~3'

Static List with Dynamic Preview

git log --oneline --all | \
    fzf --ansi --disabled \
        --preview 'git show --color=always {1}' \
        --preview-window right:50%

Interactive Search Toggle

ps aux | \
    fzf --disabled \
        --header 'Press Ctrl-S to enable filtering' \
        --bind 'ctrl-s:enable-search' \
        --bind 'ctrl-d:disable-search'

Summary

• --disabled disables internal fuzzy filtering by setting the Phony option in src/options.go (line 2714), causing the core loop in src/core.go (line 403) to skip matching.
• Use it for external search workflows where tools like ripgrep, git, or ag handle the filtering, and fzf serves only as the UI layer.
• Enable dynamic toggling with enable-search and disable-search actions to switch between browse and filter modes during a session.
• Improves performance on massive datasets by avoiding fzf's memory-intensive indexing when not needed.

Frequently Asked Questions

What is the difference between --disabled and the old --phony flag?

There is no functional difference. The --disabled flag is the renamed version of --phony, introduced to make the option's purpose clearer to users. According to the changelog at line 2125, --phony was deprecated in favor of --disabled, but both set the same internal Phony option to true in src/options.go.

Can I use --disabled with --preview?

Yes, and this is one of the most powerful combinations. When using --disabled with --preview, the preview command can still access the {q} placeholder to show context-aware information, but the main list remains unfiltered. This is documented in ADVANCED.md lines 66-71, showing how to create preview-only workflows where the query updates the preview pane without shrinking the item list.

How do I toggle search on and off during a session?

Use the enable-search and disable-search actions bound to keys of your choice. For example, --bind "ctrl-s:enable-search" --bind "ctrl-d:disable-search" allows you to pause filtering to view the full list, then resume searching. These actions modify the internal paused state initialized from the Phony option in src/terminal.go (line 1066).

Does --disabled improve performance with large files?

Absolutely. When processing millions of lines, fzf's internal fuzzy matching algorithm requires significant memory to build its index and CPU to compute scores. By using --disabled, you bypass this entirely—the core loop in src/core.go (line 403) skips the matching phase, reducing fzf's footprint to that of a simple terminal UI. This is essential when using fzf as a frontend for high-performance external searchers like ripgrep or silver searcher.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}