{"record":{"id":"3dc60878142b08a1","repo":"ytdl-org/youtube-dl","slug":"ffmpeg-or-avconv-not-found-please-install-one","errorCode":null,"errorMessage":"ffmpeg or avconv not found. Please install one.","messagePattern":"ffmpeg or avconv not found\\. Please install one\\.","errorType":"exception","errorClass":"FFmpegPostProcessorError","httpStatus":null,"severity":"error","filePath":"youtube_dl/postprocessor/ffmpeg.py","lineNumber":62,"sourceCode":"    'm4a': 'aac',\n    'opus': 'libopus',\n    'vorbis': 'libvorbis',\n    'wav': None,\n}\n\n\nclass FFmpegPostProcessorError(PostProcessingError):\n    pass\n\n\nclass FFmpegPostProcessor(PostProcessor):\n    def __init__(self, downloader=None):\n        PostProcessor.__init__(self, downloader)\n        self._determine_executables()\n\n    def check_version(self):\n        if not self.available:\n            raise FFmpegPostProcessorError('ffmpeg or avconv not found. Please install one.')\n\n        required_version = '10-0' if self.basename == 'avconv' else '1.0'\n        if is_outdated_version(\n                self._versions[self.basename], required_version):\n            warning = 'Your copy of %s is outdated, update %s to version %s or newer if you encounter any errors.' % (\n                self.basename, self.basename, required_version)\n            if self._downloader:\n                self._downloader.report_warning(warning)\n\n    @staticmethod\n    def get_versions(downloader=None):\n        return FFmpegPostProcessor(downloader)._versions\n\n    def _determine_executables(self):\n        # ordered to match prefer_ffmpeg!\n        convs = ['ffmpeg', 'avconv']\n        probes = ['ffprobe', 'avprobe']\n        prefer_ffmpeg = True","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/ytdl-org/youtube-dl/blob/956b8c585591b401a543e409accb163eeaaa1193/youtube_dl/postprocessor/ffmpeg.py#L44-L80","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install ffmpeg (Debian/Ubuntu: apt install ffmpeg; macOS: brew install ffmpeg; Windows: winget install ffmpeg)","If already installed, pass its directory explicitly: --ffmpeg-location /path/to/ffmpeg/bin","For cron/systemd/CI, set PATH in the environment or use the absolute --ffmpeg-location","Verify with 'ffmpeg -version' and 'avconv -version' in the same shell you launch youtube-dl from"],"exampleFix":"# before\nyoutube-dl -x --audio-format mp3 URL   # fails: ffmpeg not found\n# after\nsudo apt-get install ffmpeg\nyoutube-dl -x --audio-format mp3 URL","handlingStrategy":"validation","validationCode":"import shutil\n\ndef ffmpeg_ready(location=None):\n    if location:\n        import os\n        return os.path.exists(os.path.join(location, 'ffmpeg')) or os.path.exists(os.path.join(location, 'avconv'))\n    return bool(shutil.which('ffmpeg') or shutil.which('avconv'))\n\nassert ffmpeg_ready(opts.get('ffmpeg_location')), 'ffmpeg required for post-processing'","typeGuard":null,"tryCatchPattern":"try:\n    ydl.download([url])\nexcept PostProcessingError as e:\n    if 'ffmpeg or avconv not found' in str(e):\n        raise SystemExit('Install ffmpeg or pass --ffmpeg-location before using -x/--recode-video')","preventionTips":["Provision ffmpeg in CI images and servers up front","Use --ffmpeg-location with an absolute path in cron/systemd where PATH is minimal","Verify 'ffmpeg -version' in the exact environment that runs youtube-dl"],"tags":["ffmpeg","dependency","path","postprocessor"],"backgroundTag":null,"analyzedSha":"956b8c585591b401a543e409accb163eeaaa1193","analyzedAt":"2026-08-14T18:59:47.863Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}