Photo and video import tools

Published May 23, 2026 · Updated August 16, 2026

🧭 You may not need this page

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

Otherwise, PhotoStructure offers to set these tools up for you on first launch. Say yes and you’re done. The rest of this page covers what that installs, how to do it by hand instead, and how to undo it.

📦 What PhotoStructure installs for you

As of version 2026.5, PhotoStructure on Linux, macOS, Windows, and Docker checks for missing photo and video import tools during first launch. If tools are missing, it asks for your consent, then hands the work to a standard package manager. PhotoStructure never hosts or serves the tools itself.

macOS uses Homebrew if you already have it. If you don’t, PhotoStructure downloads Pixi into $HOME/.pixi (a single signed binary from Pixi’s own GitHub release, verified by SHA-256 and macOS code signature) and installs FFmpeg with that. No administrator password is required, and FFmpeg is the only addition: macOS reads .heic photos on its own.

Windows downloads Pixi into %UserProfile%\.pixi (a single binary from Pixi’s own GitHub release, verified by SHA-256 and its Authenticode signature) and uses it to fetch FFmpeg from conda-forge, a community-run software repository. No administrator password is required, and nothing outside your user profile is touched. Earlier releases used MSYS2 instead; see Uninstalling if you’d like to clean that up.

Linux downloads Pixi into $HOME/.pixi and uses it to fetch FFmpeg from conda-forge. Nothing runs as root, and your distribution’s own packages stay untouched. The same steps work on Debian, Ubuntu, Fedora, Arch, and openSUSE. conda-forge builds need glibc, so Alpine and other musl-based distributions have to install by hand.

Docker fetches the same conda-forge FFmpeg into pixi/linux-<arch> inside your system settings directory, running as the container’s ordinary unprivileged user. The system settings is either the bind-mount /ps/config, or if missing, /ps/library/.photostructure/docker-config. Expect about 700 MB disk use.

Because nothing needs root, this works under hardened container runtimes, including TrueNAS SCALE apps. See PhotoStructure for Docker for how to move it.

On Windows, Linux, and Docker, that FFmpeg is version 8.1 or newer, so it reads .heic photos as well and libheif isn’t installed.

You can install or skip these tools later from the Video support or HEIF support health check.

📸 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 uses one or two extra tools when importing them:

FFmpeg reads video files and converts them so you can watch them in PhotoStructure. Version 8.1 and later reads .heic photos too.
libheif also reads .heic photos, the format used by iPhones, Samsung Galaxy phones, and many newer cameras. It’s optional, and packaged by many Linux distributions: PhotoStructure uses its heif-thumbnailer to build the smallest thumbnails, which is quicker than asking FFmpeg for them. Full-size .heic photos go through FFmpeg, or through macOS itself on a Mac.

PhotoStructure doesn’t bundle either one, so they have to be installed separately.

.avif photos use the same tools as .heic. On a Mac they need macOS 13 (Ventura) or later — earlier versions read .heic but not .avif, and PhotoStructure will report .avif files as unreadable. The HEIF support health check says so if it applies to you. Linux, Windows, and Docker read .avif with the same FFmpeg that reads .heic.

🛠️ Installing the tools yourself

Install by hand if you run Alpine or another musl-based distribution, prefer your distribution’s own packages, or are working through a failed install.

🐧 Linux

Install libheif alongside FFmpeg. Reading .heic with FFmpeg needs version 8.1 or newer, and most distributions still ship 7.x or 8.0. The libheif packages also give you heif-thumbnailer, which builds the smallest .heic thumbnails about twice as fast as FFmpeg does.

🦖 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, check the version:

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

macOS reads .heic photos on its own, so FFmpeg is all you need.

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 administrator 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

🪟 Windows

FFmpeg 8.1 and later reads .heic photos, so one package covers both videos and phone photos. Everything lands in your own user profile, so no administrator password is needed.

Open PowerShell and install Pixi (if you don’t have it):

powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"

Close that window and open a new PowerShell, so %UserProfile%\.pixi\bin is on your PATH. Then install FFmpeg:
```
pixi global install --channel conda-forge --expose ffmpeg --expose ffprobe "ffmpeg>=8.1"
```
The quotes around "ffmpeg>=8.1" matter: without them PowerShell reads the > as a redirect and writes a file named =8.1.

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 MSYS2 or Cygwin. Neither is needed now. See Uninstalling to remove MSYS2, or uninstall Cygwin if you aren’t using it for anything else.

✅ 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

🐧 Linux

If PhotoStructure installed FFmpeg for you:

pixi global uninstall ffmpeg

To fully uninstall Pixi as well:

rm -rf ~/.pixi

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

🍎 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

If PhotoStructure installed FFmpeg for you:

pixi global uninstall ffmpeg

To fully uninstall Pixi as well, delete the %UserProfile%\.pixi directory, then remove %UserProfile%\.pixi\bin from your PATH (Settings > System > About > Advanced system settings > Environment Variables).

If you have MSYS2 from an older release:

PhotoStructure used MSYS2 on Windows before version 2026.5. To remove just the packages it installed, open the MSYS2 MINGW64 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.

🐳 Docker

Delete the pixi directory inside your system settings directory — normally /ps/library/.photostructure/docker-config/pixi, or /ps/config/pixi if you bind-mounted it — or wherever you set PIXI_HOME.

📚 See also

Advanced settings documentation

Install