{"id":5175,"library":"decord2","title":"Decord2","description":"Decord2 is a high-performance, efficient video decoding and loading library for deep learning research, featuring smart shuffling, random frame access, GPU acceleration, and seamless integration with popular frameworks. It is currently at version 3.3.0 and has a frequent release cadence, with multiple releases in the past year.","status":"active","version":"3.3.0","language":"en","source_language":"en","source_url":"https://github.com/johnnynunez/decord2","tags":["video","deep learning","loader","gpu","ffmpeg","audio","video processing"],"install":[{"cmd":"pip install decord2","lang":"bash","label":"CPU-only installation"},{"cmd":"pip install decord2[cu130] # Example for CUDA 13.0, check available wheels for your CUDA version","lang":"bash","label":"GPU (CUDA) installation via wheels (if available)"},{"cmd":"git clone --recursive https://github.com/johnnynunez/decord2.git\ncd decord2\nmkdir build && cd build\ncmake .. -DUSE_CUDA=ON -DCMAKE_BUILD_TYPE=Release # Or -DUSE_CUDA=0 for CPU\nmake\ncd ../python\npip install .","lang":"bash","label":"Source installation (required for custom GPU setups or specific FFmpeg versions)"}],"dependencies":[{"reason":"Required for the library itself","package":"python","optional":false},{"reason":"Core dependency for array operations on frames and audio","package":"numpy","optional":false},{"reason":"Underlying video decoding backend. Specific version required for source builds (e.g., 8.0 for v2.0.0+).","package":"ffmpeg","optional":true},{"reason":"Required for GPU acceleration via source builds. Specific version required (e.g., 13.x for v2.0.0+).","package":"cuda","optional":true}],"imports":[{"note":"Main class for video file access","symbol":"VideoReader","correct":"from decord import VideoReader"},{"note":"Context for CPU processing","symbol":"cpu","correct":"from decord import cpu"},{"note":"Context for GPU processing (requires GPU-enabled installation)","symbol":"gpu","correct":"from decord import gpu"}],"quickstart":{"code":"import os\nimport numpy as np\nfrom decord import VideoReader, cpu\n\n# Create a dummy video file for demonstration\n# In a real scenario, you would have an actual video file\ndummy_video_path = 'dummy_video.mp4'\n# For a real application, ensure ffmpeg is installed and generate a simple video:\n# import subprocess\n# try:\n#     subprocess.run(['ffmpeg', '-f', 'lavfi', '-i', 'testsrc=s=1280x720:r=30', '-vframes', '30', dummy_video_path], check=True)\n# except FileNotFoundError:\n#     print('FFmpeg not found. Cannot create dummy video.')\n#     print('Please replace \"dummy_video.mp4\" with a path to an actual video file.')\n#     exit()\n\n# Placeholder for a real video file\n# Assume 'your_video.mp4' exists or create one as above\nvideo_file = 'your_video.mp4' # Replace with your video file path\n\n# Initialize VideoReader with CPU context\n# Use 'cpu(0)' for the first CPU context\n# For GPU, use 'gpu(0)' if installed with GPU support\ntry:\n    vr = VideoReader(video_file, ctx=cpu(0))\n    print(f\"Successfully opened video: {video_file}\")\n    print(f\"Number of frames: {len(vr)}\")\n\n    # Access a single frame by index\n    frame_0 = vr[0].asnumpy()\n    print(f\"Shape of first frame: {frame_0.shape}\") # (H, W, C)\n\n    # Access a batch of frames (e.g., frames 10 to 20)\n    frames_batch = vr[10:20].asnumpy()\n    print(f\"Shape of frames batch: {frames_batch.shape}\") # (N, H, W, C)\n\n    # Access frames at specific indices\n    random_frames = vr.get_batch([5, 15, 25]).asnumpy()\n    print(f\"Shape of random frames batch: {random_frames.shape}\") # (N, H, W, C)\n\nexcept Exception as e:\n    print(f\"Error processing video: {e}\")\n    print(\"Please ensure 'your_video.mp4' exists and is a valid video file.\")\n    print(\"You may also need to install FFmpeg on your system if installing from source.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure 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`).","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"For 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.","message":"Achieving 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`).","severity":"gotcha","affected_versions":"All"},{"fix":"If 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.","message":"When 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure 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.","message":"Videos 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.","severity":"gotcha","affected_versions":"<=0.3.5 (original decord), potentially affects decord2 depending on fixes incorporated."}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}