Install & Compatibility
Where this runs
tested against v3.4.15 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 97MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.8s · import 0.000s · 89MB
95MB installed
● package 95MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Imath
✓ import Imath
✗ import openexr
This quickstart demonstrates writing a simple RGB image with `HALF` precision to an EXR file and then reading the red channel back. It utilizes `numpy` for data manipulation, which is standard practice when working with image pixel data in `openexr`. Ensure you have `numpy` and `imath` installed (`pip install numpy imath`).
import openexr
import Imath
import numpy as np
# Define image properties
width = 256
height = 256
half_channels = {'R': Imath.ChannelList().add('R', Imath.PixelType(Imath.PixelType.HALF)),
'G': Imath.ChannelList().add('G', Imath.PixelType(Imath.PixelType.HALF)),
'B': Imath.ChannelList().add('B', Imath.PixelType(Imath.PixelType.HALF))}
# Create some dummy data (e.g., a simple gradient)
x = np.linspace(0, 1, width)
y = np.linspace(0, 1, height)
R = np.outer(y, x).astype(np.float16)
G = np.outer(y, 1-x).astype(np.float16)
B = np.outer(1-y, x).astype(np.float16)
# Write an EXR file
output_filename = 'example.exr'
header = openexr.Header(width, height)
# Ensure correct channel types and data window if writing half data
# header['channels'] = half_channels
# The above is for explicit channel list. For simplicity, let's use default half for RGB.
file_out = openexr.OutputFile(output_filename, header)
file_out.writePixels({'R': R.tobytes(), 'G': G.tobytes(), 'B': B.tobytes()})
file_out.close()
print(f"Written {output_filename}")
# Read the EXR file
file_in = openexr.InputFile(output_filename)
header_in = file_in.header()
data_window = header_in['dataWindow']
dw = Imath.Box2i(data_window)
size = (dw.max.x - dw.min.x + 1, dw.max.y - dw.min.y + 1)
# Read 'R' channel data as bytes and convert to numpy array
r_channel_bytes = file_in.channel('R', Imath.PixelType(Imath.PixelType.HALF))
r_data = np.frombuffer(r_channel_bytes, dtype=np.float16).reshape(size[1], size[0])
print(f"Read R channel data shape: {r_data.shape}")
print(f"First few R values: {r_data.flatten()[:5]}")
file_in.close()
Debug
Known issues
breakingThe `openexr` package is the official Python 3 binding for OpenEXR 3.x, replacing the older `PyOpenEXR` and `PyImath` packages which were tied to OpenEXR 2.x. Users migrating from older setups will find significant API differences and different import paths. Do not mix `openexr` with `PyOpenEXR`.fixRewrite code to use the new `openexr` API (e.g., `openexr.InputFile` instead of `OpenEXR.InputFile`). Ensure `pip install openexr` and potentially `pip install imath` are used, not `pip install PyOpenEXR PyImath`.
affects: < 3.0
gotchaInstalling `openexr` from source can be complex due to its underlying C++ dependencies (OpenEXR, Imath, zlib, etc.). Pre-built wheels are typically available on PyPI for common platforms, but if a wheel isn't available for your specific Python version/OS, a robust C++ build environment (including `cmake`) is required.fixPrioritize `pip install openexr` to leverage pre-built wheels. If building from source, ensure `cmake` and all necessary C++ development headers for OpenEXR and its dependencies are installed on your system.
affects: All versions (when building from source)
gotchaWhile `openexr` provides EXR file I/O, `Imath` (vectors, matrices, boxes) is typically accessed via the separate `imath` Python package. Though `openexr`'s internal C++ libraries use Imath, its Python bindings do not fully expose all Imath types directly under the `openexr` namespace.fixAlways `import Imath` separately if you need to create or manipulate Imath-specific types (e.g., `Imath.V3f`, `Imath.Box2i`) in your Python code, and ensure the `imath` package is installed (`pip install imath`).
affects: All versions
gotchaPixel data read from `openexr` channels are returned as raw `bytes` objects. These must be converted to `numpy.ndarray` for practical manipulation, requiring careful handling of `dtype` (e.g., `np.float16` for `HALF`, `np.float32` for `FLOAT`) and `reshape` to the correct image dimensions.fixWhen reading, use `np.frombuffer(raw_bytes, dtype=...).reshape(...)`. When writing, convert your `numpy` arrays to bytes using `array.tobytes()` and ensure the `PixelType` in the `openexr.Header` matches your data's `dtype`.
affects: All versions
gotchaMultiple recent patch releases (e.g., 3.4.9, 3.3.9, 3.2.7) have addressed significant security vulnerabilities, including heap out-of-bounds writes and integer overflows, which could lead to crashes or arbitrary code execution when processing malformed EXR files.fixAlways keep your `openexr` installation updated to the latest patch release (e.g., `pip install --upgrade openexr`) to mitigate known security risks, especially when dealing with EXR files from untrusted sources.
affects: < 3.4.9, < 3.3.9, < 3.2.7
Upgrade
Version history
3.4.15latest on PyPI · released Aug 21, 2026
Audit
Dependencies
numpyrequiredEssential for efficient handling of image pixel data (arrays).
imathoptionalProvides Python bindings for Imath (vector/matrix math library), commonly used alongside OpenEXR for geometric data in headers.