LESSPIPE.SH(1)

💖 NAME 💖

lesspipe.sh — a filter for less ✨

(it's from LESSPIPE.SH(1), User Commands — that's the official lil badge it wears, but you can just call it by its name, bestie 💅)

---

📜 SYNOPSIS 📜

lesspipe.sh [FILE[s]]...

---

🌸 DESCRIPTION 🌸

okay so the whole vibe of lesspipe.sh is: it makes less eat better. That's it. That's the dream. 🫶

The rules it uses to decide how to dress up your output are based on the file contents themselves. The file extension? Only respected as an absolute last resort, like the final backup plan when nothing else worked. Usually lesspipe.sh gets called as an input filter for less.

With this filter in the mix, less will show you the uncompressed contents of compressed files — and the list is giving: gzip, bzip2, compress, zstd, lz4, lzip, xz, lzma, zlib, brotli. Obsessed. 😌

For files containing archives and directories, you get a table of contents instead of chaos: tar, ar, zip, 7-zip, rar, jar, cpio, rpm, deb, ms-cabinet, iso, dmg, appimage, snap. 👑

And many other files get reformatted for display — this includes pdf, dvi, markdown, Office (MS and OpenOffice) suite formats, NetCDF, matlab, device tree blob, html, xml, and media (image, audio, video) formats. ⭐

heads up bestie: this whole situation requires helper programs to actually be installed. no helpers, no glow-up. 💀

The filter can also be applied recursively, extracting and displaying files inside archives on the fly. It works to a depth of 6, and applying a decompression algorithm counts as a separate level. (yes, layered. like a cute little parfait. 🍓)

If the file utility reports text with an encoding different from the one used in the terminal, the text gets transformed using iconv into the default encoding. Fair warning though: this assumes that the file command gets the file encoding right, which can be wrong in some situations 😭. An appended colon to the file name suppresses the conversion.

When you're using the programs git, vim or mutt, they can be enabled to read non-text files by using lesspipe.sh. That's described in the Wiki at https://github.com/wofr06/lesspipe/wiki 📚

---

🔥 FILTER ACTIVATION 🔥

The filter gets called from less provided that the environment variable LESSOPEN is set properly. For ksh-like shells (bash, zsh), this command:

LESSOPEN="|lesspipe.sh %s"; export LESSOPEN

activates the filter for less. Use the fully qualified path if lesspipe.sh is not in the search path. 💅

The command to set LESSOPEN can also be displayed by calling lesspipe.sh without arguments. And you can even use that to set LESSOPEN directly:

eval `lesspipe.sh`

(bash) or

lesspipe.sh | source /dev/stdin

(zsh)

⚠️ the above commands work only as described if the file name is lesspipe.sh. If it's installed under a different name, calling it without an argument will work as a filter with LESSQUIET set and expect input from STDIN.

Having set the environment variable as described above, less will then display textual information for a wide range of file formats. slay. 🌈

The filter is normally not called if input is piped to less, as in:

cat somefile | less

As described in the man page of less, filtering in a pipe can however be forced by starting LESSOPEN with the characters |-. noted 🎀

🐛 if commands within lesspipe.sh fail, error messages are sometimes displayed; this is a considered buggy behavior and should be reported. pls report it, bestie, we're not gatekeeping bugs.

To suppress informal messages in the first line of the filter output, the environment variable LESSQUIET can be set to a nonempty value. 🤫

To disengage the filter temporarily, a colon can be appended to the file name. If the output was colorful, then the colon only disables the colorizer command. A second colon may then be required to display the original content. And if the file name contains a colon, then an equal sign should be used instead. 😭 yes this is a lot. breathe.

---

🧚 HTML, XML and Perl POD Files 🧚

Files in the HTML and Perl POD formats are always rendered. Sometimes, however, you want to see the original contents of the file instead. As mentioned before, that can be achieved by appending a colon to the file name. And if the correct file type (html, pod) follows, the output can be colorized (see also the section below). ✨

Example: less index.html:html

If the xmq binary is installed, XML is rendered differently, so that the XML structure is easier to recognize. A similar display for HTML contents using xmq is achieved by appending a colon to the file name. To get the original HTML file contents, two colons are required in this case. 💀

The color scheme used is for a light background. To select the dark color scheme the ENV variable XMQ_THEME has to be set to the value dark. 🌙

---

🌈 OUTPUT COLORIZATION 🌈

The filter is able to do syntax highlighting for a wide variety of file types. It is not always wanted and can slow down the file display considerably. So therefore, an ENV variable LESS_MAXSIZE_COLOR (default: 200000) has been introduced — larger files do not get colorized. 🛑

If installed, nvimpager is used to colorize the output. If not, bat/batcat, pygmentize, e2ansi-cat, source-highlight, vimcolor and code2color are tried in turn. For bat/batcat, the theme is set to ansi and the style is set to plain, which comes closer to the unfiltered output of less. These settings can be changed in ~/.config/bat/config or by the environment variables BAT_STYLE and BAT_THEME. 🎀

The contents of log files can be colorized if the tspin program is installed and the string ":log" is appended to the file name or the file extension is "log". 🪵

Among the colorizers, a preferred one can be forced by setting the environment variable LESSCOLORIZER to the name of the colorizer. For pygmentize and bat/batcat, restricted option settings are allowed as follows:

LESSCOLORIZER='pygmentize -O style=foo' # -P allowed as well
LESSCOLORIZER='bat --style=foo --theme=bar' # default: theme=ansi, style=plain

Syntax highlighting is activated if the environment variable LESS exists and contains the option -R, or if less is called with this option. This guarantees that escape sequences are converted into colors and do not garble the display. 🌈

⚠️ using the option -r is not recommended, as the screen layout may be wrong if long lines are in the output. don't do it. i'm serious. 🙈

Syntax highlighting can be switched off by appending a colon after the file name if the output was colorful. If the wrong language was chosen for syntax highlighting, another one can be forced by appending a colon and a suffix to the file name. The list of suffixes and supported languages can be printed using the following colorizer commands:

bat --list-languages
batcat --list-languages
pygmentize -L lexers
M-x -mode [TAB] within emacs
source-highlight --lang-list
code2color -h
vimcolor -L (both for vimcolor and nvimpager)

In a pipe, that method cannot be used. As a workaround, a last argument can be added that is inspected by lesspipe.sh. A single colon (disengage filter) or :extension (force language) is possible, as in:

command that generates C code | less - :c

When the conditions for syntax highlighting are met, directory listings and listings of tar file contents are colorized as well. 💅

As less is used as a default browser in other programs (e.g. man, git, and perldoc), lesspipe.sh may be engaged and alter the output of those programs. 👀

---

👑 WATCHING GROWING FILES 👑

For all plain text files not recognized as log files, a colorizer is tried nevertheless — as it sometimes can detect the correct file type and color the file aproppriately. This does however destroy the abilty to watch growing files using the F command within less. 😭

To retain the ability to watch growing files without the .log extension, or when the log file colorizer tspin was called for log files, a single colon has to be given to the less call as the second argument, as in:

less /var/log/syslog :

It can also be achieved by listing such files in a file .lessignore in the users home directory. The entries are fully specified path names or contain globbing characters. Such a file could look as follows:

syslog
*/syslog
*.syslog

This would allow watching growing files with the name syslog, all syslog files in arbitrary directories and all files with the ending .syslog. 🌱

---

🦋 ADVANCED USAGE 🦋

This version of lesspipe.sh allows you to view individual files contained in a file archive, which itself may even be contained in another archive. inception core. 🌀

The notation for viewing files in multifile archives is:

less archive_file:contained_file

or even:

less super_archive:archive_file:contained_file

To display or extract the last file in the chain in raw format, a colon (:) has to be appended to the file name. If it contains a colon, then the alternate separator character equal sign (=) has to be used. To extract archives or compressed files, a second colon or equal sign may be required. 😮‍💨

Again, this method of extracting and displaying files does not work if less is called in an output pipe and LESSOPEN starts with the |- characters. As already for syntax highlighting, the solution is to use a second argument that starts with a colon. Then the above command would be written as:

cat super_archive | less - :archive:contained_file

---

🎀 COMPLETING MECHANISM FOR ARCHIVE CONTENTS 🎀

With the provided lesscomplete file (for zsh and bash) and the _less (for zsh) and less (for bash) files generated during installation, tab completion for files in archives can be accomplished. ✨

Entering a colon (:) or an equal sign (=) after an archive file name and then pressing the tab key triggers the completion mechanism. This also works in chained archives. The files required for the completion algorithm are installed in directories according to the choices made during the installation (configure script). 🛠️

The file lesscomplete has to be in one of the directories listed in $PATH and the function _less for zsh in a directory listed by $fpath. The file less with completion instructions for bash has to be sourced within a bash initialization script, e.g. in ~/.bashrc. New directories such as ~/scripts and ~/.fpath (for zsh) can be added using the commands:

PATH=~/scripts:$PATH # (lesspipe.sh, less) fpath=(~/.fpath
$fpath) # (_less, zsh only)

In zsh, compinit has to be called and the menucomplete option has to be set if it has not already been done. That can be achieved with the commands:

autoload compinit
compinit -Uz
setopt menucomplete

In bash, bash-completion (usually a package with that name) has to be installed. 💅

✨ USER DEFINED FILTERING ✨

okay so bestie, plot twist: you can replace the lesspipe.sh filtering, or just level it up, with your very own program 💅

Your lil custom script has to be called one of these two things:

• .lessfilter — and it lives in your home directory 🏠
• lessfilter — and it's reachable from some directory that's in $PATH 🌈

It has to be executable, no cap, and it must return exit code 0 if the filtering actually got done inside that script. If it returns a nonzero exit code instead? That means the filtering is handed off to lesspipe.sh. So it's giving "you handle this one, I'm clocking out" 😭✨

---

This whole mechanism is lowkey iconic for two reasons: you can add filtering for brand new formats, or — and this is the fun part — you can block filtering for certain file types when you just don't want it 🙈

A sample .lessfilter could look exactly like this:

#!/usr/bin/env bash
case $1 in
*.md|*.MD|*.mkd|*.markdown|*.rst)
# if the Python module rich.markdown is not found then
# the exit code is nonzero and lesspipe.sh is called
python3 -m rich.markdown -c $1 ;;
*.html|*.htm)
# call your favorite HTML beautifier, cat -b is just a boring example
cat -b $1 ;;
*)
exit 1;;
esac

---

👑 AUTHOR 👑

Wolfgang Friebel

🐛 REPORTING BUGS 🐛

Found a bug? Spill the tea ☕ report it to <wp.friebel AT gmail DOT com> or open a github issue, fr fr.

📜 COPYRIGHT 📜

Copyright © 2005-2026 Wolfgang Friebel

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

bestie this is the important one: no warranty, none, not even the MERCHANTABILITY kind or the FITNESS FOR A PARTICULAR PURPOSE kind. it's free software and you get it as-is 💀

🔗 SEE ALSO 🔗

• less(1)

A description of lesspipe.sh can also be found in the README contained in the source code package 📦

---

that's the whole page babes — lesspipe.sh, April 2026, and it's all living in section LESSPIPE.SH(1) 🫶 go forth and pipe everything, you absolute icon 🌸✨🎀