lesspipe: a preprocessor that lets less read PDFs, archives and media

The pager becomes a file browser for things that are not text

lesspipe.sh is a preprocessor for less, and the project description puts it plainly: display more with less.

The motivation section names the four programs it is designed to improve. If you use the pager less in the command line, the version control system git, the text editor Vim, or the mail client mutt, then lesspipe.sh enables these programs to read non-text files such as PDFs, Microsoft or LibreOffice office documents, or even media files including JPG or PNG images and MP3 audio or video.

The word read is defined precisely, and that definition is the whole design. Read means either formatting and showing the contained text of a document or a tag in a media file, or showing sensible file information such as the length of a video. So an MP3 is not decoded into a player, it is reported on, and a PDF is reduced to its text.

The technical mechanism is the environment variable LESSOPEN. By setting it, less can be enhanced by external filters to become even more powerful, and most Linux distributions come already with a lesspipe.sh that covers the most common situations. The introduction is careful to note that the input filter described here is called lesspipe.sh, that it enables users to deeply inspect archives and display the contents of files in archives without having to unpack them first, and that this means file contents can be properly interpreted even if the files are compressed and contained in a hierarchy of archives, which the readme notes is often found in RPM or DEB archives containing source tarballs.

The script itself is a bash script that works as well as a zsh script, and it is easily extensible for new formats.

Format detection falls back through three signals

How the script decides what to do with a file is a small algorithm, and it is worth understanding because it explains the behaviour when detection goes wrong.

In most cases the decision is made on the output of the file --mime command, which returns the mime type. In some cases the mime type is too vague, and then the file command yielding a textual description is used, or the file suffix. As a last resort the file extension is consulted.

That is a cascade from most specific to least, and each step down is less reliable than the one before. A mime type can be generic, a textual description from file can be a sentence that has to be matched, and an extension is a convention rather than a fact about the content.

The consequence is that a file whose extension lies about its content will be handled by the wrong branch, and the documentation's own advice is worth repeating to yourself when something renders oddly: the format is being guessed, not negotiated.

The extraction itself is delegated. For the text and info extraction, lesspipe.sh depends on external tools, and the readme says many use cases are covered by an installation of LibreOffice and a common text browser such as lynx, pdftotext, and mediainfo or exiftool. That list is the real dependency footprint of the tool, and it is worth reading as a menu of what it can and cannot do: office documents and PDFs need LibreOffice and pdftotext, media metadata needs mediainfo or exiftool, and the text browser is what turns HTML into readable text.

A separate mechanism handles files with alternate character encodings, listed in the contents as the conversion of files with alternate character encoding, and the readme also notes that the file type is determined at each stage in extracting files from a hierarchy, which guarantees correct processing and display of the last file in the list.

LESSOPEN has to point at the right script

The activation is one environment variable, and the readme is fussy about the details because getting them wrong produces a silent failure.

To activate lesspipe.sh the environment variable LESSOPEN has to be defined in a specific way for sh like shells:

        LESSOPEN="|lesspipe.sh %s"; export LESSOPEN  # (sh like shells)

If lesspipe.sh is not in the UNIX search path, or if the wrong lesspipe.sh is found in the search path, then the full path to lesspipe.sh should be given in those commands and in the invocations below. The commands work only in the described manner if the file name is lesspipe.sh. If it is installed under a different name then calling it without an argument will work as a filter with LESSQUIET set and expecting input from STDIN.

That last detail is a genuine trap. The documentation, the man page and the distribution packaging all assume the name lesspipe.sh, and a renamed copy silently behaves differently.

There is a shortcut too. The command to set LESSOPEN can be displayed by calling lesspipe.sh without arguments, and this can be used to set LESSOPEN directly:

        eval "$(lesspipe.sh)"             # (bash) or
        lesspipe.sh | source /dev/stdin   # (zsh)

or the settings can be added to your shell startup files:

        lesspipe.sh >> ~/.bashrc        # (bash) and
        lesspipe.sh >> ~/.zshrc         # (zsh) and

Several Linux distributions do set LESSOPEN by default, and if the contents of the variable do not refer to this lesspipe.sh version it has to be redefined to get the functionality described.

For archives, the usage is a colon separated hierarchy, and because lesspipe.sh accepts only a single argument, a hierarchical list of file names has to be separated by a non-blank character. A colon is rarely found in file names, so it has been chosen as the separator. If a file name does contain at least one isolated colon, the equal sign can be used as an alternate separator character.

The commands are:

        less archive_file:contained_file

to view a file in an archive, and:

        less archive_file:contained_file: > extracted_file

to extract one. The trailing separator character matters and is easy to miss, because it ensures that the file is extracted in raw format and not modified by lesspipe. For extracting without less at all, the same thing works through the script directly:

        lesspipe.sh archive_file:contained_file: > extracted_file

Colouring, long lines and the completion helpers

Two of the readme's sections are about the output rather than the input, and both are the reasons you would install this over the lesspipe.sh your distribution already ships.

The first is colourising. The features cover syntax highlighting, a coloured directory listing, and a coloured listing of tar file contents, with the readme pointing to a sample terminal.css stylesheet and the termcolour and vimcolor directories in the repository for the highlighting choices, and a list of supported languages. The second is the display of long lines. By default less wraps long lines unless called with the option -S or --chop-long-lines, and that can be changed interactively by typing -S followed by ENTER when viewing files with long lines. The readme notes it is quite useful for tabular display of csv files with many columns, which is the case that makes people think a file is corrupt when it is not.

The third is the shell integration. Auxiliary programs are provided to enhance the TAB completion mechanism in bash and zsh shells and to help colorizing the filtered output, and the repository holds bash_completion and zsh_completion directories alongside a lesscomplete helper. Completion in a pager is a genuinely useful thing, because the completion candidates for a file inside an archive are the files in the archive.

There is also a section on displaying files with special characters in the file name, and one on calling less from standard input, plus a section on user defined filtering, which is the extension point for formats the script does not know about.

The repository layout matches this. There is lesspipe.sh itself, the man page lesspipe.1, an INSTALL file, a configure script, a ChangeLog, the archive_color, vimcolor and lesscomplete helper files, the two completion directories, german.txt, a test.sh with a tests/ directory, and a packaging/ directory for distribution packages. The primary language of the repository is recorded as Shell, and the licence is GPL-2.0 with a LICENSE file at the root.

An active fork of a script most distributions ship

The maintenance picture explains why this project exists as a separate effort rather than a patch to a distribution package.

The three most recent releases are v2.28 from 2026-09-08, titled V2.28 with improved text file handling, v2.27 from 2026-06-10, titled V 2.27 with better pem file display, and v2.26 from 2026-06-05, titled V 2.26 with better log file handling and fixes for color support. Three releases in three months, each one fixing a specific kind of file, which is the right pattern for a filter whose job is handling other people's file formats.

The repository is not archived, the default branch is named lesspipe rather than master, and the last push was on 2026-09-14, about five weeks before the current date. So the work is continuing, on a version line that is in the high twenties.

The fork relationship is worth being clear about, because the readme is careful about it. The script here is the input filter for less described in this repository, and the readme points out that most Linux distributions come already with a lesspipe.sh that covers the most common situations. Several distributions also set LESSOPEN by default. The note at the end of the usage section draws the conclusion: if the contents of the variable do not refer to this lesspipe.sh version, it has to be redefined.

That is the whole pitch. Your distribution's lesspipe.sh is adequate for common cases, and this one adds the formats and the colour that the distribution version does not handle, at the cost of being a separate thing to install and to point LESSOPEN at.

There is a bug report and proposal route through GitHub, and the author can be contacted by email at the address given. The project website is lesspipe.org, there is a zip file on GitHub for the latest version, and the development version can be cloned with git, which the readme gives as a single command.

Editorial conclusion

lesspipe suits a Unix user who works with PDFs, office documents, source tarballs and media and wants to inspect them from the pager rather than extracting them first, and it suits someone building a CI or release pipeline that needs to look inside packages. It does not suit a Windows user, and it does not remove the dependency on external extraction tools, since the text and information extraction still relies on LibreOffice, pdftotext and mediainfo or exiftool. Before installing, check that the tools for the formats you care about are present, and note that the script must be called lesspipe.sh or the commands in the documentation will not work as written.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. wofr06/lesspipe on GitHub