How to Install librosa and soundfile in CI Without libsndfile Errors

librosa reads audio through soundfile, which links libsndfile. On a slim runner the import fails with "sndfile library not found" until you install libsndfile1.

librosa is pure Python, but it depends on soundfile, which wraps the C library libsndfile. Modern soundfile wheels often bundle libsndfile, but on many slim images you still need libsndfile1 - and decoding MP3/compressed audio needs ffmpeg.

Why it fails in CI

soundfile loads libsndfile at runtime; if the system library is absent (and not bundled for your platform), import soundfile / librosa fails. Compressed formats (MP3, M4A) also need an external decoder like ffmpeg, which slim images lack.

• OSError: sndfile library not found / cannot load library libsndfile on import.
• No matching distribution for a dependency on a new Python/musl.
• librosa failing to load MP3/compressed audio because ffmpeg is missing.

Install it reliably

Install libsndfile1 so soundfile can load its backend, and ffmpeg so librosa can decode compressed audio. Then install the Python packages from wheels.

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

# Alpine
apk add --no-cache libsndfile ffmpeg

pip install --only-binary=:all: librosa soundfile

Cache & speed

Cache ~/.cache/pip so the wheels are reused, and bake libsndfile1 + ffmpeg into a custom image so apt does not run every job.

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

Common errors

Key takeaways

• soundfile needs libsndfile - install libsndfile1 on slim/Alpine images.
• Add ffmpeg so librosa can decode MP3/compressed audio.
• Bake the system libs into the image; cache ~/.cache/pip.

Related guides