---
title: "pydub Silent ffmpeg Dependency in Docker"
aliases: [pydub-ffmpeg, pydub-mp3-docker, pydub-runtime-crash]
tags: [python, audio, docker, gotcha, pydub, ffmpeg]
sources:
  - "daily/2026-04-30.md"
created: 2026-04-30
updated: 2026-04-30
---

# pydub Silent ffmpeg Dependency in Docker

`pydub` installs cleanly via pip but crashes at runtime when exporting audio if the system `ffmpeg` binary is not present in the Docker image. The error gives no hint that `ffmpeg` is required — it just fails with a file-not-found error.

## Key Points

- `pydub.AudioSegment.export(format="mp3")` requires system `ffmpeg` binary at runtime
- `pip install pydub` succeeds with no warnings; the missing dependency is invisible until export is called
- Runtime error: `[Errno 2] No such file or directory: 'ffmpeg'`
- No import-time warning — the failure surfaces only when `export()` is invoked
- Fix option 1: add `RUN apt-get install -y ffmpeg` to your Dockerfile
- Fix option 2: replace pydub with `lameenc` (pure-Python MP3 encoder) — no system dependency
- `lameenc` works for PCM→MP3 conversion without any system binary

## Details

### Why This Bites You in Docker

A standard Python Docker image (`python:3.11-slim`) contains no system audio tools. `pydub` delegates all audio encoding to external binaries (`ffmpeg`, `avconv`) via subprocess. The import succeeds, model loading succeeds, but the first `export()` call crashes.

```python
# This line installs fine:
# pip install pydub

from pydub import AudioSegment

# This crashes in Docker without ffmpeg:
segment = AudioSegment.from_raw(pcm_data, sample_width=2, frame_rate=22050, channels=1)
segment.export("output.mp3", format="mp3")
# → FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'
```

### Fix 1: Add ffmpeg to Dockerfile

```dockerfile
RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*
```

### Fix 2: Replace with lameenc (pure Python)

```python
import lameenc

encoder = lameenc.Encoder()
encoder.set_bit_rate(128)
encoder.set_in_sample_rate(22050)
encoder.set_channels(1)
encoder.set_quality(2)

mp3_data = encoder.encode(pcm_bytes)
mp3_data += encoder.flush()
mp3_bytes = bytes(mp3_data)  # lameenc returns bytearray — must cast
```

Note: `lameenc.encode()` returns `bytearray`, not `bytes` — see [[wiki/concepts/lameenc-bytearray-gcs-upload]] for the GCS upload gotcha.

### Diagnosis

When `pydub` crashes with `[Errno 2] No such file or directory: 'ffmpeg'`:
1. Confirm no `ffmpeg` in image: `docker run --rm <image> which ffmpeg`
2. Choose fix based on whether you control the Dockerfile and need full ffmpeg capabilities

## Related Concepts

- [[wiki/concepts/lameenc-bytearray-gcs-upload]] — lameenc bytearray type gotcha when uploading to GCS
- [[wiki/concepts/celery-redis-queue-flush-on-deterministic-error]] — when pydub crash causes Celery retry loops

## Sources

- [[daily/2026-04-30.md]] — Session 18:47, pydub MP3 export failing in Docker TTS worker
