ctpv

File previewer for a terminal

ctpv is a file previewer utility for a terminal.

It was made with integration into lf file manager in mind, but I believe that it can be easily integrated into other programs as well.

It supports previews for source code, archives, PDF files, images, videos, etc. See Previews for more info.

Image previews are powered by one of these programs:

Überzug (X11 only)
Chafa (X11 and Wayland)
Kitty terminal

ctpv is a remake of an awesome program named stpv. stpv did everything I wanted, except it was a bit sluggish because it was written in POSIX shell. ctpv is written in C and is an attempt to make a faster version of stpv with a few new features.

Previews

Previewing each file type requires specific programs installed on a system. If a program is not found on the system, ctpv will try to use another one. Only one program is required for each file type. For example, you only need either elinks, lynx or w3m installed on your system to view HTML files.

File types	Programs
any	exiftool cat
archive	atool
audio	ffmpegthumbnailer ffmpeg
diff	colordiff delta diff-so-fancy
directory	ls
font	fontimage
gpg-encrypted	gpg
html	elinks lynx w3m
image	ueberzug chafa
json	jq
markdown	glow mdcat
office	libreoffice
pdf	pdftoppm
svg	convert
text	bat cat highlight source-highlight
torrent	transmission-show
video	ffmpegthumbnailer

Installation

Manual

If you are building from source, make sure to install these libraries! Depending on your system, you probably will also need "devel" versions of the same libraries.

libcrypto
libmagic

Install:

git clone https://github.com/NikitaIvanovV/ctpv
cd ctpv
make
sudo make install

Uninstall:

sudo make uninstall

AUR

If you are an Arch Linux user, you can install ctpv-git AUR package.

yay -S ctpv-git

MacPorts

With MacPorts, you can install the ctpv package.

sudo port install ctpv

Homebrew

With Homebrew, you can install the ctpv package.

brew install ctpv

Nix

Nix package

nix-env -ivf cptv
nix profile install nixpkgs#cptv # with flakes enabled

NixOS and HomeManager

If you don't need to call it directly and just want to use it through lf:

programs.lf = {
  previewer = {
    keybinding = "i";
    source = "${pkgs.ctpv}/bin/ctpv";
  };
  extraConfig = ''
    &${pkgs.ctpv}/bin/ctpv -s $id
    cmd on-quit %${pkgs.ctpv}/bin/ctpv -e $id
    set cleaner ${pkgs.ctpv}/bin/ctpvclear
  '';
}

Gentoo

Add this ctpv-9999.ebuild to your own repository.

Or alternatively:

eselect repository add sneethe-overlay git https://github.com/Sneethe/sneethe-overlay.git
emaint sync --repo sneethe-overlay
emerge --ask --verbose app-misc/ctpv

Integration

lf file manager

Add these lines to your lf config (usually located at ~/.config/lf/lfrc).

set previewer ctpv
set cleaner ctpvclear
&ctpv -s $id
&ctpvquit $id

Wayland

If you use Wayland, follow these steps:

Make sure you use one of the terminals that support sixel
Install this fork of lf
Install Chafa
Add set chafasixel to ~/.config/ctpv/config

As of 2023-03-19, original lf does not support sixel protocol, which is why you need use the fork.

Documentation

Full documentation on command line options, configuration and how to define custom previews can be found here: https://www.nikitaivanov.com/man1/ctpv