Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

PyNVVL: A Python wrapper for NVIDIA Video Loader (NVVL) with CuPy

Project description


pypi-pynvvl-cuda80 pypi-pynvvl-cuda90 pypi-pynvvl-cuda91 pypi-pynvvl-cuda92 GitHub license

PyNVVL is a thin wrapper of NVIDIA Video Loader (NVVL). This package enables you to load videos directoly to GPU memory and access them as CuPy ndarrays with zero copy. The pre-built binaries of PyNVVL include NVVL itself, so you do not need to install NVVL.


  • CUDA 8.0, 9.0, 9.1, or 9.2
  • Python 2.7.6+, 3.4.7+, 3.5.1+, or 3.6.0+
  • CuPy v4.5.0

Tested Environment

  • Ubuntu 16.04
  • Python 2.7.6+, 3.4.7+, 3.5.1+, and 3.6.0+
  • CUDA 8.0, 9.0, 9.1, and 9.2

Install the pre-built binary

Please choose a right package depending on your CUDA version.

# [For CUDA 8.0]
pip install pynvvl-cuda80

# [For CUDA 9.0]
pip install pynvvl-cuda90

# [For CUDA 9.1]
pip install pynvvl-cuda91

# [For CUDA 9.2]
pip install pynvvl-cuda92


import pynvvl
import matplotlib.pyplot as plt

# Create NVVLVideoLoader object
loader = pynvvl.NVVLVideoLoader(device_id=0, log_level='error')

# Show the number of frames in the video
n_frames = loader.frame_count('examples/sample.mp4')
print('Number of frames:', n_frames)

# Load a video and return it as a CuPy array
video = loader.read_sequence(

print(video.shape)  # => (91, 3, 385, 512): (n_frames, channels, height, width)
print(video.dtype)  # => float32

# Get the first frame as numpy array
frame = video[0].get()
frame = frame.transpose(1, 2, 0)


This video is flickr-2-6-3-3-5-2-7-6-5626335276_4.mp4 from the Moments-In-Time dataset.

Note that cropping is performed after scaling. In the above example, NVVL performs scaling up from 256 x 256 to 512 x 512 first, then cropping the region [60:60 + 385, 0:512]. See the following section to know more about the transformation options.

VideoLoader options

Please specify the GPU device id when you create a NVVLVideoLoader object. You can also specify the logging level with a argument log_level for the constructor of NVVLVideoLoader.

Wrapper of NVVL VideoLoader

        device_id (int): Specify the device id used to load a video.
        log_level (str): Logging level which should be either 'debug',
            'info', 'warn', 'error', or 'none'.
            Logs with levels >= log_level is shown. The default is 'warn'.

Transformation Options

pynvvl.NVVLVideoLoader.read_sequence can take some options to specify the color space, the value range, and what transformations you want to perform to the video.

Loads the video from disk and returns it as a CuPy ndarray.

        filename (str): The path to the video.
        frame (int): The initial frame number of the returned sequence.
            Default is 0.
        count (int): The number of frames of the returned sequence.
            If it is None, whole frames of the video are loaded.
        channels (int): The number of color channels of the video.
            Default is 3.
        scale_height (int): The height of the scaled video.
            Note that scaling is performed before cropping.
            If it is 0 no scaling is performed. Default is 0.
        scale_width (int): The width of the scaled video.
            Note that scaling is performed before cropping.
            If it is 0, no scaling is performed. Default is 0.
        crop_x (int): Location of the crop within the scaled frame.
            Must be set such that crop_y + height <= original height.
            Default is 0.
        crop_y (int): Location of the crop within the scaled frame.
            Must be set such that crop_x + width <= original height.
            Default is 0.
        crop_height (int): The height of cropped region of the video.
            If it is None, no cropping is performed. Default is None.
        crop_width (int): The width of cropped region of the video.
            If it is None, no cropping is performed. Default is None.
        scale_method (str): Scaling method. It should be either of
            'Nearest' or 'Lienar'. Default is 'Linear'.
        horiz_flip (bool): Whether horizontal flipping is performed or not.
            Default is False.
        normalized (bool): If it is True, the values of returned video is
            normalized into [0, 1], otherwise the value range is [0, 255].
            Default is False.
        color_space (str): The color space of the values of returned video.
            It should be either 'RGB' or 'YCbCr'. Default is 'RGB'.
        chroma_up_method (str): How the chroma channels are upscaled from
            yuv 4:2:0 to 4:4:4. It should be 'Linear' currently.
        out (cupy.ndarray): Alternate output array where place the result.
            It must have the same shape and the dtype as the expected
            output, and its order must be C-contiguous.

How to build

Build wheels using Docker:


  • Docker
  • nvidia-docker (v1/v2)
bash docker/

Setup development environment without Docker:

The script searches for necessary libraries.

Requirements: the following libraries are available in LIBRARY_PATH.


You can build in the nvvl repository. Follow the instructions of nvvl library. The build directory must be in LIBRARY_PATH.

Other three libraries are available as packages in Ubuntu 16.04. They are installed under /usr/lib/x86_64-linux-gnu, so they must be in LIBRARY_PATH as well.

python develop
python bdist_wheel

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
pynvvl_cuda80-0.0.3a2-cp27-cp27mu-manylinux1_x86_64.whl (779.9 kB) Copy SHA256 hash SHA256 Wheel cp27
pynvvl_cuda80-0.0.3a2-cp34-cp34m-manylinux1_x86_64.whl (794.6 kB) Copy SHA256 hash SHA256 Wheel cp34
pynvvl_cuda80-0.0.3a2-cp35-cp35m-manylinux1_x86_64.whl (791.7 kB) Copy SHA256 hash SHA256 Wheel cp35
pynvvl_cuda80-0.0.3a2-cp36-cp36m-manylinux1_x86_64.whl (796.2 kB) Copy SHA256 hash SHA256 Wheel cp36

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page