Install & Compatibility
Where this runs
tested against v3.4.0 · 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
py 3.9
✕ no_wheel
✕ no_wheel
158MB installed
● package 158MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VideoReader
✓ from decord import VideoReader
Main class for video file access
cpu
✓ from decord import cpu
Context for CPU processing
gpu
✓ from decord import gpu
Context for GPU processing (requires GPU-enabled installation)
Initialize a `VideoReader` to load frames from a video file. This example demonstrates accessing individual frames, slicing a batch of frames, and retrieving frames by specific indices. It defaults to CPU context but can be switched to GPU if the library is installed with CUDA support.
import os
import numpy as np
from decord import VideoReader, cpu
# Create a dummy video file for demonstration
# In a real scenario, you would have an actual video file
dummy_video_path = 'dummy_video.mp4'
# For a real application, ensure ffmpeg is installed and generate a simple video:
# import subprocess
# try:
# subprocess.run(['ffmpeg', '-f', 'lavfi', '-i', 'testsrc=s=1280x720:r=30', '-vframes', '30', dummy_video_path], check=True)
# except FileNotFoundError:
# print('FFmpeg not found. Cannot create dummy video.')
# print('Please replace "dummy_video.mp4" with a path to an actual video file.')
# exit()
# Placeholder for a real video file
# Assume 'your_video.mp4' exists or create one as above
video_file = 'your_video.mp4' # Replace with your video file path
# Initialize VideoReader with CPU context
# Use 'cpu(0)' for the first CPU context
# For GPU, use 'gpu(0)' if installed with GPU support
try:
vr = VideoReader(video_file, ctx=cpu(0))
print(f"Successfully opened video: {video_file}")
print(f"Number of frames: {len(vr)}")
# Access a single frame by index
frame_0 = vr[0].asnumpy()
print(f"Shape of first frame: {frame_0.shape}") # (H, W, C)
# Access a batch of frames (e.g., frames 10 to 20)
frames_batch = vr[10:20].asnumpy()
print(f"Shape of frames batch: {frames_batch.shape}") # (N, H, W, C)
# Access frames at specific indices
random_frames = vr.get_batch([5, 15, 25]).asnumpy()
print(f"Shape of random frames batch: {random_frames.shape}") # (N, H, W, C)
except Exception as e:
print(f"Error processing video: {e}")
print("Please ensure 'your_video.mp4' exists and is a valid video file.")
print("You may also need to install FFmpeg on your system if installing from source.")
Debug
Known issues
breakingVersion 2.0.0 introduced significant updates to underlying dependencies, including FFmpeg 8.0 (from 7.x) and CUDA 13.x (from 12.x). Projects building from source or with specific local FFmpeg/CUDA installations may encounter build failures or runtime issues if not updated to compatible versions.fixEnsure your FFmpeg and CUDA installations are compatible with Decord2 v2.0.0 and later. For source builds, explicitly specify paths or versions during `cmake` configuration (e.g., `-DFFMPEG_DIR=/path/to/ffmpeg`).
affects: >=2.0.0
gotchaAchieving GPU acceleration requires a source build of Decord2 with CUDA enabled, which can be complex due to dependency linking (e.g., `libnvcuvid.so` on Linux). Pre-built wheels for PyPI are typically CPU-only unless specific CUDA versions are explicitly indicated (e.g., `decord2-cu130`).fixFor GPU, follow the detailed source build instructions in the GitHub README, ensuring all system dependencies (FFmpeg, CUDA toolkit, CMake) are correctly installed and linked. Verify `libnvcuvid.so` is discoverable or explicitly linked if errors occur.
affects: All
gotchaWhen using `decord` (the original project, which `decord2` is forked from) with deep learning frameworks that employ multiprocessing data loaders (e.g., PyTorch `DataLoader` with `num_workers > 0`), users have reported issues with the process hanging or deadlocking. This indicates potential concurrency issues in the underlying C++ components.fixIf experiencing hangs with multiprocessing, try setting `num_workers=0` in your data loader to isolate the issue. Investigate if the specific version of Decord2 has known patches or workarounds for multithreading stability, or consider using alternative video loading strategies within your data pipeline.
affects: All
gotchaVideos with imprecise or corrupted metadata (e.g., incorrect duration) can lead to issues with accurate frame counting or random access operations, potentially yielding incorrect frames or unexpected behavior, especially in older versions of the underlying Decord library.fixEnsure video files have correct and complete metadata if possible. Decord aims for robustness, but problematic files may still cause issues. Validate frame content, especially when performing random access or dealing with videos from unreliable sources.
affects: <=0.3.5 (original decord), potentially affects decord2 depending on fixes incorporated.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'decord'
The `decord2` library, or its predecessor `decord`, is not installed in your current Python environment or the import statement uses the older 'decord' name.
fixEnsure you have installed the correct package using `pip install decord2`. If your code was written for the older `decord` library and you are using `decord2`, update your import statements from `import decord` to `import decord2` or install `decord` if that is intended.
ERROR: Could not find a version that satisfies the requirement decord2 (from versions: none) ERROR: No matching distribution found for decord2
This typically occurs when `pip` cannot find a pre-built wheel for your specific operating system, Python version, or architecture (e.g., ARM-based systems, or when seeking a GPU-enabled version that isn't provided as a pre-built wheel on PyPI).
fixFor CPU-only versions, ensure your Python version and OS are supported. For GPU acceleration, pre-built PyPI wheels for `decord2` are generally CPU-only. You will need to build `decord2` from source, explicitly enabling CUDA and ensuring all system dependencies (like FFmpeg, CUDA Toolkit, CMake) are correctly installed and configured.
Python process hangs or deadlocks without error messages when using PyTorch DataLoader with num_workers > 0
The underlying C++ components of Decord (and by extension, Decord2) can encounter concurrency issues or resource contention when used with multiprocessing data loaders, leading to hangs.
fixTry setting `num_workers=0` in your PyTorch `DataLoader` to see if the issue is resolved. If it is, consider alternative video loading strategies or investigate specific patches/workarounds for multithreading stability in the Decord2 GitHub repository.
OSError: libnvcuvid.so: cannot open shared object file: No such file or directory (or similar FFmpeg/CUDA library linking errors)
This error occurs when a GPU-enabled build of `decord2` cannot find the necessary NVIDIA video decoding libraries (`libnvcuvid.so`) or other CUDA/FFmpeg shared libraries at runtime or during the build process.
fixEnsure the CUDA Toolkit is correctly installed and its libraries are in your system's library path (`LD_LIBRARY_PATH` on Linux). For `libnvcuvid.so`, you may need to manually locate it (e.g., `ldconfig -p | grep libnvcuvid`) and link it to your CUDA installation's `lib64` directory. When building from source, explicitly specify paths to FFmpeg (`-DFFMPEG_DIR=/path/to/ffmpeg`) and CUDA (`-DUSE_CUDA=/path/to/cuda`) during `cmake` configuration.
ModuleNotFoundError: No module named 'decord2'
The `decord2` package is installed via `pip install decord2`, but the primary module to import within Python code is named `decord`, not `decord2`.
fixAfter installing the package with `pip install decord2`, import it using `import decord` or `from decord import VideoReader`.
Upgrade
Version history
3.4.0latest on PyPI · released May 30, 2026
Audit
Dependencies
pythonrequiredRequired for the library itself
numpyrequiredCore dependency for array operations on frames and audio
ffmpegoptionalUnderlying video decoding backend. Specific version required for source builds (e.g., 8.0 for v2.0.0+).
cudaoptionalRequired for GPU acceleration via source builds. Specific version required (e.g., 13.x for v2.0.0+).