--- name: "lesspipe" section: "1" platform: "linux" package: "lesspipe" version: "2.28-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/lesspipe" --- # lesspipe(1) a filter for less ## 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 \ or open a github issue.** ## 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.** ## SEE ALSO **[less(1)](/less/1.md)** **A description of lesspipe.sh** **can also be found in the README contained in the source code package**