bat User Guide

A cat(1) clone with syntax highlighting, git integration, and automatic paging. bat displays files with beautiful syntax coloring, shows git modifications in the sidebar, and automatically pipes output through a pager when it exceeds the terminal height.

Quick Start

View a file with syntax highlighting

bat README.md

View multiple files

bat src/*.rs

Pipe from stdin with automatic language detection

curl -s https://sh.rustup.rs | bat

Pipe from stdin with explicit language

yaml2json .travis.yml | json_pp | bat -l json

Show non-printable characters

bat -A /etc/hosts

Use as a drop-in cat replacement

# Create a new file
bat > note.md

# Concatenate files
bat header.md content.md footer.md > document.md

# Show line numbers only
bat -n main.rs

# Interleave file and stdin
bat f - g

Tip

When bat detects a non-interactive terminal (piped output), it automatically behaves like cat -- outputting plain text without syntax highlighting or decorations.

Installation

Package Managers

Ubuntu / Debian

sudo apt install bat

Note

On Debian and Ubuntu, the executable is installed as batcat due to a naming conflict with another package. Create a symlink to use the bat name:

mkdir -p ~/.local/bin
ln -s /usr/bin/batcat ~/.local/bin/bat

Alternatively, install the latest .deb package from the releases page:

sudo dpkg -i bat_0.26.1_amd64.deb

Arch Linux

pacman -S bat

Fedora

dnf install bat

Alpine Linux

apk add bat

Gentoo Linux

emerge sys-apps/bat

Void Linux

xbps-install -S bat

openSUSE

zypper install bat

FreeBSD

pkg install bat

OpenBSD

pkg_add bat

Termux (Android)

pkg install bat

macOS

Homebrew

brew install bat

MacPorts

port install bat

Windows

Important

Windows requires Visual C++ Redistributable to be installed.

WinGet

winget install sharkdp.bat

Chocolatey

choco install bat

Scoop

scoop install bat

Nix

nix-env -i bat

Flox

flox install bat

Pre-built Binaries

Download pre-built binaries for your platform from the GitHub releases page. Statically-linked binaries are available in archives with musl in the filename.

From Source

Requires Rust 1.88 or newer.

cargo install --locked bat

Note

Building from source with cargo install does not install supplementary files such as man pages or shell completion scripts. These are generated during the build and can be found in the cargo target directory under build/. Shell completions can also be generated at runtime with bat --completion <shell>.

Configuration

Configuration File

bat reads configuration from a file containing command-line arguments (one per line). Lines starting with # are comments.

Finding the configuration file path

bat --config-file

Default locations by platform:

Generating a default configuration file

bat --generate-config-file

Example configuration file

# Set the theme
--theme="TwoDark"

# Show line numbers, Git changes, and file header (no grid)
--style="numbers,changes,header"

# Use italics in the terminal (not supported on all terminals)
--italic-text=always

# Use C++ syntax for Arduino .ino files
--map-syntax "*.ino:C++"

# Use "Git Ignore" syntax for .ignore files
--map-syntax ".ignore:Git Ignore"

Overriding the config file location

Set the BAT_CONFIG_PATH environment variable:

export BAT_CONFIG_PATH="/path/to/bat.conf"

Configuration Directory

The configuration directory holds custom syntaxes and themes. View the path:

bat --config-dir

Override with BAT_CONFIG_DIR:

export BAT_CONFIG_DIR="/path/to/bat-config"

Environment Variables

Core Usage

Syntax Highlighting

bat automatically detects file types and applies syntax highlighting. The detection follows this order:

1. Explicit mappings (--map-syntax rules)
2. File name (exact file name matches)
3. Hidden file extensions (e.g., .bashrc matched as Bash)
4. File extension (e.g., .rs for Rust)
5. First line content (shebang lines like #!/bin/bash)

Specifying a language manually

bat --language rust main.rs
bat -l json data.txt

Listing available languages

bat --list-languages

Themes

Listing available themes

bat --list-themes

Setting a theme

# Command-line flag
bat --theme=TwoDark file.rs

# Environment variable (permanent)
export BAT_THEME="TwoDark"

Built-in Themes (27 total)

8-Bit Color Themes

Three themes use 8-bit (or fewer) ANSI colors instead of true color. These adapt to your terminal color scheme:

• ansi -- Uses 3-bit colors (8 basic colors). Works on any terminal.
• base16 -- Uses 4-bit colors (basic + bright). Designed for base16 terminal themes.
• base16-256 -- Uses 8-bit colors. Designed specifically for base16-shell users.

Warning

Do not use base16-256 just because you have a 256-color terminal. It is specifically designed for use with base16-shell.

Previewing themes with fzf

bat --list-themes | fzf --preview="bat --theme={} --color=always /path/to/file"

macOS Dark/Light Mode Auto-Switching

alias cat="bat --theme=\$(defaults read -globalDomain AppleInterfaceStyle &> /dev/null && echo default || echo GitHub)"

Adding Custom Themes

mkdir -p "$(bat --config-dir)/themes"
cd "$(bat --config-dir)/themes"

# Download a .tmTheme file
git clone https://github.com/greggb/sublime-snazzy

# Rebuild the binary cache
bat cache --build

Verify with bat --list-themes.

Output Styles

Control which decorations bat displays with --style.

Style Components

Combining style components

# Show only line numbers and git changes
bat --style=numbers,changes file.rs

# Show everything
bat --style=full file.rs

# Disable a specific component with a minus prefix
bat --style=default,-grid file.rs

Setting a permanent style

export BAT_STYLE="numbers,changes,header"

Plain output (-p / --plain)

Using -p once disables decorations. Using -pp also disables paging. Using -ppp also disables ANSI styling (completely plain output like cat).

bat -p file.rs       # No decorations
bat -pp file.rs      # No decorations, no paging
bat -ppp file.rs     # No decorations, no paging, no colors

Line Ranges

Display only specific lines with --line-range / -r.

Examples

# Show lines 40 through 50
bat --line-range 40:50 file.rs

# Show first 20 lines
bat -r :20 file.rs

# Show from line 100 to end
bat -r 100: file.rs

# Show line 35 with 5 lines of context
bat -r 35::5 file.rs

# Multiple ranges
bat -r 1:5 -r 20:25 file.rs

Line Highlighting

Highlight specific lines with --highlight-line / -H:

bat --highlight-line 42 file.rs
bat -H 30:40 file.rs

Paging

bat automatically pipes output through a pager when it exceeds the terminal height.

Pager selection order

1. --pager command-line option (or config file)
2. BAT_PAGER environment variable
3. PAGER environment variable
4. less (default)

Paging modes

bat --paging=always file.rs    # Always use a pager
bat --paging=auto file.rs      # Pager only if output exceeds terminal (default)
bat --paging=never file.rs     # Never use a pager

Custom pager

export BAT_PAGER="less -RF"

Built-in pager

bat includes a built-in pager (powered by the minus crate) that can be used when less is not available:

bat --pager=builtin file.rs

Note

When less is the pager and no custom arguments are specified, bat automatically passes these flags: -R (ANSI color support), -F (quit if content fits one screen), -K (quit on interrupt). For less versions older than 530, --no-init is also added to fix a --quit-if-one-screen bug. If PAGER is set to more, most, or bat itself, bat silently substitutes less to avoid issues.

Color Output

bat --color=always file.rs   # Force color output (useful in pipes)
bat --color=never file.rs    # Disable color output
bat --color=auto file.rs     # Auto-detect (default)

Non-printable Characters

Show non-printable characters with -A / --show-all:

bat -A file.txt

Non-printable characters are displayed using Unicode notation by default:

Caret notation is also available via --nonprintable-notation=caret:

bat -A --nonprintable-notation=caret file.txt

Wrapping

bat --wrap=auto file.rs       # Wrap at terminal width (default)
bat --wrap=never file.rs      # No wrapping (enables horizontal scrolling in less)
bat --wrap=character file.rs  # Wrap at character boundaries

When wrapping is set to never and the pager is less, bat automatically passes -S (chop long lines) so you can scroll horizontally.

Tab Width

bat expands tabs to spaces (default: 4 spaces). This is done before output reaches the pager.

bat --tabs=8 file.txt         # 8-space tabs
bat --tabs=0 file.txt         # Pass raw tabs to the pager

Note

Setting tab width via the pager (e.g., less -x8) has no effect because bat expands tabs before the pager sees them. Use --tabs=0 to let the pager handle tab expansion.

Diff Mode

Show only modified lines (compared to the git index):

bat --diff file.rs
bat -d file.rs

ANSI Escape Sequence Handling

bat --strip-ansi=auto file.txt     # Strip if not plain text (default)
bat --strip-ansi=always file.txt   # Always strip ANSI sequences
bat --strip-ansi=never file.txt    # Never strip (pass through)

Squeezing Empty Lines

Limit consecutive empty lines:

bat --squeeze-limit=1 file.txt   # Max 1 consecutive empty line

Common Tasks

Syntax Mapping

Map file patterns to specific syntax definitions:

# All .conf files use INI syntax
bat --map-syntax='*.conf:INI' myfile.conf

# Exact file name match
bat --map-syntax='.ignore:Git Ignore' .ignore

# Path-based mapping
bat --map-syntax='/etc/apache2/**/*.conf:Apache Conf' /etc/apache2/sites-available/default.conf

Put these in your config file for permanent effect.

Adding Custom Syntaxes

bat uses Sublime Text .sublime-syntax files via the syntect library.

# Create the syntaxes directory
mkdir -p "$(bat --config-dir)/syntaxes"
cd "$(bat --config-dir)/syntaxes"

# Add a syntax definition
git clone https://github.com/tellnobody1/sublime-purescript-syntax

# Rebuild the cache
bat cache --build

# Verify
bat --list-languages

To revert to defaults:

bat cache --clear

Cache Management

bat cache --build     # Rebuild syntax/theme cache from config dir
bat cache --clear     # Remove custom cache, revert to built-in assets

The cache directory location:

bat --cache-dir

Integration with Other Tools

fzf (Fuzzy Finder)

fzf --preview "bat --color=always --style=numbers --line-range=:500 {}"

find / fd

find . -name '*.rs' -exec bat {} +
fd --extension rs -X bat

ripgrep

Use batgrep from bat-extras:

batgrep needle src/

tail -f (Live log monitoring)

tail -f /var/log/syslog | bat --paging=never -l log

Important

Paging must be disabled (--paging=never) when reading from a continuous stream. Language must be specified manually since bat cannot auto-detect from a pipe.

git show

git show v0.6.0:src/main.rs | bat -l rs

git diff

batdiff() {
    git diff --name-only --relative --diff-filter=d -z | xargs -0 bat --diff
}

For full git diff support, see delta.

man pages

export MANPAGER="sh -c 'col -bx | bat -l man -p'"
man 2 select

Note

Replace bat with batcat on Debian/Ubuntu. You may also need MANROFFOPT="-c" if you experience formatting issues. This does not work with the Mandoc implementation of man. For a ready-made solution, use batman from bat-extras.

Highlighting --help output

alias bathelp='bat --plain --language=help'
help() {
    "$@" --help 2>&1 | bathelp
}

Usage:

help cp
help git commit

xclip (Clipboard)

bat main.cpp | xclip

bat auto-detects piped output and strips decorations.

prettier / shfmt / rustfmt

Use prettybat from bat-extras to format and display code.

LESSOPEN Preprocessing

When the lessopen feature is enabled (default in standard builds), bat supports the LESSOPEN and LESSCLOSE environment variables for input preprocessing.

LESSOPEN prefix modes:

Example:

export LESSOPEN="|batpipe %s"

Using bat as a Library

bat exposes a Rust library API via the PrettyPrinter struct:

use bat::PrettyPrinter;

PrettyPrinter::new()
    .input_from_bytes(b"<span>Hello world!</span>\n")
    .language("html")
    .print()
    .unwrap();

Tip

When depending on bat as a library, you must enable either the regex-onig or regex-fancy feature.

Library Features

The PrettyPrinter API supports:

• File, stdin, byte, and custom reader inputs
• Language selection
• Theme selection
• Style components (header, line numbers, grid, rule, snip, VCS markers)
• Line ranges and line highlighting
• Color output control
• True color support
• Tab width
• Wrapping mode
• Paging mode and custom pager
• ANSI stripping
• Syntax mapping
• Non-printable character display

Workflows

Previewing Code in a Git Repository

# View a file with git change markers
bat --style=numbers,changes src/main.rs

# View only modified lines
bat --diff src/main.rs

# View a specific commit's version of a file
git show HEAD~5:src/main.rs | bat -l rs

Reading Log Files

# Static log file with syntax highlighting
bat -l log /var/log/syslog

# Live tail with highlighting
tail -f /var/log/app.log | bat --paging=never -l log

Code Review Workflow

# List changed files, preview each
git diff --name-only | xargs bat --diff

# View specific line ranges around a known issue
bat -r 100:150 -H 120:130 src/handler.rs

Scripting with bat

When used in scripts, bat detects non-interactive terminals and acts like cat:

# bat in a script -- outputs plain text
CONTENT=$(bat --style=plain --color=never --paging=never input.txt)

# Force colored output in pipes
bat --color=always file.rs | head -20

Converting File Encodings

bat natively supports UTF-8 and UTF-16. For other encodings, convert first:

iconv -f ISO-8859-1 -t UTF-8 legacy-file.php | bat -l php

Advanced Usage

Binary File Detection

bat automatically detects binary files by inspecting the first bytes of input. When binary content is detected, bat prints a notice and does not display the content. This prevents garbled terminal output.

Italics

Some terminal emulators support italic text rendering:

bat --italic-text=always file.rs

Shell Completions

Generate shell completion scripts at runtime:

bat --completion bash > bat.bash
bat --completion zsh > _bat
bat --completion fish > bat.fish
bat --completion powershell > bat.ps1

Acknowledgements

View the license acknowledgements for bundled syntaxes and themes:

bat --acknowledgements

How It Works

Syntax Highlighting Engine

bat uses the syntect library, which reads Sublime Text .sublime-syntax definitions and .tmTheme theme files. Syntect compiles syntax definitions into a binary cache for fast loading.

Paging Architecture

When paging is enabled, bat spawns the pager as a child process and pipes its output to the pager's stdin. The pager selection follows a priority chain: --pager flag > BAT_PAGER env > PAGER env > less default.

For the less pager, bat automatically configures optimal flags (-R, -F, -K) unless custom arguments are provided via BAT_PAGER or --pager. Arguments from the generic PAGER variable are replaced with bat's defaults to ensure correct ANSI color handling.

Git Integration

bat uses the git2 library (libgit2 bindings) to detect file modifications. It compares the working tree version against the index to generate line-level change markers (added, modified, removed). This is controlled by the git cargo feature and can be disabled at compile time.

Color Scheme Detection

bat can auto-detect your terminal's color scheme (dark or light background) using the terminal-colorsaurus library. This enables the --theme=auto behavior, which selects an appropriate theme based on your terminal background.

Troubleshooting

Terminal and Color Issues

Colors look wrong or missing

Symptoms: Output appears in limited colors or monochrome.

Solution: Ensure your terminal supports and advertises true color:

echo $COLORTERM
# Should output: truecolor or 24bit

If unset, add to your shell profile:

export COLORTERM=truecolor

Colors not showing in pipes

Cause: bat disables color when it detects non-interactive output.

Solution:

bat --color=always file.rs | less -R

Line numbers and grid are hard to see

Solution: Switch to OneHalfDark or OneHalfLight theme, which uses brighter grid colors:

bat --theme=OneHalfDark file.rs

Pager Issues

Output disappears or flashes briefly

Cause: The pager quits before you can read the output (less -F flag behavior with short content).

Solution: This is expected -- less exits immediately if the content fits on one screen.

Mouse wheel scrolling not working

Cause: On older less versions (< 530), bat passes --no-init which disables mouse support.

Solution: Upgrade less to version 530 or newer. Alternatively, set:

export BAT_PAGER="less -R"

This disables --quit-if-one-screen but enables mouse wheel scrolling.

Pager not found

Symptoms: [bat warning]: Pager 'xyz' not found, outputting to stdout instead

Solution: Install the pager or change BAT_PAGER:

export BAT_PAGER="less"

bat set as its own pager causes infinite recursion

bat detects this and shows an error: InvalidPagerValueBat. Set a different pager.

PAGER set to more or most

bat silently substitutes less when PAGER is set to more or most (which do not support ANSI colors). This only applies to the generic PAGER variable -- BAT_PAGER and --pager are always respected.

File Issues

Unknown syntax / no highlighting

Cause: bat cannot detect the file type.

Solutions:

# Specify language manually
bat -l python script

# Add a permanent mapping
bat --map-syntax='*.custom:Python' script.custom

# Or in config file
echo '--map-syntax "*.custom:Python"' >> "$(bat --config-file)"

UTF-16 files display correctly but other encodings do not

bat supports UTF-8 and UTF-16 natively. For other encodings, pre-convert:

iconv -f ISO-8859-1 -t UTF-8 file.txt | bat

Binary file detected when file is text

bat inspects the first bytes for null characters and other binary indicators. If a text file is misidentified, force text display:

bat --show-all file.txt

File path errors on Cygwin

bat does not natively support Cygwin-style paths (/cygdrive/c/...). Add this wrapper to .bash_profile:

bat() {
    local index
    local args=("$@")
    for index in $(seq 0 ${#args[@]}) ; do
        case "${args[index]}" in
        -*) continue;;
        *)  [ -e "${args[index]}" ] && args[index]="$(cygpath --windows "${args[index]}")";;
        esac
    done
    command bat "${args[@]}"
}

Windows-Specific Issues

Colors not working in Windows terminal

Windows 10 v1511+ supports colors in Command Prompt and PowerShell natively. For older versions, use Cmder with ConEmu.

Git/MSYS less does not display colors correctly

The Git for Windows and MSYS2 versions of less have color handling issues. Either:

# Disable paging entirely
bat --paging=never file.rs

# Or set an empty pager
export BAT_PAGER=""

Visual C++ runtime error on startup

Install the Visual C++ Redistributable.

Theme and Syntax Issues

--list-themes not showing custom themes

Rebuild the cache after adding themes:

bat cache --build

Custom syntax/theme not working after update

After updating bat, rebuild the cache:

bat cache --build

To start fresh:

bat cache --clear
bat cache --build

--theme auto not selecting the right theme (#3641)

If auto-detection picks the wrong theme for your terminal background, set BAT_THEME explicitly:

export BAT_THEME="GitHub"  # for light backgrounds
export BAT_THEME="TwoDark" # for dark backgrounds

Performance Issues

Slow on very large files

Use line ranges to limit output:

bat -r :500 large-file.log

Or disable paging and decorations:

bat -pp large-file.log

Known Issues

FAQ

General

Q: What is bat? A: bat is a cat(1) replacement written in Rust that adds syntax highlighting, git integration, line numbers, and automatic paging.

Q: What version is this guide for? A: bat v0.26.1.

Q: What license is bat under? A: Dual-licensed under MIT and Apache 2.0 (your choice).

Q: Does bat replace cat? A: bat can be used as a drop-in replacement. When piped or in non-interactive mode, it behaves like cat. Many users alias cat to bat.

Q: How do I alias cat to bat? A: Add to your shell profile:

alias cat='bat --paging=never'

Q: What platforms does bat support? A: Linux, macOS, Windows, FreeBSD, OpenBSD, and Android (Termux). Pre-built binaries are available for x86_64, aarch64, and other architectures.

Q: Is there a Docker image for bat? A: There is no official Docker image (#3633).

Syntax and Themes

Q: How many languages does bat support? A: bat ships with syntax definitions for over 200 languages and file formats, inherited from Sublime Text.

Q: Can I add my own syntax definitions? A: Yes. Place .sublime-syntax files in $(bat --config-dir)/syntaxes/ and run bat cache --build.

Q: Can I add my own themes? A: Yes. Place .tmTheme files in $(bat --config-dir)/themes/ and run bat cache --build.

Q: Which theme should I use for a light terminal? A: GitHub, OneHalfLight, Solarized (light), Catppuccin Latte, or gruvbox-light.

Q: Which theme should I use for a dark terminal? A: TwoDark, Dracula, Nord, OneHalfDark, Catppuccin Mocha, or the default theme.

Q: What is the difference between ansi, base16, and base16-256 themes? A: ansi uses 3-bit colors (8 basic), base16 uses 4-bit colors (16 including bright), base16-256 remaps some colors to 8-bit values for base16-shell compatibility. Only use base16-256 if you use base16-shell.

Q: How do I request a new built-in syntax? A: Open a syntax request on GitHub.

Paging

Q: How do I disable paging? A: Use --paging=never or set BAT_PAGER="".

Q: Can I use bat without less installed? A: Yes. Without less, bat outputs directly to stdout. You can also use the built-in pager with --pager=builtin.

Q: Why does bat override my PAGER settings for less? A: When the pager comes from the generic PAGER variable (not BAT_PAGER), bat replaces the arguments with its own defaults (-RFK) to ensure ANSI color support. Use BAT_PAGER for full control.

Q: How do I pass custom arguments to less? A: Set BAT_PAGER="less -RF --mouse" or use --pager="less -RF" in your config file.

Configuration

Q: Where is my config file? A: Run bat --config-file to see the path.

Q: What format is the config file? A: One command-line argument per line. Lines starting with # are comments.

Q: Can I use different configs for different projects? A: Set BAT_CONFIG_PATH to a project-specific config file.

Q: How do I reset bat to defaults? A: Delete the config file and run bat cache --clear.

Git Integration

Q: What do the sidebar markers mean? A: + = added line, ~ = modified line, - = removed line (shown at the position where the deletion occurred).

Q: Can I disable git markers? A: Use --style without changes:

bat --style=numbers file.rs

Q: Git markers not showing up? A: The file must be in a git repository, and the git feature must be compiled in (it is by default).

Encoding

Q: What file encodings does bat support? A: UTF-8 and UTF-16 natively. Other encodings must be pre-converted with iconv.

Q: How does bat detect binary files? A: bat inspects the initial bytes using the content_inspector crate. Files with null bytes or other binary indicators are flagged.

Command-Line Reference

Synopsis

bat [OPTIONS] [FILE]...
bat cache [CACHE-OPTIONS]

Primary Options

Cache Subcommand

bat-extras

The bat-extras project provides companion tools: