Installation

Requirements

• Python 3.10–3.14
• ffmpeg and ffprobe on PATH, or explicit binary paths
• pipx for the recommended isolated CLI install

Install FFmpeg using the package source you already trust for your operating system. PyFFmpegCore deliberately does not download or bundle it.

macOS and Windows FFmpeg

On macOS, Homebrew's ffmpeg formula provides both ffmpeg and ffprobe:

brew install ffmpeg
ffmpeg -version
ffprobe -version

On Windows, the Microsoft WinGet repository currently lists the Gyan.FFmpeg 8.1.2 full build. Follow Microsoft's WinGet install command in PowerShell:

winget install --id Gyan.FFmpeg --exact

Open a new PowerShell window after installation, then run:

ffmpeg -version
ffprobe -version

If either executable is still missing, inspect the package's install location and PATH, or pass trusted absolute binary paths as shown in troubleshooting. The WinGet, Fedora, Arch, and Homebrew package pages were checked on 24 September 2026. The Windows and Linux installations were not run on this macOS host. CI also installs FFmpeg separately on hosted macOS and Windows runners.

Ubuntu and Debian FFmpeg

Install the distribution package with APT:

sudo apt-get update
sudo apt-get install ffmpeg
ffmpeg -version
ffprobe -version

Ubuntu 24.04 lists ffmpeg in Universe; its package file list includes both executables. Debian 12's ffmpeg package also includes both command-line tools. If APT cannot find the Ubuntu package, check that the Universe repository is enabled. See the APT install command reference. Package pages were checked on 24 September 2026. Then install PyFFmpegCore with pipx below and run pyffmpegcore doctor and pyffmpegcore smoke-test.

Fedora Linux and Arch Linux

On Fedora 44, install the distribution's ffmpeg-free package with the documented DNF install command:

sudo dnf install ffmpeg-free

Fedora's Fedora 44 update file list includes both ffmpeg and ffprobe. This build deliberately supports fewer codecs than some third-party FFmpeg builds.

On x86_64 Arch Linux, install the official ffmpeg package as described in the ArchWiki installation section:

sudo pacman -S ffmpeg

The Arch package file list also includes both executables. After installing PyFFmpegCore with pipx below, check the selected build and a real synthetic workflow:

ffmpeg -version
ffprobe -version
pyffmpegcore doctor
pyffmpegcore smoke-test

These Fedora and Arch install commands were checked against official package pages on 24 September 2026; they were not executed on those distributions in this audit. Encoder and filter availability depends on the installed FFmpeg build. Inspect pyffmpegcore doctor --json before relying on a particular workflow; PyFFmpegCore does not fetch missing codecs.

Bash or zsh

Install the exact validated public release:

pipx install "pyffmpegcore==0.3.3"
pyffmpegcore --version
pyffmpegcore doctor
pyffmpegcore smoke-test

A repository checkout also provides ./install.sh.

uv users can install the same release as an isolated tool:

uv tool install "pyffmpegcore==0.3.3"
pyffmpegcore smoke-test

PowerShell

pipx install "pyffmpegcore==0.3.3"
pyffmpegcore --version
pyffmpegcore doctor
pyffmpegcore smoke-test

From a checkout, use ./install.ps1; do not run the POSIX shell installer on Windows.

Python project dependency

For a Python project dependency:

python -m pip install "pyffmpegcore==0.3.3"

Use an appropriate compatible-release constraint after validating future versions against your own media workflows.

There is no Homebrew tap today. The project will add and maintain one only after public demand justifies another release channel; Homebrew can still install the external FFmpeg dependency.

Verify the selected binaries

pyffmpegcore doctor --json

The report includes resolved paths, versions, build configuration, capability counts, selected workflow encoders/filters, and hardware accelerators. If a capability listing times out, capabilities is null, capabilities_error explains the failure, and doctor exits with code 3. Supplying an untrusted --ffmpeg-path or --ffprobe-path executes that binary; treat it like any other executable.