Optional Dependencies

Some input formats require external libraries that are not bundled with the PreviewProxy binary. Install only the ones you need.

Library	Required for	How it is found
`pdfium`	PDF input	Beside the binary (`./`) or on the system library path
`libheif`	HEIC / HEIF input	System library path (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH`)
`ffmpeg`	Video thumbnail extraction	`PATH` or `FFMPEG_PATH` environment variable

pdfium

PreviewProxy renders PDF files using the PDFium library. Pre-built binaries are available from the pdfium-binaries project - no build tools required.

Go to the pdfium-binaries releases page and download the archive for your platform.

Linux / macOS - place beside the binary

Extract the shared library and put it in the same directory as the previewproxy binary:

# Example for Linux x86_64
tar -xzf pdfium-linux-x64.tgz
cp lib/libpdfium.so /usr/local/bin/

PreviewProxy looks for libpdfium.so (Linux) / libpdfium.dylib (macOS) in ./ first, then falls back to the system library path.

Linux - system-wide

sudo cp lib/libpdfium.so /usr/local/lib/
sudo ldconfig

macOS - system-wide

sudo cp lib/libpdfium.dylib /usr/local/lib/

Windows

Place pdfium.dll in the same directory as previewproxy-windows-x86_64.exe.

Required for HEIC / HEIF input.

Linux

# Debian / Ubuntu
sudo apt install libheif1

# Arch Linux
sudo pacman -S libheif

macOS

brew install libheif

info

Homebrew installs libraries to a non-standard path. If PreviewProxy cannot find libheif, add the Homebrew lib directory to DYLD_LIBRARY_PATH:

export DYLD_LIBRARY_PATH="$(brew --prefix libheif)/lib:$DYLD_LIBRARY_PATH"

Windows

Install via vcpkg:

vcpkg install libheif

Or download a pre-built DLL from the libheif GitHub releases and place heif.dll in the same directory as the previewproxy binary.

Required for video thumbnail extraction.

Linux

# Debian / Ubuntu
sudo apt install ffmpeg

# Arch Linux
sudo pacman -S ffmpeg

macOS

brew install ffmpeg

Windows

Download a pre-built build from gyan.dev or install via a package manager:

# winget
winget install ffmpeg

# Chocolatey
choco install ffmpeg

# Scoop
scoop install ffmpeg

Add the bin\ directory to your PATH, or point PreviewProxy directly at the executable:

$env:FFMPEG_PATH = "C:\ffmpeg\bin\ffmpeg.exe"
previewproxy

Custom path (all platforms)

Set FFMPEG_PATH to use a non-PATH location:

FFMPEG_PATH=/opt/ffmpeg/bin/ffmpeg previewproxy

See the Environment Variables reference for the full list of video-related options.