How to Install pydub in CI Without ffmpeg Audio Errors

pydub is pure Python, but anything beyond raw WAV goes through ffmpeg. CI fails with "couldn’t find ffmpeg" the moment you touch MP3 or other compressed formats.

pydub manipulates audio in Python but relies on the ffmpeg (or avconv) binary for decoding and encoding compressed formats like MP3, M4A, and OGG. The pip install needs nothing extra, so failures appear at runtime as a warning then an error when the binary is missing.

Why it fails in CI

pydub handles raw WAV natively but shells out to ffmpeg for compressed audio. On a slim runner ffmpeg is absent, so loading or exporting MP3/M4A raises "Couldn’t find ffmpeg or avconv" (often after a RuntimeWarning at import).

• Couldn’t find ffmpeg or avconv when loading/exporting compressed audio.
• RuntimeWarning: Couldn’t find ffmpeg at import - a warning that becomes an error on use.
• WAV works but MP3/M4A fails because only the ffmpeg path needs the binary.

Install it reliably

Install the ffmpeg binary via apt/apk so pydub can decode and encode compressed audio, then pip install pydub.

# Debian/Ubuntu: ffmpeg binary for compressed audio
apt-get update && apt-get install -y ffmpeg

# Alpine
apk add --no-cache ffmpeg

pip install pydub
ffmpeg -version   # verify pydub can find it on PATH

Cache & speed

ffmpeg is a system binary - bake it into a custom image. Cache ~/.cache/pip only for the small pydub package.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-pydub-${{ hashFiles('requirements*.txt') }}

Common errors

Key takeaways

• pydub is pure Python but needs the ffmpeg binary for compressed audio.
• WAV works without ffmpeg; MP3/M4A/OGG require it.
• Bake ffmpeg into the image and verify it is on PATH.

Related guides