LESSPIPE.SH(1) User Commands LESSPIPE.SH(1)
NAME
lesspipe.sh - a filter for less
SYNOPSIS
lesspipe.sh [FILE[s]]...
DESCRIPTION
The aim of lesspipe.sh is to enhance the output of less. The choice of
the rules to be applied to modify the output is based on the file
contents. The file extension is respected only as a last resort.
Usually lesspipe.sh is called as an input filter to less.
With the help of that filter, less will display the uncompressed
contents of compressed (gzip, bzip2, compress, zstd, lz4, lzip, xz,
lzma, zlib or brotli) files. For files containing archives and
directories, a table of contents will be displayed (tar, ar, zip,
7-zip, rar, jar, cpio, rpm, deb, ms-cabinet, iso, dmg, appimage and
snap formats). Many other files will be 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 and
video) formats. This requires helper programs to be installed.
The filter can also be applied recursively to extract and display files
in archives on the fly. This works to a depth of 6, where applying a
decompression algorithm counts as a separate level.
If the file utility reports text with an encoding different from the
one used in the terminal, the text will be transformed using iconv into
the default encoding. 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 using the programs git, vim or mutt, they can be enabled to read
non-text files by using lesspipe.sh. That is described in the Wiki at
https://github.com/wofr06/lesspipe/wiki.
FILTER ACTIVATION
The filter is called from less provided that the environment variable
LESSOPEN is set properly. For ksh-like shells (bash, zsh), the 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. This can
even be used 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 is 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.
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 |-.
If commands within lesspipe.sh fail, error messages are sometimes
displayed; this is a considered buggy behavior and should be reported.
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. If the file name contains a colon, then an equal
sign should be used instead.
HTML, XML and Perl POD Files
Files in the HTML and Perl POD formats are always rendered. Sometimes,
however, the original contents of the file should be viewed instead. As
mentioned before, that can be achieved by appending a colon to the file
name. 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. 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.
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.
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
The lesspipe.sh filtering can be replaced or enhanced by a user-
defined program. Such a program has to be called either .lessfilter
(and be placed in the user's home directory) or lessfilter (and be
accessible from a directory mentioned in $PATH). It has to be
executable and must return exit code 0 if the filtering was done within
that script. Otherwise, a nonzero exit code means the filtering is left
to lesspipe.sh.
This mechanism can be used to add filtering for new formats or, for
example, to inhibit filtering for certain file types. A sample
.lessfilter could look as follows:
#!/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
Report bugs to <wp.friebel AT gmail DOT com> or open a github issue.
COPYRIGHT
Copyright (C) 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.
SEE ALSO
less(1)
A description of lesspipe.sh can also be found in the README contained
in the source code package
lesspipe.sh April 2026 LESSPIPE.SH(1)
lesspipe 2.28 - Generated Thu Sep 10 13:00:36 CDT 2026