Install & Compatibility
Where this runs
tested against v0.0.0.dev0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.000s · 40MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VideoDecoder
✓ import torchcodec
✗ from torchcodec import VideoDecoder
This quickstart demonstrates how to initialize a `VideoDecoder` for a given video file path. It prints basic video metadata and provides commented-out lines for decoding frames. Remember to replace the placeholder `video_path` with an actual video file on your system.
import torchcodec
from torchcodec.decoders import VideoDecoder
import os
# Replace 'path/to/your/video.mp4' with the actual path to your video file.
# For demonstration, we use an environment variable or a placeholder.
video_path = os.environ.get('TORCHCODEC_DEMO_VIDEO', 'path/to/your/video.mp4')
try:
decoder = VideoDecoder(video_path)
print(f"VideoDecoder initialized for: {video_path}")
print(f"Video width: {decoder.width}")
print(f"Video height: {decoder.height}")
# Uncomment the following lines to decode frames:
# frames = decoder.next_chunk(num_frames=10)
# print(f"Decoded 10 frames with shape: {frames.shape}")
except FileNotFoundError:
print(f"Error: Video file not found at '{video_path}'. Please replace with a valid path.")
except Exception as e:
print(f"An error occurred during decoder initialization or usage: {e}")
print("\nTo decode frames, ensure a valid video_path is provided and uncomment the 'frames = decoder.next_chunk...' line.")
Debug
Known issues
gotchaTorchCodec versions are often tied to specific PyTorch versions. Installing an incompatible PyTorch version can lead to runtime errors or unexpected behavior.fixAlways check the official TorchCodec release notes or documentation for the compatible PyTorch version. For example, v0.11.0 is compatible with torch 2.10.
affects: All versions
gotchaWhen using the 'beta' CUDA backend (available from v0.8.0 onwards) on certain systems, a hard dependency on `libnvcuvid.so` might cause import issues if the library is not present.fixThis issue was largely resolved in v0.8.1. Ensure you are on v0.8.1 or later. If using the 'beta' backend, make sure your CUDA installation is complete and `libnvcuvid.so` is accessible.
affects: 0.8.0
gotchaUsers on Windows might encounter issues where FFmpeg cannot be found by TorchCodec, even if installed.fixUpgrade to TorchCodec v0.9.1 or later. Ensure FFmpeg is correctly installed and its binaries are added to your system's PATH environment variable.
affects: Prior to 0.9.1, particularly on Windows.
gotchaFor GPU decoding on Windows, `pip install` might not always provide the necessary CUDA-enabled binaries directly. The `conda-forge` channel often provides a more stable setup for GPU support.fixConsider installing TorchCodec via `conda install torchcodec -c conda-forge` if you are on Windows and plan to use GPU acceleration.
affects: All versions, specifically for Windows GPU users.
gotchaThe faster CUDA decoder backend, introduced as 'beta' in v0.8.0, needs to be explicitly enabled for improved performance.fixCall `torchcodec.decoders.set_cuda_backend("beta")` before initializing your `VideoDecoder` to leverage the performance improvements. affects: 0.8.0 and later when using CUDA decoding.
Upgrade
Version history
0.16.0latest on PyPI · released Aug 13, 2026
Audit
Dependencies
torchrequiredCore PyTorch tensor integration; specific PyTorch versions are compatible with specific TorchCodec releases.
ffmpegrequiredBackend for video and audio processing; must be installed and accessible in the system PATH.