Install & Compatibility
Where this runs
tested against v3.1.14.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
muslpy 3.10–3.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 4.0s · import 0.043s · 102MB
103MB installed
● package 103MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenImageIO
✓ import OpenImageIO as oiio
ImageInput
✓ from OpenImageIO import ImageInput
✗ import ImageInput
ImageInput is a class within the OpenImageIO module, not a top-level module itself.
ImageBuf
✓ from OpenImageIO import ImageBuf
✗ import ImageBuf
ImageBuf is a class within the OpenImageIO module, not a top-level module itself.
This quickstart demonstrates how to create an in-memory image (a red square) using OpenImageIO and NumPy, write it to an OpenEXR file, and then read it back. It utilizes `ImageSpec` to define image properties and `ImageBuf` for convenient image manipulation and I/O. The `get_pixels` method retrieves pixel data as a NumPy array.
import OpenImageIO as oiio
import numpy as np
import os
# Create a dummy image (e.g., a red square)
width, height, channels = 256, 256, 3
spec = oiio.ImageSpec(width, height, channels, oiio.TypeDesc('float'))
# Create a NumPy array with red pixels
pixels = np.zeros((height, width, channels), dtype=np.float32)
pixels[:, :, 0] = 1.0 # Red channel to full intensity
# Create an ImageBuf from the spec and pixels
img_buf = oiio.ImageBuf(spec, pixels)
# Define output file path
output_filename = 'red_square.exr'
# Write the image
try:
img_buf.write(output_filename)
print(f"Successfully wrote {output_filename}")
# Read the image back
read_img_buf = oiio.ImageBuf(output_filename)
if read_img_buf.has_error:
raise RuntimeError(f"Error reading {output_filename}: {read_img_buf.geterror()}")
# Get pixel data as a NumPy array
read_pixels = read_img_buf.get_pixels(oiio.TypeDesc('float'))
print(f"Read image with shape: {read_pixels.shape}")
except Exception as e:
print(f"An error occurred: {e}")
finally:
if os.path.exists(output_filename):
os.remove(output_filename) # Clean up the dummy file
oiiotool --version
Debug
Known issues
breakingOpenImageIO 2.0 introduced significant breaking changes in Python bindings, most notably the switch from Python's `array.array` to `numpy.ndarray` for pixel data. Code written for OIIO 1.x that handles pixel buffers will need updates.fixMigrate pixel buffer handling to use NumPy arrays. Functions like `read_image()` and `get_pixels()` now return NumPy arrays, and `write()` expects them.
affects: >=2.0.0
gotchaInstalling OpenImageIO via `pip` on certain platforms or for full functionality (especially with specific C++ compiler versions or less common image formats) can sometimes be challenging due to its underlying C++ dependencies. Pre-built wheels aim to simplify this but edge cases exist.fixEnsure your environment meets the `requires_python` version. If `pip install` fails or format support is missing, consider building from source using `vcpkg` or by following the detailed build instructions in the OIIO documentation, which might require installing system-level C++ development packages (e.g., `libtiff-dev`, `libopenexr-dev`).
affects: All
gotchaWhen `pip` installing OpenImageIO from source, or if using a custom build, a `ModuleNotFoundError` can occur if the Python interpreter cannot locate the `OpenImageIO` module. This is particularly common on macOS where shared libraries (`.dylib`) might not be found by Python which often expects `.so` extensions.fixVerify that the `PYTHONPATH` environment variable correctly points to the directory containing the `OpenImageIO.so` (or `OpenImageIO.pyd` on Windows) file. For macOS, ensure the `.dylib` file is either renamed to `.so` or linked appropriately, or that the build system is configured to produce `.so`.
affects: All (especially custom builds)
gotchaIncorrectly converting a color image (like sRGB JPEG) to grayscale by simply averaging the R, G, B channels will yield visually inaccurate results because human perception of brightness is not uniform across color channels, and sRGB is a non-linear color space.fixUse `oiio.ImageBufAlgo.colorconvert()` to linearize the image (e.g., 'sRGB' to 'linear') and then `oiio.ImageBufAlgo.channel_sum()` with appropriate luminance weights (e.g., `(0.2126, 0.7152, 0.0722)` for Rec. 709/sRGB luminance) to derive the grayscale. Convert back to sRGB if outputting to an 8-bit image format.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'OpenImageIO'
The Python interpreter cannot find the installed OpenImageIO module. This often happens after building from source or due to incorrect `PYTHONPATH` settings.
fixEnsure `pip install openimageio` completed successfully. If building from source, set the `PYTHONPATH` environment variable to include the directory where `OpenImageIO.so` (Linux/macOS) or `OpenImageIO.pyd` (Windows) is located. For macOS, sometimes renaming `OpenImageIO.dylib` to `OpenImageIO.so` is required.
Python interpreter crashes when reading certain image files.
OpenImageIO is a C++ library, and reading malformed or corrupted image files, or files with exotic parameters that expose bugs in the underlying C++ plugins, can lead to a hard crash of the Python interpreter instead of raising a Python exception.
fixWrap image reading operations in `try-except` blocks, specifically checking `ImageBuf.has_error` and `ImageBuf.geterror()` after initialization or I/O operations. While this doesn't prevent all C++-level crashes, it helps catch many issues gracefully. Ensure you are using the latest stable version of OpenImageIO and its dependencies, as many such bugs are fixed over time.
TypeError: argument 'pixels': 'list' object cannot be converted to 'PyArrayObject'
Attempting to pass raw Python lists or `array.array` objects as pixel data to OIIO functions (e.g., `ImageBuf.set_pixels()`, `ImageOutput.write_image()`) in OpenImageIO 2.0+.
fixConvert pixel data to `numpy.ndarray` objects before passing them to OpenImageIO functions. For example, `pixels_ndarray = np.array(my_list_of_pixels, dtype=np.float32)`.
Upgrade
Version history
3.1.14.0latest on PyPI · released Jun 1, 2026
Audit
Dependencies
numpyrequiredRequired for handling pixel data as NumPy arrays in Python bindings.
zliboptionalCore C++ dependency, often linked during compilation. Included in wheels.
libTIFFoptionalCore C++ dependency for TIFF format support. Included in wheels.
OpenEXRoptionalCore C++ dependency for OpenEXR format support. Included in wheels.
OpenColorIOoptionalCore C++ dependency for color management features. Included in wheels.
libjpeg / libjpeg-turbooptionalCore C++ dependency for JPEG format support. Included in wheels.