做视频数据集预处理踩坑最烦的就是环境问题。我前阵子在一个视频理解项目里给一批长视频抽帧脚本跑到一半直接抛错报错信息就一句话torchcodec is not available。当时我第一反应是没装吧随手pip install torchcodec装上再跑还是报错。后来才发现这个报错的触发方式远比想象中多——不仅仅是没安装版本不匹配、动态库缺失、torchvision底层实现切换都能以同一句is not available的形式出现。这篇文章我就把这个问题从头到尾拆开记录一下完整的排查思路和可复现的解法给同样被这条报错卡住的人一条顺路。1. 先搞清楚torchcodec是什么这个报错到底在抱怨什么1.1 它在视频读取链路里的角色torchcodec 是 PyTorch 官方团队维护的视频解码库底层基于 FFmpeg。你可以把它理解成视频文件和Tensor之间的翻译官给一个视频路径它负责把 H.264/HEVC 等编码格式的视频解码成一帧一帧的张量数据直接用于训练或推理。在 PyTorch 的视频处理生态里它和 torchvision.io 的关系非常紧密。从 torchvision 0.20 开始torchvision.io里的VideoReader、read_video等接口在底层实现上逐步切换到 torchcodec而不是以前完全自己封装的解码逻辑。这意味着什么意味着你过去写了很长时间的torchvision.io.read_video这段代码在升级了 torchvision 之后底层依赖已经悄悄换成了另一个独立库。一旦 torchcodec 没有正确安装、版本不对或者动态库链接失败torchvision 自己明明还在对外表现却是那句让人摸不着头脑的torchcodec is not available。这个库的核心价值在于解码效率和一站式集成。FFmpeg 本身是 C 库torchcodec 通过 pybind11 封装成 Python 接口同时保留了对 CUDA 硬件解码NVDEC的支持。对于需要在训练脚本里批量读取视频帧的场景它比逐帧用 OpenCV 或 imageio 要顺滑得多。1.2 not available 的三种不同含义同名报错底层原因可能完全不同。根据我实际排查过的案例torchcodec is not available这句话至少对应下面几种情况第一种是纯粹的没有安装。你在一个全新的虚拟环境里跑代码没执行过pip install torchcodec它当然不可用。这种情况报错最直接通常在 import 阶段就会因为ModuleNotFoundError挂掉。第二种是安装了但版本对不上。torchcodec 的预编译扩展是绑定特定 PyTorch 版本号的比如为 torch 2.6 编译的扩展放到 torch 2.7 的环境里运行时符号对不上轻则 import 失败重则在调用具体解码方法时抛 RuntimeError。第三种是装上了但 FFmpeg 动态库缺失。torchcodec 不是一个完全自包含的库它需要系统里有 FFmpeg 的动态库libavcodec、libavformat 等。在精简过的 Docker 镜像、只装了 CPU 版 PyTorch 的服务器或者某些没有完整 FFmpeg 运行时的 Linux 发行版上import torchcodec 本身可能不会报错但一调用就会在加载扩展时挂掉报错文本同样包含 is not available 或者类似找不到动态库的信息。1.3 谁最容易撞上这个错结合我自己的经验经常被这个问题卡住的场景大致有三类做视频数据集预处理的人。抽帧、缩放、裁剪、转 tensor大量代码直接调用torchvision.io或torchcodec环境一换直接踩雷。训练视频理解或多模态模型的同学。这类项目通常依赖比较新的 torch 和 torchvision 版本伴随大量依赖升级一个没对齐就出问题。把项目部署到 Docker 或 Windows 环境的人。容器镜像和本机环境相差很大动态库缺失的问题非常容易在这里爆发。如果你属于这三类中的任意一类下面这份环境自检清单和安装方案应该能直接省掉你几个小时。2. 五分钟环境自检别上来就重装2.1 为什么不能一上来就 pip install很多人的第一反应是缺啥装啥直接pip install torchcodec一把梭。我的建议是先别急。torchcodec 是个强版本依赖的库它和 torch/torchvision 的版本必须在一个兼容矩阵内。如果你不管当前环境的 torch 版本直接装一个最新版 torchcodec很可能越装越乱最后从没安装变成安装不兼容。我见过一个典型例子环境里是 torch 2.6有人手动升级到 torch 2.7 之后忘装对应的 torchcodec然后各种报错最后无奈把环境删了重建。其实多做一步确认就能避免。2.2 需要收集的四条信息打开终端先按顺序执行下面四组命令把你的环境底牌摸清楚python -c import sys; print(sys.version)python -c import torch; print(torch.__version__)python -c import torchvision; print(torchvision.__version__)pip show torchcodec第四步如果提示Package(s) not found: torchcodec说明确实没装。如果已经装了会看到 Version 字段把它记下来。这四条信息到手基本就能判断大部分问题了。2.3 动手验证 torchcodec 的真实状态接下来执行一个最关键的命令python -c import torchcodec; print(torchcodec.__version__)这里会暴露不同层次的问题如果报ModuleNotFoundError: No module named torchcodec说明根本没装进当前 Python 环境。如果报ImportError: libavcodec.so.58: cannot open shared object file之类说明装了扩展但系统没有对应的 FFmpeg 动态库。如果 import 成功那你遇到的很可能不是安装问题而是调用方式或者版本不匹配问题。把这个验证结果和你记下来的 torch/torchvision 版本放在一起一套完整的诊断信息就齐了。不要嫌这一步烦等到后面所有方案都能用这三条信息快速归位。2.4 三个层次报错形态速查表为了让你对号入座更快我整理了一个快速对照表报错形态报错示例根本原因修复方向ModuleNotFoundErrorNo module named torchcodec未安装安装匹配版本的 torchcodecImportError链接失败libavcodec.so: cannot open shared object fileFFmpeg 动态库缺失安装 FFmpeg 相关系统库RuntimeError调用时torchcodec is not available版本不匹配 / 安装损坏对齐版本矩阵后重装大多数网上求助帖里贴出的torchcodec is not available全文都能归类到上面任意一行。有了这个表排查方向就不会乱。3. 正确安装 torchcodec不同平台的最省事路径3.1 版本对应关系这是整个问题的主线torchcodec 不是独立存在的库它的版本号和 torch/torchvision 有明确的对应矩阵。以我目前掌握的信息大致规律是torch 版本torchvision 版本torchcodec 建议版本2.6.x0.20.x0.1.x2.7.x0.21.x0.2.x2.8.x0.22.x0.3.x注意这个对应关系会随着官方更新而变化强烈建议以 PyTorch 官网和 torchcodec 的 GitHub release 页面为准。安装前花 30 秒核对一下比反复试错划算得多。核心逻辑是先看你的 torch 版本是什么再选择对应矩阵里的 torchcodec 版本。而不是反过来装最新的 torchcodec再去迁就其他包。3.2 Linux 和 macOS 上的直装方案如果你的平台是 Linux 或 macOS事情简单很多。PyTorch 官方为这两个平台提供了预编译 wheel直接执行pip install torchcodec如果当前环境里同时存在多个 torch 候选源为了锁定版本建议加上 extra-index-urlpip install torchcodec0.2.0 --extra-index-url https://download.pytorch.org/whl/cpu装完再跑一遍第 2.3 节里的import torchcodec能打印版本号就说明基础安装成功了。macOS 用户还需要注意一点如果你用的是 Apple SiliconM 系列芯片要用 arm64 架构的 Python 环境避免 x86_64 兼容层带来的动态库匹配问题。最好的做法是用 Homebrew 的 Python或者在 conda 里创建一个osx-arm64的环境。3.3 Windows 上最值得尝试的路径Windows 是 torchcodec 问题的高发区。如果 PyPI 上有与你 torch 版本匹配的预编译 Windows wheel直接pip install torchcodec就行。但很多时候官方没有发布 Windows 的预编译包那就只能走源码编译。源码编译的前提是环境里具备编译工具链安装 Visual Studio Build Tools勾选使用 C 的桌面开发。安装 FFmpeg 开发库推荐用 vcpkggit clone https://github.com/microsoft/vcpkg cd vcpkg bootstrap-vcpkg.bat .\vcpkg install ffmpeg:x64-windows克隆 torchcodec 源码并执行编译git clone https://github.com/pytorch/torchcodec cd torchcodec python setup.py install这里要提醒一句如果你在 Windows 上没有特殊理由必须用原生 Python最省心的做法其实是装一套 WSL2直接在 WSL2 的 Linux 环境里用 pip 安装预编译包。关于 WSL2 的坑我在后面第 5 节专门说。3.4 虚拟环境隔离防止问题扩大不管哪个平台我都建议在独立的虚拟环境里操作不要直接在系统 Python 或 base conda 环境里来回折腾。torchcodec 对版本的敏感度很高一旦环境里已经装了一堆和 torch 有依赖关系的包重装 torchcodec 很容易连带升级 torch 本身然后引发连锁反应。我的习惯是每次都从零建一个 venvpython -m venv .venv source .venv/bin/activate pip install torch2.7.1 torchvision0.21.1 pip install torchcodec0.2.0这样环境干净出了问题直接删掉重建比在旧环境里反复修复快得多。4. 重灾区升级 torch 或 torchvision 后突然挂掉4.1 为什么升级顺序会踩坏 ABI这是我在实际项目中遇到最多的情况项目原本跑得好好的某天为了用某个新功能升级了 torch代码里 import torchvision.io 就开始报torchcodec is not available。原因其实不复杂。torchcodec 的预编译扩展在编译时针对特定版本的 torch 生成内部会链接到 PyTorch 的 C 符号。你升级 torch 之后这些符号的版本或布局可能变了旧的 torchcodec 扩展就加载不上或者加载后调用时崩溃。术语叫 ABI 不兼容通俗讲就是钥匙和锁不匹配了。解决逻辑很简单升级 torch 的同时必须配套升级 torchcodec。你不能只升一半。4.2 老代码里的 torchvision.io 兼容问题比 ABI 更隐蔽的问题是 API 行为变化。在 torchvision 0.20 之前torchvision.io.read_video有自己的实现返回的帧格式、数据类型、是否需要手动 permute 等等是固定的。切换到 torchcodec 之后部分场景下返回的数据语义会变化比如通道顺序、shape 维度的默认值甚至某些参数可能被标记为废弃。如果你是从旧项目升级过来的除了要装好 torchcodec还要去查一下当前 torchvision 版本对read_video等接口的文档确认参数和返回值有没有变化。否则你装好了所有依赖跑出来的数据却不符合预期那比报错还难排查因为程序不会报错只是结果悄悄变了。4.3 回滚与修复的实操顺序如果你已经升级了 torch现在想快速恢复按这个顺序操作先确认当前环境的 torch 版本python -c import torch; print(torch.__version__)。去 PyTorch 官网或 torchcodec 的 release 页面找到与当前 torch 版本匹配的 torchcodec 版本。强制指定版本重装pip install torchcodec对应版本重启 Python 解释器跑一个最小验证脚本用torchvision.io实际读一帧确认不再报错。如果你实在不想升级 torchcodec那就把 torch 降回原版本。但这里我强烈不建议在原环境里原地降级Python 包依赖的解析很容易把环境搞脏。正确做法是新建一个虚拟环境按已知的正常版本组合重新安装。我自己在项目里就是这么干的项目 root 下放一个requirements.txt里面把 torch、torchvision、torchcodec 的版本全部写死谁也不要动。跑任何新任务之前先核对这三者的版本组合再往下走。5. 部署阶段的两个隐形坑打包和 WSL25.1 PyInstaller 打包后为什么丢了 torchcodec如果你把视频处理脚本用 PyInstaller 打包成可执行文件很可能遇到一个现象本机运行没问题打包出来的 exe 在别的机器上却报torchcodec is not available。原因有两个层面。第一PyInstaller 的默认依赖收集逻辑不一定能识别 torchcodec 这种扩展模块的全部动态库尤其当它依赖的外部 .so/.dll 文件不在 Python 包根目录时。第二torchcodec 依赖 FFmpeg 动态库这些库在目标机器上不一定存在而打包时如果没显式收进去运行时就找不到。解决方式是在打包命令里显式收集pyinstaller --collect-all torchcodec --collect-all torchvision your_script.py如果还是报动态库缺失需要手动指定 FFmpeg 库的路径pyinstaller --add-binary/path/to/ffmpeg/lib/libavcodec.so:. your_script.py打包完成后务必在一台干净环境最好是没有安装 Python 和 FFmpeg 的机器或容器里测试一次不要在自己电脑上测完就认为万事大吉。5.2 WSL2 环境下 GPU 解码的连带陷阱再单独说说 WSL2。很多 Windows 用户为了绕开原生 Windows 的编译难题会转到 WSL2 下跑 Linux 版 torch。这个思路本身没问题但有一个非常常见的坑你在 Windows 里通过 pip 装的 torch/torchcodec 是 Windows 版WSL2 里却是 Linux 环境二者不能直接通用必须重新安装 Linux 版。如果你在 WSL2 里没装 NVIDIA 的 CUDA 驱动或者驱动不完整调用 GPU 硬件解码时会看到类似uva is not available的报错因为 CUDA 的统一虚拟地址UVA不可用硬件解码通路就起不来。这时候 torchcodec 本身的安装可能是正常的纯粹是 GPU 解码功能受限。我的排查建议是先用 CPU 模式验证 torchcodec 是否工作比如设置环境变量让解码走 CPUpython -c import torchcodec; print(import ok)如果 import 正常再跑一段实际视频解码脚本。CPU 能跑通而 GPU 失败说明问题不在 torchcodec而在 CUDA 视频解码链路。不要在这个方向上盲目重装 torchcodec。5.3 容器镜像里最容易缺的依赖容器部署是另一个高频坑。很多精简镜像比如python:3.11-slim里根本没有 FFmpeg 运行时而 torchcodec 又强依赖 FFmpeg 动态库import 时就会因为找不到 libavcodec 而失败报错内容依然和 is not available 有点关系。如果你用 Docker在 Dockerfile 里需要显式安装RUN apt-get update apt-get install -y ffmpeg libavcodec-extra或者是直接使用 PyTorch 官方镜像pytorch/pytorch里面通常已经带好了相关依赖。用自己裁剪的 Python 镜像时请一定把 FFmpeg 加进去这是我在容器环境里踩过最多次的坑。6. 辨认近亲报错别被网上相似错误带偏6.1 常见的 not available 错误速查你在网上搜这个报错时会发现大量标题里都带 is not available 但内容完全不同的错误。这些近亲报错很容易让人看串我列几个常见的方便你对号入座错误信息所属领域真实原因torchcodec is not availablePython / PyTorchtorchcodec 未安装、版本不匹配或动态库缺失The following packages are not available from current channelsCondaconda 源里没有你指定的包或版本换源或换版本解决swap used up but available still highLinux 资源监控这是对 available 内存指标望文生义不代表内存泄漏no supported authentication methods availableGit / SSHSSH 认证算法不匹配配置公钥或修改 ssh configxdb database not available数据库数据库实例未启动或连接配置错误看到没同样是 not available真实原因天差地别。排查的第一步永远是看报错来自哪个工具链然后顺藤摸瓜而不是看字面意思猜。6.2 判断标准你的报错源头在哪个环节我的判断顺序是先看它是pipy/conda 安装期报错还是程序运行期报错。安装期报错大概率是包不存在、渠道没有、版本号写错这一类运行期报错则要结合 import 链路来看torchcodec 只在 import 到调用视频解码这一段起作用。再进一步如果你在import torchvision.io时就报错多半是 torchcodec 装得不对如果你import torchcodec本身没问题但调用VideoDecoder时才崩那更可能是 FFmpeg 版本或 GPU 解码链路的问题。我把这个判断标准当作所有排查的出发点它能帮你省掉大量在论坛里来回翻帖子的时间。7.1 一份可直接抄的排查清单最后分享一个我在新环境里反复使用的检查序列直接照做就行确认 torch 版本。确认 torchvision 版本。确认是否安装 torchcodec以及版本号。执行import torchcodec观察是哪种报错形态。用torchvision.io实际解码一个视频文件确认功能正常。如果要在 Windows 或容器里跑额外确认 FFmpeg 动态库是否存在。建议把这个序列写成一个check_env.py脚本扔到项目里每次换机器或者升级依赖后跑一遍一分钟出结果比每次踩坑时再临时手敲命令强太多。7.2 我的几条个人体会被这个问题折腾了几次之后我养成了三个习惯。第一所有涉及视频处理的项目requirements.txt 里 torcv/torchvision/torchcodec 的版本号必须写死禁止无脑升级。第二Windows 上做视频解码任务优先 WSL2 Linux 环境不要和原生 Windows 的编译链死磕。第三遇到torchcodec is not available先花两分钟把环境信息收集齐再动包不能凭感觉卸载安装那样只会把环境越搞越乱。这个报错本身不难解决难的是一开始被人云亦云的重装大法带偏。只要你能把版本对应关系和环境状态搞清楚大多数情况下十分钟内就能恢复正常。