Could not load libtorchcodec (fix)

Since torchaudio 2.9, torchaudio.load decodes through TorchCodec, and it often fails with RuntimeError: Could not load libtorchcodec ("TorchCodec is not installed correctly"). We reproduced the two common causes: no FFmpeg shared libraries, and a torchcodec built for a different torch. Each has a different error and fix.

1. The test

A one-second WAV made with the standard library:

import math, struct, wave
with wave.open("tone.wav", "wb") as w:          # 1 s, 16 kHz, mono 440 Hz
    w.setnchannels(1); w.setsampwidth(2); w.setframerate(16000)
    w.writeframes(b"".join(struct.pack("<h", int(8000 * math.sin(2 * math.pi * 440 * i / 16000))) for i in range(16000)))
print("wrote tone.wav")

wrote tone.wav

The script that loads it:

import torch, torchaudio, torchcodec
print("torch", torch.__version__, "| torchaudio", torchaudio.__version__, "| torchcodec", torchcodec.__version__)
waveform, sr = torchaudio.load("tone.wav")
print(waveform.shape, sr)

2. Error A: "Could not load libtorchcodec" = FFmpeg missing

torch 2.9.0, torchaudio 2.9.0 and the matching torchcodec 0.9.1 (CPU wheels), on a machine with no FFmpeg:

Traceback (most recent call last):
  ...
RuntimeError: Could not load libtorchcodec. Likely causes:
          1. FFmpeg is not properly installed in your environment. We support
             versions 4, 5, 6, 7, and 8. On Windows, ensure you've installed
             the "full-shared" version which ships DLLs.
          2. The PyTorch version (2.9.0+cpu) is not compatible with
             this version of TorchCodec. Refer to the version compatibility
             table:
             https://github.com/pytorch/torchcodec?tab=readme-ov-file#installing-torchcodec.
          3. Another runtime dependency; see exceptions below.
        The following exceptions were raised as we tried to load libtorchcodec:
        
[start of libtorchcodec loading traceback]
FFmpeg version 8: Could not load this library: .../site-packages/torchcodec/libtorchcodec_core8.so
FFmpeg version 7: Could not load this library: .../site-packages/torchcodec/libtorchcodec_core7.so
FFmpeg version 6: Could not load this library: .../site-packages/torchcodec/libtorchcodec_core6.so
FFmpeg version 5: Could not load this library: .../site-packages/torchcodec/libtorchcodec_core5.so
FFmpeg version 4: Could not load this library: .../site-packages/torchcodec/libtorchcodec_core4.so
[end of libtorchcodec loading traceback].

The versions match here, so cause 2 in the message is not it. Each libtorchcodec_coreN.so fails because the FFmpeg shared libraries (libavcodec, libavutil, …) are not found. TorchCodec does not bundle FFmpeg.

3. Fix: install FFmpeg 4–8 shared libraries

• Debian/Ubuntu: sudo apt install ffmpeg
• macOS: brew install ffmpeg
• conda: conda install -c conda-forge "ffmpeg<8"
• Windows: a "full-shared" FFmpeg build (the message says so) on PATH

We had no root, so we used conda-forge FFmpeg 7 in a micromamba prefix and pointed the loader at it:

micromamba create -p ./ff -c conda-forge "ffmpeg=7"
LD_LIBRARY_PATH=./ff/lib python c1.py

torch 2.9.0+cpu | torchaudio 2.9.0+cpu | torchcodec 0.9.1
torch.Size([1, 16000]) 16000

Same venv, same torchcodec, only FFmpeg added: it loads.

4. Error B: OSError on libtorchcodec_image.so = wrong torchcodec for your torch

torchcodec declares no torch dependency, so pip install torchcodec pulls the newest release whatever torch you have. torchcodec 0.17.0 on torch 2.9.0:

Traceback (most recent call last):
  ...
OSError: libnvrtc.so.13: cannot open shared object file: No such file or directory

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  ...
OSError: Could not load this library: .../site-packages/torchcodec/libtorchcodec_image.so

This fails before FFmpeg is even looked for. The inner error varied between our installs (libnvrtc.so.13 missing in this one, undefined symbol: torch_list_size in an earlier one); the outer OSError: Could not load this library: …libtorchcodec_image.so was the same.

5. Fix: install the torchcodec that matches your torch

From the TorchCodec README compatibility table:

python -c "import torch; print(torch.__version__)"
pip install "torchcodec==0.9.*"   # for torch 2.9

After that you get Error A or success, depending on FFmpeg.

6. Workaround: load audio without torchcodec

For plain WAV/FLAC/OGG, pip install soundfile (ships libsndfile) and build the same (channels, frames) tensor:

import soundfile as sf, torch
data, sr = sf.read("tone.wav", dtype="float32", always_2d=True)
waveform = torch.from_numpy(data.T)        # (channels, frames), like torchaudio.load
print(waveform.shape, sr)

torch.Size([1, 16000]) 16000

Related: torchaudio has no attribute info · torchaudio has no attribute AudioMetaData · No module named torchaudio.backend · No module named torchaudio.io · libtorchaudio.so undefined symbol

Written with AI assistance. Measured on 2026-10-24 on Linux with CPython 3.11.17, CPU wheels of torch/torchaudio 2.9.0, torchcodec 0.9.1 and 0.17.0, conda-forge FFmpeg 7. Output pasted unedited except shortened site-packages paths and cut tracebacks. PlainTables is our extension; torchcodec, FFmpeg and soundfile are free.