Cannot load torchcodec

Beginners
4

When using Python in a Windows environment, particularly with venv, conda, or Jupyter, DLL errors occasionally occur because the Windows PATH environment variable isn’t used to locate DLLs…

You’re hitting a Windows DLL-loading problem for TorchCodec plus a possible version or kernel mismatch. The error text in your HF thread shows TorchCodec probing core8→7→6→5→4 and failing to bind FFmpeg. That pattern means the FFmpeg runtime DLLs are not visible to the Python process or the Torch↔TorchCodec pair is mismatched. (Hugging Face Forums)

Causes

  • Python ≥3.8 on Windows does not use PATH for dependent DLLs. You must add the FFmpeg DLL folder to the current process with os.add_dll_directory(...) before importing torchcodec. Adding PATH via os.system("set PATH=...") does not affect the running process. Order is also tricky if you add multiple directories. (Python documentation)
  • FFmpeg major not supported for your OS. TorchCodec supports FFmpeg 4–7 on all platforms. FFmpeg 8 is supported on Mac/Linux. Windows requires 4–7 today. (GitHub)
  • Torch/TorchCodec mismatch. Use the matrix: TorchCodec 0.8 ↔ torch 2.9. TorchCodec 0.7 ↔ torch 2.8. Python 3.10–3.13 for 0.8. Nightly/RC combos often fail to load. (GitHub)
  • Wrong Jupyter kernel or mixed environments. Installing in one venv and running another reproduces the same error. (Hugging Face Forums)
  • On macOS only: Homebrew FFmpeg layouts have caused incompatibility; conda-forge FFmpeg works. Not your Windows case, but relevant if you switch machines. (GitHub)

Solutions

1) Keep venv + conda FFmpeg. Add the DLL dir correctly.

Put this at the very top of your notebook, before any torch or torchcodec import.

# Use Python's Windows DLL API (3.8+). Add the folder that holds avcodec/avformat/avutil DLLs.
# TorchCodec README + version matrix: https://github.com/pytorch/torchcodec  (docs)
# Torchaudio FFmpeg install notes on Windows: https://docs.pytorch.org/audio/main/installation.html  (install tips)

from pathlib import Path
import os, sys

ffmpeg_dll_dir = Path(r"C:\Users\majh0\miniconda3\Library\bin")  # adjust if your conda root differs
assert ffmpeg_dll_dir.exists(), ffmpeg_dll_dir
os.add_dll_directory(str(ffmpeg_dll_dir))  # Python 3.8+ DLL search

import torch, torchcodec, platform, subprocess
print("exe:", sys.executable)
print("torch", torch.__version__, "torchcodec", torchcodec.__version__, "py", platform.python_version())
subprocess.run(["ffmpeg", "-version"], check=True)

Background: os.add_dll_directory was added in 3.8 for this exact scenario. It affects the current process and is the supported way to expose dependency DLLs. Adding to PATH in a child shell does not help. Avoid adding multiple DLL dirs since search order is unspecified. (Python documentation)

2) Pin a supported version set.

Pick one:

# CPU
pip install "torch==2.9.*" "torchcodec==0.8.*"
# or
# pip install "torch==2.8.*" "torchcodec==0.7.*"

Reason: TorchCodec pairs with specific torch versions. The README documents 0.8↔2.9 and 0.7↔2.8. (GitHub)

3) Ensure FFmpeg 4–7 and use a shared build.

# In an Anaconda/Miniconda prompt
conda install -y -c conda-forge "ffmpeg<8"
# DLLs land in ...\miniconda3\Library\bin  (the dir you pass to os.add_dll_directory)

Conda-forge FFmpeg provides the needed Windows runtime DLLs. (PyTorch Documentation)

4) Make sure Jupyter is using the same interpreter.

# inside your venv
pip install ipykernel
python -m ipykernel install --user --name asrvenv --display-name "Python (asrvenv)"
# then select "Python (asrvenv)" in Jupyter

This prevents importing from a different Python that lacks your fixes. (Hugging Face Forums)

5) One-env fallback to avoid mixing tools.

If mixing venv + conda is awkward, put everything in one conda env:

conda create -n asr python=3.10 -y
conda activate asr
conda install -c conda-forge "ffmpeg<8"
pip install "torch==2.9.*" "torchcodec==0.8.*"
python -c "import torch, torchcodec; print(torch.__version__, torchcodec.__version__)"

Windows support is marked experimental, and the README recommends conda for CUDA and Windows cases. (GitHub)

6) Temporary workaround if you must proceed.

Preconvert MP3 → WAV with FFmpeg and feed WAV to the pipeline. This avoids MP3 decoding, but it does not fix DLL loading.

ffmpeg -i input.mp3 -ar 16000 -ac 1 -y input.wav

Use only while you stabilize the environment. (Hugging Face Forums)

Why your specific repro keeps failing

  • You set PATH in a child shell (os.system("set PATH=...")). The current Python process did not inherit it. Python ≥3.8 also ignores PATH for dependent DLLs. Use os.add_dll_directory and the exact Miniconda path that actually contains avcodec-*.dll. (Python documentation)
  • Your HF post shows the expected TorchCodec probe sequence and a venv site-packages path. That confirms a loader failure, not a missing Python package. (Hugging Face Forums)
  • If you added more than one DLL directory, search order is unspecified. Keep only the conda Library\bin. (Discussions on Python.org)

Quick checklist

  • torch==2.9.*, torchcodec==0.8.*, Python 3.10–3.13. (GitHub)
  • conda install -c conda-forge "ffmpeg<8" on Windows. DLLs in ...\miniconda3\Library\bin. (PyTorch Documentation)
  • Top cell calls os.add_dll_directory(r"...\miniconda3\Library\bin") before importing torchcodec. (Python documentation)
  • Jupyter kernel points to the same venv. (Hugging Face Forums)

Context and background

  • TorchCodec loads FFmpeg at runtime. It supports FFmpeg 4–7 across platforms and 8 on Mac/Linux. The README also lists the torch↔torchcodec compatibility table. Windows is labeled experimental. (GitHub)
  • Many similar Windows reports reduce to DLL discovery or mismatched versions. Torchaudio docs endorse conda-forge FFmpeg to simplify discovery on Windows. (PyTorch Documentation)

Supplemental references

Core docs

  • TorchCodec README: support matrix, FFmpeg majors, Windows notes. Useful for exact pins. (GitHub)
  • Torchaudio install page: FFmpeg on Windows via conda-forge. Good for verifying FFmpeg placement. (PyTorch Documentation)

Related issues

  • Homebrew FFmpeg incompatibility on macOS. Use conda-forge FFmpeg instead. (GitHub)
  • Python 3.8+ DLL behavior and os.add_dll_directory. Explains why editing PATH is insufficient and why order is unspecified. (Python documentation)