Install & Compatibility
Where this runs
tested against v1.1.11 · 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.920 runs
installs and imports cleanly · install 0.0s · import 3.005s · 253MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.9s · import 2.825s · 244MB
252MB installed
● package 252MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
skvideo.io
✓ import skvideo.io
For video reading and writing functionalities.
skvideo.datasets
✓ import skvideo.datasets
Provides access to test datasets.
skvideo.utils
✓ import skvideo.utils
For various utility functions.
This quickstart demonstrates how to load a sample video from `skvideo.datasets` into a NumPy array using `skvideo.io.vread`. It also shows how to inspect the video's shape and data type. For large videos, `skvideo.io.vreader` is recommended for memory efficiency.
import skvideo.io
import skvideo.datasets
import numpy as np
# Get a sample video filename
filename = skvideo.datasets.bigbuckbunny()
# Read the video into a NumPy array
# For larger videos, consider skvideo.io.vreader for frame-by-frame processing
videodata = skvideo.io.vread(filename, num_frames=10) # Read first 10 frames for quick test
print(f"Video data shape: {videodata.shape}")
print(f"Data type: {videodata.dtype}")
# Example: Convert to grayscale (if not already)
if videodata.shape[-1] == 3:
# Simple average for grayscale, or use more advanced conversion
grayscale_video = np.mean(videodata, axis=-1, keepdims=True).astype(videodata.dtype)
print(f"Grayscale video shape: {grayscale_video.shape}")
# To prevent 'module numpy has no attribute float' errors with recent NumPy,
# you might need this workaround before importing anything that uses it if it breaks:
# import numpy
# numpy.float = numpy.float64
# numpy.int = numpy.int_
Debug
Known issues
breakingIncompatibility with recent NumPy versions (>=1.20, especially >=1.24) due to the removal of `numpy.float` and `numpy.int` aliases, causing `AttributeError`.fixDowngrade NumPy to a version prior to 1.20 (e.g., `pip install numpy==1.19.5`) or apply a monkey-patch before `skvideo` imports: `import numpy; numpy.float = numpy.float64; numpy.int = numpy.int_`.
affects: scikit-video <= 1.1.11 with NumPy >= 1.20
gotchaOlder installations of `scikit-video` might have used the package name `sk-video`, leading to import conflicts or unexpected behavior if `scikit-video` is installed afterwards.fixEnsure previous installations of `sk-video` are uninstalled before installing `scikit-video`: `pip uninstall sk-video` then `pip install scikit-video`.
affects: < 1.1.10
gotchaThe `skvideo.io.vread` function loads the entire video into memory. For large video files, this can lead to `MemoryError` or system instability.fixFor large videos, use `skvideo.io.vreader` which returns a generator, allowing frame-by-frame processing and significantly reducing memory footprint.
affects: All versions
gotcha`skvideo.io.vread` can be significantly slower if `num_frames` is not explicitly provided, especially for certain video types, as it may perform multiple passes to auto-detect video properties.fixAlways specify `num_frames` when reading only a subset of frames (e.g., `skvideo.io.vread(filename, num_frames=N)`).
affects: All versions
gotchaRequires external `ffmpeg` or `libav` binaries to be installed and available in the system's PATH. Without them, video I/O operations will fail.fixInstall `ffmpeg` (recommended) or `libav` on your system. If they are not in PATH, you can explicitly set their location using `skvideo.setFFmpegPath('/path/to/ffmpeg')` or `skvideo.setLibAVPath('/path/to/libav')`. affects: All versions
deprecatedThe `setup.py` script, used for installing from source, relies on `numpy.distutils`, which is deprecated and removed in Python 3.12 and later, potentially breaking source installations.fixFor Python 3.12+, installation from source may require manual intervention or the use of `pip install --no-build-isolation .` or equivalent methods, if the project is not updated to `pyproject.toml`.
affects: All versions (impacts Python >= 3.12)
Errors
Common errors & fixes
skvideo.io.ffprobe_json.FFProbeError: FFProbe failed! Make sure ffmpeg is installed and available in your PATH.
The scikit-video library requires the external 'ffmpeg' binary to be installed on your system and accessible via the system's PATH environment variable.
fixInstall FFmpeg on your system and ensure its executable directory is added to your system's PATH. For Linux (Debian/Ubuntu): `sudo apt install ffmpeg`, for macOS (Homebrew): `brew install ffmpeg`.
ModuleNotFoundError: No module named 'skvideo'
The scikit-video library is either not installed or you are attempting to import it with the incorrect package name; the correct top-level import is 'skvideo', not 'scikit-video'.
fixInstall the library using pip: `pip install scikit-video`, then ensure you import it as `import skvideo.io` or `import skvideo.datasets`.
skvideo.io.VideoIOError: Could not read video frame, file might be corrupt or an unsupported format.
The specified video file path is incorrect, the file does not exist, it is corrupted, or its format/codec is not supported by FFmpeg or skvideo.
fixVerify the file path is correct, ensure the file exists and is not corrupted, and check that FFmpeg (and thus scikit-video) supports its codec.
ValueError: Frames must be 3-dimensional with 3 channels for rgb or 1 channel for grayscale
The input NumPy array representing video frames passed to `skvideo.io.vwrite` does not conform to the expected shape.
fixReshape your video data array to `(num_frames, height, width, 3)` for RGB or `(num_frames, height, width)` for grayscale before passing it to `vwrite`.
Upgrade
Version history
1.1.11latest on PyPI · released Sep 18, 2018
Audit
Dependencies
ffmpegrequiredBackend for video decoding/encoding, version >= 2.8. Alternatively, libav (version 10 or 11) can be used.
numpyrequiredCore numerical operations, version >= 1.9.2.
scipyrequiredScientific computing functionalities, version >= 0.16.0.
PillowrequiredImage processing, version >= 3.1.
scikit-learnrequiredRequired for some functionalities, version >= 0.18.
setuptoolsrequiredRequired for installation from source.
mediainfooptionalOptional tool for metadata probing.