ytdl-org/youtube-dl · error · FFmpegPostProcessorError

ffmpeg or avconv not found. Please install one.

Error message

ffmpeg or avconv not found. Please install one.

What it means

Raised by FFmpegPostProcessor.check_version() when neither ffmpeg nor avconv was found on PATH at initialization (self.available is falsy). Almost every ffmpeg-based post-processor (audio extraction, recode, metadata, embed-thumbnail via ffmpeg) calls check_version first, so this error gates all of them.

Source

Thrown at youtube_dl/postprocessor/ffmpeg.py:62

    'm4a': 'aac',
    'opus': 'libopus',
    'vorbis': 'libvorbis',
    'wav': None,
}


class FFmpegPostProcessorError(PostProcessingError):
    pass


class FFmpegPostProcessor(PostProcessor):
    def __init__(self, downloader=None):
        PostProcessor.__init__(self, downloader)
        self._determine_executables()

    def check_version(self):
        if not self.available:
            raise FFmpegPostProcessorError('ffmpeg or avconv not found. Please install one.')

        required_version = '10-0' if self.basename == 'avconv' else '1.0'
        if is_outdated_version(
                self._versions[self.basename], required_version):
            warning = 'Your copy of %s is outdated, update %s to version %s or newer if you encounter any errors.' % (
                self.basename, self.basename, required_version)
            if self._downloader:
                self._downloader.report_warning(warning)

    @staticmethod
    def get_versions(downloader=None):
        return FFmpegPostProcessor(downloader)._versions

    def _determine_executables(self):
        # ordered to match prefer_ffmpeg!
        convs = ['ffmpeg', 'avconv']
        probes = ['ffprobe', 'avprobe']
        prefer_ffmpeg = True

View on GitHub (pinned to 956b8c5855)

Solutions

  1. Install ffmpeg (Debian/Ubuntu: apt install ffmpeg; macOS: brew install ffmpeg; Windows: winget install ffmpeg)
  2. If already installed, pass its directory explicitly: --ffmpeg-location /path/to/ffmpeg/bin
  3. For cron/systemd/CI, set PATH in the environment or use the absolute --ffmpeg-location
  4. Verify with 'ffmpeg -version' and 'avconv -version' in the same shell you launch youtube-dl from

Example fix

# before
youtube-dl -x --audio-format mp3 URL   # fails: ffmpeg not found
# after
sudo apt-get install ffmpeg
youtube-dl -x --audio-format mp3 URL
Defensive patterns

Strategy: validation

Validate before calling

import shutil

def ffmpeg_ready(location=None):
    if location:
        import os
        return os.path.exists(os.path.join(location, 'ffmpeg')) or os.path.exists(os.path.join(location, 'avconv'))
    return bool(shutil.which('ffmpeg') or shutil.which('avconv'))

assert ffmpeg_ready(opts.get('ffmpeg_location')), 'ffmpeg required for post-processing'

Try / catch

try:
    ydl.download([url])
except PostProcessingError as e:
    if 'ffmpeg or avconv not found' in str(e):
        raise SystemExit('Install ffmpeg or pass --ffmpeg-location before using -x/--recode-video')

Prevention

When it happens

Trigger: Using -x/--recode-video/--add-metadata/etc. on a machine without ffmpeg or avconv installed, or where they are installed but not on the PATH that youtube-dl sees; --ffmpeg-location pointing to a wrong path.

Common situations: Minimal Docker images and fresh servers; ffmpeg installed via a tool like snap/flatpak not on PATH; running under cron/systemd where PATH is stripped; Windows users who downloaded ffmpeg but never added it to PATH.

Related errors

AI-assisted analysis of ytdl-org/youtube-dl@956b8c5855 (2026-08-14). Data as JSON: /api/errors/3dc60878142b08a1. Report an issue: GitHub.