Install & Compatibility
Where this runs
tested against v2.4.2.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
75MB installed
● package 75MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PyOpenColorIO
✓ import PyOpenColorIO-stubs as OCIO
✗ import PyOpenColorIO-stubs as OCIO
This quickstart demonstrates how to load an OpenColorIO configuration and perform a basic color space transformation using the Python bindings. It first attempts to load an existing configuration (e.g., via the `OCIO` environment variable) and falls back to creating a minimal in-memory configuration if none is found. It then converts a sample sRGB pixel value to a linear color space using a `Processor`.
import PyOpenColorIO as OCIO
import os
# For a runnable example, we'll try to get the current config.
# In a real setup, you'd likely set the OCIO environment variable
# to point to an OCIO config file, e.g., os.environ['OCIO'] = '/path/to/my_config.ocio'
# For this example, we'll assume a default or simple config if OCIO is not set.
try:
config = OCIO.GetCurrentConfig()
print("Successfully loaded OCIO config.")
except OCIO.Exception as e:
print(f"Could not load OCIO config: {e}. Attempting to create a minimal default config.")
# Create a minimal config for demonstration if none is found
config = OCIO.Config.Create()
config.setFileFormatVersion(OCIO.Constants.OCIO_FILE_FORMAT_VERSION_2_0)
linear_cs = OCIO.ColorSpace.Create()
linear_cs.setName("linear")
linear_cs.setFamily("linear")
linear_cs.setIsData(False)
config.addColorSpace(linear_cs)
srgb_cs = OCIO.ColorSpace.Create()
srgb_cs.setName("sRGB")
srgb_cs.setFamily("display")
srgb_cs.setIsData(False)
srgb_to_linear = OCIO.BuiltinTransform.Create(OCIO.BuiltinTransformRegistry.ACES_CG_TO_ACES2065_1)
srgb_to_linear.setDirection(OCIO.TransformDirection.INVERSE_TRANSFORM)
srgb_cs.setTransform(srgb_to_linear, OCIO.TransformDirection.FROM_REFERENCE)
config.addColorSpace(srgb_cs)
config.setDefaultWorkingSpaceName("linear")
config.setRole(OCIO.ROLE_SCENE_LINEAR, "linear")
config.setRole(OCIO.ROLE_COLOR_PICKING, "sRGB")
config.setRole(OCIO.ROLE_DISPLAY, "sRGB")
# Define source and destination color spaces
source_colorspace = "sRGB"
destination_colorspace = "linear"
# Ensure the color spaces exist in the config
if config.getColorSpace(source_colorspace) is None:
print(f"Error: Source colorspace '{source_colorspace}' not found in config.")
exit(1)
if config.getColorSpace(destination_colorspace) is None:
print(f"Error: Destination colorspace '{destination_colorspace}' not found in config.")
exit(1)
# Get a Processor to perform the color transformation
processor = config.getProcessor(OCIO.ColorSpaceTransform(src=source_colorspace, dst=destination_colorspace))
# Create an image buffer (e.g., a single pixel, RGB float values 0-1)
# Example sRGB value (mid-gray)
input_pixel = [0.218, 0.218, 0.218, 1.0] # R, G, B, A
# Create a working buffer (CPU processor operates on this)
# OCIO expects a contiguous flat array of pixel data.
# For a single pixel, it's [R, G, B, A]
output_pixel_data = list(input_pixel)
# Apply the transformation
# CPUProcessor handles float arrays directly
cpu_processor = processor.getCPUProcessor()
cpu_processor.applyRGB(output_pixel_data)
print(f"Input (sRGB): {input_pixel}")
print(f"Output (linear): {output_pixel_data[:3]} (alpha: {output_pixel_data[3]})")
Debug
Known issues
breakingOpenColorIO v2 introduced significant API changes compared to v1, including a re-engineered GPU renderer, modified clamping behavior for transforms, and new requirements for interchange roles (`aces_interchange`, `cie_xyz_d65_interchange`) for inter-config conversions.fixReview the OpenColorIO v2 migration guides. Update configuration files to include new roles and verify clamping behavior. Adapt Python code to the new GPU rendering API if used.
affects: OpenColorIO 2.x.x (and corresponding types-opencolorio 2.x.x.x)
gotchaThe `types-opencolorio` package provides only type stubs. The actual runtime library, `PyOpenColorIO` (installed via `pip install opencolorio`), must be installed separately for your Python code to execute successfully. Without it, you will encounter `ModuleNotFoundError` at runtime.fixEnsure both `pip install types-opencolorio` and `pip install opencolorio` are executed in your environment.
affects: All versions
gotchaThe `OCIO` environment variable is crucial for OpenColorIO applications as it typically points to the active configuration file. If this variable is not set or points to an invalid/incomplete configuration, `OCIO.GetCurrentConfig()` will fail, or applications may behave unexpectedly.fixSet the `OCIO` environment variable to the path of your `.ocio` configuration file. For example, `export OCIO=/path/to/my_config.ocio`.
affects: All versions
Upgrade
Version history
2.4.2.0latest on PyPI · released Jul 22, 2025
Audit
Dependencies
opencoloriorequiredProvides the actual runtime functionality; types-opencolorio only contains type hints.