Dockerized Working Environment Example

🚀 The feature

Provide a working Dockerfile. Any local install with the install instructions is unreliable and crashes.

Motivation, pitch

As the title suggests. Currently installing torchcodec is plagued with nasty ffmpeg issues that are not easily resolved.

• #1146
• #1149
• #1131
• #1139
• #1355

Resolving to hacks and unreliable custom setups seems counterproductive. I have spent about two hours now attempting to install just this one package on Windows and on Linux.

Here is the line that is causing the issue in my case:

        torchaudio.save(save_path, wav.to(torch.float32).cpu(), 48000)

Here is the error output from code:

  File "/app/.venv/lib/python3.10/site-packages/torchcodec/_internally_replaced_utils.py", line 111, in load_torchcodec_shared_libraries
    raise RuntimeError(
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, and we attempt to load libtorchcodec
             for each of those versions. Errors for versions not installed on
             your system are expected; only the error for your installed FFmpeg
             version is relevant. On Windows, ensure you've installed the
             "full-shared" version which ships DLLs.
          2. The PyTorch version (2.10.0+cu128) 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:
Traceback (most recent call last):
  File "/app/.venv/lib/python3.10/site-packages/torch/_ops.py", line 1442, in load_library
    ctypes.CDLL(path)
  File "/opt/conda/lib/python3.10/ctypes/__init__.py", line 374, in __init__
    self._handle = _dlopen(self._name, mode)
OSError: /app/.venv/lib/python3.10/site-packages/torchcodec/libtorchcodec_core8.so: undefined symbol: torch_dtype_float4_e2m1fn_x2

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

Traceback (most recent call last):
  File "/app/.venv/lib/python3.10/site-packages/torchcodec/_internally_replaced_utils.py", line 93, in load_torchcodec_shared_libraries
    torch.ops.load_library(core_library_path)
  File "/app/.venv/lib/python3.10/site-packages/torch/_ops.py", line 1444, in load_library
    raise OSError(f"Could not load this library: {path}") from e
OSError: Could not load this library: /app/.venv/lib/python3.10/site-packages/torchcodec/libtorchcodec_core8.so

FFmpeg version 7:
Traceback (most recent call last):
  File "/app/.venv/lib/python3.10/site-packages/torch/_ops.py", line 1442, in load_library
    ctypes.CDLL(path)
  File "/opt/conda/lib/python3.10/ctypes/__init__.py", line 374, in __init__
    self._handle = _dlopen(self._name, mode)
OSError: libavutil.so.59: 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):
  File "/app/.venv/lib/python3.10/site-packages/torchcodec/_internally_replaced_utils.py", line 93, in load_torchcodec_shared_libraries
    torch.ops.load_library(core_library_path)
  File "/app/.venv/lib/python3.10/site-packages/torch/_ops.py", line 1444, in load_library
    raise OSError(f"Could not load this library: {path}") from e
OSError: Could not load this library: /app/.venv/lib/python3.10/site-packages/torchcodec/libtorchcodec_core7.so

FFmpeg version 6:
Traceback (most recent call last):
  File "/app/.venv/lib/python3.10/site-packages/torch/_ops.py", line 1442, in load_library
    ctypes.CDLL(path)
  File "/opt/conda/lib/python3.10/ctypes/__init__.py", line 374, in __init__
    self._handle = _dlopen(self._name, mode)
OSError: libavutil.so.58: 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):
  File "/app/.venv/lib/python3.10/site-packages/torchcodec/_internally_replaced_utils.py", line 93, in load_torchcodec_shared_libraries
    torch.ops.load_library(core_library_path)
  File "/app/.venv/lib/python3.10/site-packages/torch/_ops.py", line 1444, in load_library
    raise OSError(f"Could not load this library: {path}") from e
OSError: Could not load this library: /app/.venv/lib/python3.10/site-packages/torchcodec/libtorchcodec_core6.so

FFmpeg version 5:
Traceback (most recent call last):
  File "/app/.venv/lib/python3.10/site-packages/torch/_ops.py", line 1442, in load_library
    ctypes.CDLL(path)
  File "/opt/conda/lib/python3.10/ctypes/__init__.py", line 374, in __init__
    self._handle = _dlopen(self._name, mode)
OSError: libavutil.so.57: 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):
  File "/app/.venv/lib/python3.10/site-packages/torchcodec/_internally_replaced_utils.py", line 93, in load_torchcodec_shared_libraries
    torch.ops.load_library(core_library_path)
  File "/app/.venv/lib/python3.10/site-packages/torch/_ops.py", line 1444, in load_library
    raise OSError(f"Could not load this library: {path}") from e
OSError: Could not load this library: /app/.venv/lib/python3.10/site-packages/torchcodec/libtorchcodec_core5.so

FFmpeg version 4:
Traceback (most recent call last):
  File "/app/.venv/lib/python3.10/site-packages/torch/_ops.py", line 1442, in load_library
    ctypes.CDLL(path)
  File "/opt/conda/lib/python3.10/ctypes/__init__.py", line 374, in __init__
    self._handle = _dlopen(self._name, mode)
OSError: libavutil.so.56: 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):
  File "/app/.venv/lib/python3.10/site-packages/torchcodec/_internally_replaced_utils.py", line 93, in load_torchcodec_shared_libraries
    torch.ops.load_library(core_library_path)
  File "/app/.venv/lib/python3.10/site-packages/torch/_ops.py", line 1444, in load_library
    raise OSError(f"Could not load this library: {path}") from e
OSError: Could not load this library: /app/.venv/lib/python3.10/site-packages/torchcodec/libtorchcodec_core4.so
[end of libtorchcodec loading traceback].

Here is a starting point which is causing the error:

FROM nvidia/cuda:12.8.2-runtime-ubuntu22.04

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y --no-install-recommends \
    python3.10 \
    python3.10-venv \
    python3-pip \
    wget \
    curl \
    libsndfile1 \
    git \
 && rm -rf /var/lib/apt/lists/*

# Install Miniforge - conda-forge by default, no Anaconda ToS.
ENV CONDA_DIR=/opt/conda
RUN wget -q https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -O /tmp/miniforge.sh \
 && bash /tmp/miniforge.sh -b -p $CONDA_DIR \
 && rm /tmp/miniforge.sh
ENV PATH=$CONDA_DIR/bin:$PATH

RUN conda install -y python=3.10 ffmpeg \
 && conda clean -afy

# Make conda's FFmpeg shared libraries visible to torchcodec at runtime
ENV LD_LIBRARY_PATH=$CONDA_DIR/lib:$LD_LIBRARY_PATH

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app

# Copy dependency manifests first for better layer caching
COPY pyproject.toml ./

# Sync all dependencies except the package itself.
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --no-install-project

# Copy source and examples
COPY src/ ./src/
COPY assets/ ./assets/
COPY examples/ ./examples/

RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync

Start from the Dockerfile shown in the issue and compare its dependency setup with pyproject.toml, then inspect the source and examples copied into the image. Build the image and exercise the shown torchaudio.save call; done means the documented Docker environment installs successfully and avoids the reported torchcodec and FFmpeg loading failure.