---
title: Photo and video import tools
url: https://photostructure.com/getting-started/media-codec-support/
description: Reference for the extra tools PhotoStructure uses to import videos and some phone photos.
date: 2026-04-27
keywords: video-transcoding, HEIF, H.265, installation, Docker, H.264
---


<a id="why-do-i-need-to-install-these"></a>

## 🧭 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](https://brew.sh/) or
[Pixi](https://pixi.sh) on macOS,
[MSYS2](https://www.msys2.org/) on Windows, and
[apt](https://wiki.debian.org/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](https://www.ffmpeg.org/)** reads video files and converts them so
  you can watch them in PhotoStructure

- **[libheif](https://github.com/strukturag/libheif)** reads `.heic` photos,
  the format used by iPhones, Samsung Galaxy phones, and many newer cameras

{{< note >}}
Installing this software may subject you to patent licensing requirements
depending on your jurisdiction and use case. You are responsible for compliance
with applicable licenses. PhotoStructure does not distribute, warrant, or
support the installed third-party software.
{{< /note >}}

<a id="install-linux"></a>

## 🐧 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

```sh
sudo apt install ffmpeg libheif-examples heif-thumbnailer
```

### 🦏 Ubuntu 24.04 or 24.10

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

### 🪨 Ubuntu 22.04

```sh
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

```sh
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

```sh
sudo dnf install ffmpeg libheif-tools
```

{{% tip %}}
Snap Store versions of FFmpeg do not work with PhotoStructure.
{{% /tip %}}

<a id="heif-linux"></a>

### 🧩 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](https://github.com/strukturag/libheif/releases/tag/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](https://github.com/strukturag/libheif/releases/tag/v1.19.0))

<a id="install-macos"></a>

## 🍎 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](https://pixi.sh) (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:**

```sh
# 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):**

```sh
# 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.

<a id="install-windows"></a>
<a id="windows-heif"></a>

## 🪟 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](https://www.msys2.org/#installation)

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

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

Notes:

- Always [scan downloaded software for viruses](/faq/scan-for-viruses/).
- The FFmpeg website has [Windows builds](https://ffmpeg.org/download.html#build-windows),
  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](https://www.cygwin.com/), but its
  builds are outdated. [Uninstall Cygwin](https://www.cygwin.com/faq.html#faq.setup.uninstall-all)
  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](/getting-started/advanced-settings/#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:

| 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](https://apps.microsoft.com/detail/9nmzlz57r3t7) 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](https://forum.photostructure.com/t/poor-transcoding-of-videos-in-wider-color-spaces-rec-2020/646)
for background.

## 🧹 Uninstalling

### 🍎 macOS

**If you installed via Homebrew:**

```sh
brew uninstall ffmpeg
```

To fully uninstall Homebrew as well:

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

**If you installed via Pixi:**

```sh
pixi global uninstall ffmpeg
```

To fully uninstall Pixi as well:

```sh
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:

```sh
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:**

```sh
sudo apt remove ffmpeg libheif-examples heif-thumbnailer
```

To also remove the strukturag PPAs:

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

**Fedora:**

```sh
sudo dnf remove ffmpeg libheif-tools
```

## 📚 See also

- [Advanced settings documentation](/getting-started/advanced-settings/)