Photo and video import tools

Published May 23, 2026 · Updated June 30, 2026

🧭 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 instructions

🦖 Ubuntu 26.04, 25.04+, or Debian Trixie

sudo apt install ffmpeg libheif-examples heif-thumbnailer

🦏 Ubuntu 24.04

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

🍃 Linux Mint and LMDE

Check your Linux Mint or LMDE release:

( . /etc/os-release && printf '%s\n' "$PRETTY_NAME" )

Then follow the matching install instructions:

Linux Mint 22.x → Ubuntu 24.04
LMDE 6 → Debian Bookworm

(Other versions of Linux Mint or LMDE have not been tested)

🎩 Fedora 40 or later

Fedora doesn’t ship H.264/H.265 codecs because of software patents, so you need RPM Fusion — a third-party repository maintained by Fedora community members.

Enable it (if you haven’t already):

sudo dnf install \
  https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm

Then install the tools:

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)

✅ Confirm the libheif version

After installing, double-check you’re above the iPhone-decoding floor:

heif-convert --version

This should report 1.19.0 or newer. If it reports 1.17.x or 1.18.x, your apt cache still points at the distro’s stock package — re-run sudo apt update and re-install.

🍎 macOS instructions

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:

Homebrew already installed? PhotoStructure runs brew install ffmpeg.
Pixi already installed? PhotoStructure runs pixi global install ffmpeg.
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 instructions

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), then follows the MSYS2 update procedure before installing the codec packages.

If you prefer to install them yourself:

Download and install MSYS2

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

# 1. Refresh the keyring so signatures from older installs validate:
pacman -Sy msys2-keyring

# 2. Run the full MSYS2 update. If pacman tells you to close all MSYS2
#    windows, close them, reopen MSYS2 MINGW64, and run this again.
#    Repeat until pacman reports nothing to upgrade:
pacman -Suy

# 3. Install the media tools:
pacman -S --needed mingw-w64-x86_64-libheif mingw-w64-x86_64-ffmpeg

MSYS2 is a rolling-release distribution and only supports full system upgrades — skipping step 2 can leave packages in a partial-upgrade state that produces errors like could not find or read package. See the official MSYS2 update docs for background.

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 instructions

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:

Install FFmpeg.
Set PS_TRANSCODE_VIDEOS to false in your library settings.
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:

Quality level	H.264 CRF	HEVC CRF
Visually lossless	18	22
Good quality (default)	23	28
Acceptable for web	28	32

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, Linux Mint, LMDE:

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