Photo and video import tools

🧭 You may not need this page!

If your library has no videos and no .heic photos, you can skip this page.

As of version 2026.4, PhotoStructure on Docker, macOS, and Windows checks for missing photo and video import tools during first launch. If tools are missing, PhotoStructure asks for your consent, then uses your platform’s standard package manager (Homebrew or Pixi on macOS, MSYS2 on Windows, and apt on Docker).

Use this page if you:

• need to install Linux packages yourself
• want to install the tools manually
• need reference details for troubleshooting or uninstalling

📸 Why do I need extra tools for some photos and videos?

Modern phones and cameras save photos and videos in newer, space-saving formats. Your phone reads them fine, but PhotoStructure may use one or two extra tools when importing them:

• FFmpeg reads video files and converts them so you can watch them in PhotoStructure

• libheif reads .heic photos, the format used by iPhones, Samsung Galaxy phones, and many newer cameras

🐧 Linux

You need FFmpeg for videos and libheif tools for .heic photos from iPhones and newer Android phones. Pick your distribution below.

🦖 Ubuntu 25.04+ or Debian Trixie

sudo apt install ffmpeg libheif-examples heif-thumbnailer

🦏 Ubuntu 24.04 or 24.10

sudo apt install ffmpeg
sudo add-apt-repository ppa:strukturag/libheif
sudo apt install libheif-examples heif-thumbnailer

🪨 Ubuntu 22.04

sudo apt install ffmpeg
sudo add-apt-repository ppa:strukturag/libde265
sudo add-apt-repository ppa:strukturag/libheif
sudo apt install libheif-examples heif-thumbnailer

🪱 Debian Bookworm

sudo apt install ffmpeg
echo 'deb http://deb.debian.org/debian bookworm-backports main' | sudo tee /etc/apt/sources.list.d/backports.list
sudo apt update
sudo apt install -t bookworm-backports libheif-examples heif-thumbnailer

🎩 Fedora

sudo dnf install ffmpeg libheif-tools

🧩 Why the libheif instructions vary

You need at least libheif v1.19.0 for correct iPhone photo decoding.

• v1.17.x and earlier crash on iPhone 16 and later photos (Too many auxiliary image references, fixed in v1.18.0, released 2024-07-10)
• v1.18.x produces wrong pixel values on iPhone 12 Pro and later photos (tiled HEVC grids, fixed in v1.19.0)

🍎 macOS reference

PhotoStructure on macOS can install FFmpeg for you on first run. You’ll be asked to consent before anything is installed. The installer picks the best available path:

1. Homebrew already installed? PhotoStructure runs brew install ffmpeg.
2. Pixi already installed? PhotoStructure runs pixi global install ffmpeg.
3. Neither present? PhotoStructure downloads Pixi (a single signed binary from the official GitHub release, verified by SHA-256 and macOS code signature), extracts it into ~/.pixi/bin, then uses it to install ffmpeg from conda-forge. No admin password is required.

If you prefer to install FFmpeg yourself, use either Homebrew or Pixi:

Option A — Homebrew:

# Install Homebrew (if needed):
/bin/bash -c "$(curl -fsSL \
  https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install FFmpeg:
brew install ffmpeg

Option B — Pixi (no admin password):

# Install Pixi (if needed):
curl -fsSL https://pixi.sh/install.sh | bash
# Install FFmpeg:
pixi global install --channel conda-forge --expose ffmpeg --expose ffprobe ffmpeg

macOS already includes the tools PhotoStructure uses to read .heic photos.

🪟 Windows reference

PhotoStructure on Windows can install FFmpeg and libheif for you on first run. It sets up MSYS2 if it’s missing (using the official GitHub release, verified by SHA-256), and then runs the pacman command below.

If you prefer to install them yourself:

1. Download and install MSYS2

2. Open MSYS2 MINGW64 terminal (not the MSYS2 terminal), and run:

   pacman -S mingw-w64-x86_64-libheif mingw-w64-x86_64-ffmpeg
   

Notes:

• Always scan downloaded software for viruses.
• The FFmpeg website has Windows builds, but those are archives, not installers. You’ll need to extract the contents and add the bin directory to your %PATH%.
• Previous instructions suggested Cygwin, but its builds are outdated. Uninstall Cygwin if you aren’t using it for anything else.

🐳 Docker reference

PhotoStructure for Docker does not bundle FFmpeg or libheif. On first run, PhotoStructure asks whether to install the extra import tools from the container’s operating system package manager.

You can change your choice later from the Video support or HEIF support health check.

✅ Verify the installation

Start PhotoStructure and open the Health Check window (via the ☰ menu).

Verify that there are green check marks by Video support and HEIF support.

🎛️ Video settings

You can stop here if PhotoStructure’s health checks are green. The sections below are for advanced video settings and cleanup.

🖼️ Video thumbnails without transcoding

If you want video preview images but don’t need streaming playback:

1. Install FFmpeg.
2. Set PS_TRANSCODE_VIDEOS to false in your library settings.
3. Start PhotoStructure and run sync.

🎞️ Video codec settings

PhotoStructure can transcode videos to either H.264 (default) or HEVC/H.265 format. Use the transcodeVideoCodec setting to choose.

🛻 H.264 (libx264): default, recommended

• Browser compatibility: Works in all major browsers
• Fast encoding: 3–5x faster than HEVC
• Larger files: ~25–40% larger than equivalent HEVC

🏎️ HEVC/H.265 (libx265): for storage-constrained setups

• Smaller files: 25–40% smaller than H.264 at equivalent quality
• Slower encoding: 2–5x slower than H.264
• Limited playback compatibility: Works best when you control the browser and devices used to view your library

🎚️ CRF quality settings

When switching codecs, adjust your transcodeCrf setting:

HEVC CRF values are ~5 higher than H.264 for equivalent visual quality.

🌐 Browser compatibility for video playback

PhotoStructure streams videos directly to your browser. H.264 is the safest choice if you view your library from several browsers or devices.

HEVC/H.265 playback depends on your browser, operating system, hardware, and installed OS codecs. If you use Firefox on Windows, you may also need HEVC Video Extensions from the Microsoft Store and the media.wmf.hevc.enabled setting in about:config.

Recommendation:

• Use H.264 (default) if you use Firefox on Windows/Linux or need the broadest compatibility
• Use HEVC only if you want smaller video files, don’t mind slower transcoding, and know your browsers and devices can play it

🌈 Colorspace handling

PhotoStructure automatically handles video colorspace conversion during transcoding:

• HDR videos (BT.2020/PQ/HLG): Preserved without conversion
• HD videos (BT.709): Tagged correctly, no conversion needed
• SD videos (BT.601): Converted to BT.709 for browser compatibility

This fixes issues where videos in wider color spaces (like Rec. 2020) would appear with blown-out colors after transcoding. See this forum discussion for background.

🧹 Uninstalling

🍎 macOS

If you installed via Homebrew:

brew uninstall ffmpeg

To fully uninstall Homebrew as well:

/bin/bash -c "$(curl -fsSL \
  https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"

If you installed via Pixi:

pixi global uninstall ffmpeg

To fully uninstall Pixi as well:

rm -rf ~/.pixi

macOS already includes the image tools PhotoStructure uses for .heic photos, so there is nothing to uninstall.

🪟 Windows

To uninstall either the libheif or ffmpeg packages, open a terminal and run:

pacman -R mingw-w64-x86_64-libheif mingw-w64-x86_64-ffmpeg

If you want to fully uninstall MSYS2 as well, uninstall it like any other Windows application: Settings > Apps > Installed Apps, scroll to MSYS2, click ⋯, and select Uninstall.

After that completes, you can also manually delete the C:\msys64 directory if it still exists.

🐧 Linux

Ubuntu/Debian:

sudo apt remove ffmpeg libheif-examples heif-thumbnailer

To also remove the strukturag PPAs:

sudo add-apt-repository --remove ppa:strukturag/libheif
sudo add-apt-repository --remove ppa:strukturag/libde265

Fedora:

sudo dnf remove ffmpeg libheif-tools

📚 See also

• Advanced settings documentation

• Install