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 `PP_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.

Download

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

Platform	Archive name
Linux x86_64	`pdfium-linux-x64.tgz`
Linux arm64	`pdfium-linux-arm64.tgz`
macOS arm64	`pdfium-mac-arm64.tgz`
macOS x86_64	`pdfium-mac-x64.tgz`
Windows x86_64	`pdfium-win-x64.zip`

Install

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

Extract pdfium-win-x64.zip and place pdfium.dll (from the bin\ directory) in the same directory as previewproxy.exe.

libheif

Required for HEIC / HEIF input.

Linux

# Debian / Ubuntu
sudo apt install libheif1

# Arch Linux
sudo pacman -S libheif

macOS

brew install libheif

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

libheif is statically linked on Windows when built using vcpkg with the x64-windows-static-md triplet (as described in Build from Source). No runtime DLL is required.

ffmpeg

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:PP_FFMPEG_PATH = "C:\ffmpeg\bin\ffmpeg.exe"
previewproxy

Custom path (all platforms)

Set PP_FFMPEG_PATH to use a non-PATH location:

PP_FFMPEG_PATH=/opt/ffmpeg/bin/ffmpeg previewproxy

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