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.