Skip to content

Binary Modes

Ripgrep supports three distinct binary handling modes, controlled by the --binary and --text flags:

stateDiagram-v2
    [*] --> Auto: Default
    Auto --> SearchAndSuppress: --binary flag
    Auto --> AsText: --text/-a flag
    SearchAndSuppress --> AsText: --text overrides

    note right of Auto
        Explicit files: SearchAndSuppress
        Implicit files: Skip on NUL
    end note

    note right of SearchAndSuppress
        Search but warn on NUL
        NUL → newline conversion
    end note

    note right of AsText
        No binary detection
        Risk: terminal corruption
    end note

Figure: Binary mode selection and transitions based on command-line flags.

Auto Mode (Default)

The default mode automatically determines the binary handling strategy based on how the file is specified:

  • Explicit files (e.g., rg pattern file.bin): Uses SearchAndSuppress mode—the file is searched, but if binary data is detected, a warning is shown instead of the matches
  • Implicit files (e.g., rg pattern in a directory, or rg pattern -g '*.bin'): Quits searching immediately when binary data is detected (stops reading the file and moves to the next file, producing no output for that file—a silent skip)

Design Rationale

This dual behavior balances precision (don't waste time on binary files) with recall (if the user explicitly named a file, they probably want to search it). See Explicit vs Implicit Files for more details on this distinction.

flowchart LR
    Start[Search File] --> Check{File specification?}
    Check -->|Explicit - rg pattern file.bin| Explicit[Search and Suppress mode]
    Check -->|Implicit - rg pattern -g *.bin| Implicit[Auto skip mode]

    Explicit --> SearchE[Search file]
    SearchE --> NulE{"NUL byte
detected?"}
    NulE -->|Yes| WarnE["Show warning
Suppress matches"]
    NulE -->|No| MatchesE[Show matches]

    Implicit --> SearchI[Search file]
    SearchI --> NulI{"NUL byte
detected?"}
    NulI -->|Yes| SkipI[Skip file silently]
    NulI -->|No| MatchesI[Show matches]

    style Explicit fill:#e1f5ff
    style Implicit fill:#fff3e0
    style WarnE fill:#ffe0b2
    style SkipI fill:#f3e5f5

Figure: Auto mode decision flow showing different behavior for explicit vs implicit files.

SearchAndSuppress Mode

When you use the --binary flag, ripgrep will search binary files but suppress matches and emit warnings when NUL bytes are found:

rg --binary pattern  # (1)!
  1. Searches binary files but shows warnings instead of matches when NUL bytes are found

In this mode, NUL bytes are replaced with line terminators during searching.

Warning Message Format

When binary data is detected, ripgrep shows different messages depending on how the file was specified:

  • Explicit files (e.g., rg pattern file.bin): 
    binary file matches (found "\0" byte around offset N)
  • Implicit files searched from directories or globs: 
    file.bin: WARNING: stopped searching binary file after match (found "\0" byte around offset N)

Memory-Saving Heuristic

True binary data isn't line-oriented, so treating it as such without NUL-to-newline conversion could result in impractically large "lines" (imagine a 100MB binary file with no line breaks consuming all available memory).

AsText Mode

The --text (or -a) flag completely disables binary detection, treating all files as plain text:

rg --text pattern  # (1)!
rg -a pattern      # (2)!
  1. Force search binary files as text
  2. Short form of --text

Terminal Corruption Risk

This may print raw binary data to your terminal, including escape sequences that could corrupt your terminal display or cause unexpected behavior. Use with caution and consider piping to cat -v or similar if you need to inspect the output safely.

The --text flag overrides --binary if both are specified.

Performance Considerations

Binary detection has minimal performance impact:

  • Detection overhead: Extremely low—just a byte-by-byte scan during normal reading
  • Performance benefit: Can be significant by skipping binary files early, especially in recursive searches
  • Memory impact: The NUL-to-newline conversion in SearchAndSuppress mode prevents excessive memory usage from treating binary data as single giant lines

Choosing the Right Mode

When to use each mode:

Mode Use When Performance Profile
Auto (default) General-purpose searching Best balance: skips binaries but searches explicit files
--binary Need to know about binary matches Slightly slower: searches more files, but still stops early
--text Files incorrectly detected as binary Potentially slower: may search irrelevant data
Disabled (library) Complete control needed Fastest, but may produce garbage output

Edge Case: Early-Exit Flags

When using -l/--files-with-matches or --quiet, ripgrep stops searching immediately after finding the first match—before it might detect NUL bytes later in the file. This means binary files may be reported as matching. This is an accepted performance tradeoff.

However, --count requires scanning the entire file, so binary detection works correctly with that flag.