What is an OCIO config? config.ocio, explained

Guide · Updated 6 July 2026

An OpenColorIO config - the file usually named config.ocio - is how a studio tells every application what colorspaces exist and how to move images between them. It's a single YAML text file, which is exactly why you can read and validate it without a compiler or an OCIO build. Here's what's inside it, how the parts connect, and why configs break.

The building blocks

Colorspaces

The heart of the config is a list of colorspaces: each has a name, usually a family for grouping, optional aliases, an isdata flag (for non-colour data like normals or masks that must never be transformed), and the transforms that get it to and from the config's reference space. Everything else in the config refers back to these names.

Roles

A role is an alias with a job. Instead of hard-coding a colorspace, an application asks OCIO for a role - scene_linear, data, color_picking, reference, compositing_log, matte_paint and so on - and the config decides which real colorspace answers. That indirection is what lets you swap configs without touching every tool. Each role must point at a colorspace (or an alias of one) that actually exists.

Displays & views

A display is an output - sRGB, Rec.709, P3-D65. Within each display are views: the different ways to look at the image there, such as an ACES output transform, a log view, or a plain Raw. In OCIO v1 a view names a single colorspace; in v2 a view can instead pair a view_transform with a display_colorspace. The active_displays and active_views lists then pick which ones apps show, and in what order.

Looks & view transforms

A look is a named creative grade (a show LMT, a "beauty" look) with a process_space - the colorspace it is applied in. A view transform (OCIO v2) describes the scene-to-display rendering, shared across displays. Both reference colorspaces, so both can break if a name changes.

search_path

Finally, search_path tells OCIO where to find the LUTs and other files the transforms reference, relative to the config. A config can be structurally perfect and still fail at runtime if a LUT named in a transform isn't on the search path.

A minimal config, annotated

ocio_profile_version: 2
search_path: luts

roles:
  scene_linear: ACEScg      # apps working space
  data: Raw                 # never colour-managed
  reference: ACES2065-1     # the config's hub space

displays:
  sRGB:
    - !<View> {name: ACES SDR, view_transform: ACES 1.0 - SDR Video, display_colorspace: sRGB - Display}
    - !<View> {name: Raw, colorspace: Raw}

colorspaces:
  - !<ColorSpace> {name: ACES2065-1, family: ACES}
  - !<ColorSpace> {name: ACEScg,     family: ACES}
  - !<ColorSpace> {name: Raw,        family: Utility, isdata: true}

Read it top-down and you can see the dependency chain: the roles and the view all point back at colorspaces defined further down. If ACEScg were mistyped as ACEScg in the role, the config would parse fine but the scene_linear role would fail to resolve - the classic broken config.

Why configs break

• Renamed or removed colorspaces - a role, view or look still points at the old name.
• Typos and case - sRGB - Texture vs sRGB-Texture; OCIO names are exact.
• Duplicate colorspaces - two definitions with the same name; the config is ambiguous.
• Dangling active lists - active_views naming a view that no longer exists in any display.
• Missing standard roles - some apps expect scene_linear or data and misbehave without them.
• Missing LUTs - a transform references a file that isn't on the search_path.

The first five are all structural - visible in the text - which is exactly what OCIO Validator checks: it resolves every role, view, display, look and view transform against your defined colorspaces and lists anything that doesn't add up.

Questions, answered