Required Tools

Required Tools

Photosphere requires ImageMagick and FFmpeg (which includes FFprobe) to import photos and videos. Without them, the Import page will show installation instructions instead of the Start button.

---

Why these tools are needed

Tool	Used for
ImageMagick (magick)	Image resizing and conversion; generates display-size images, thumbnails, and micro-thumbnails from photos
FFprobe	Reads video metadata (duration, resolution, codec) without decoding the full file
FFmpeg	Extracts a representative frame from videos to use as their thumbnail

---

Installation

macOS

Using Homebrew (recommended):

brew install imagemagick ffmpeg

Using MacPorts:

sudo port install ImageMagick +universal ffmpeg +universal

Manual downloads:

• ImageMagick: https://imagemagick.org/script/download.php#macosx
• ffmpeg: https://evermeet.cx/ffmpeg/

---

Windows

Using Chocolatey (recommended):

choco install imagemagick ffmpeg

Using Scoop:

scoop install imagemagick ffmpeg

Manual downloads:

• ImageMagick: https://imagemagick.org/script/download.php#windows
• ffmpeg: https://www.gyan.dev/ffmpeg/builds/

---

Linux

Ubuntu / Debian:

sudo apt update && sudo apt install imagemagick ffmpeg

Fedora / RHEL:

dnf install ImageMagick ffmpeg

Arch Linux:

pacman -S imagemagick ffmpeg

Alpine:

apk add imagemagick ffmpeg

Manual downloads:

• ImageMagick (AppImage): https://imagemagick.org/script/download.php#linux
• ffmpeg (static builds, includes ffprobe): https://github.com/BtbN/FFmpeg-Builds/releases

---

Verifying installation

Open a terminal and run:

magick --version
ffmpeg -version
ffprobe -version

All three commands should print a version string. If any command is not found, re-check that the install location is on your PATH and restart Photosphere after installing.

On older systems, ImageMagick may use convert instead of magick:

convert --version

You can also run psi tools to let the CLI check and report the status of all required tools.

---

Troubleshooting PATH issues

• macOS / Linux: Homebrew typically installs to /usr/local/bin (Intel) or /opt/homebrew/bin (Apple Silicon). If magick is not found, add the Homebrew bin directory to your shell's PATH in ~/.zshrc or ~/.bashrc, then restart Photosphere.
• Windows: Chocolatey installs to C:\ProgramData\chocolatey\bin; Scoop installs to %USERPROFILE%\scoop\shims. Both are usually added to PATH automatically. If not, add them manually via System Properties → Environment Variables, then restart Photosphere.

After installing, use the Check again button on the Import page (desktop app) to re-run the tool check without restarting the app.