Custom LUT Filters

Three-dimensional look-up tables (LUTs) map input colors to output colors. This manager lets you import a reusable LUT and tell BetterDisplay how its values should be interpreted. Saving it here makes the LUT available in the app. Each display, PIP window, Video Filter Window or stream can then use it independently.

Where to find it: Settings > Displays > Overview > Custom LUT Filters…. A populated Custom LUT filters section in an image/filter menu also offers Manage….

Choose a LUT authored for the color conditions you intend to use. HDR LUT handling is marked Experimental and assumes a fixed display calibration. Use the settings supplied by the LUT’s author. The manager cannot determine those settings from the file for you.

New custom LUT filter with Guide Identity SDR, sRGB signal space, 100-nit reference white and enabled Add button

A valid SDR CUBE import exposes its name, signal space and reference white before it is saved.

Import a CUBE file

Select Import Custom LUT… and choose one file. BetterDisplay reads UTF-8 CUBE text containing a 3D LUT. After import, a form lets you check the LUT’s name and settings. Nothing is saved or applied until you confirm it.

The pending form shows the original CUBE file and CUBE dimension. Unique name starts from the CUBE title or filename, with a numeric suffix when needed. Choose a name you will recognize in the menus where you apply filters. Names must be unique. BetterDisplay ignores spaces at either end, letter case and accents when comparing them. A duplicate name shows A custom filter with this name already exists. Choose a different name to enable the Add button.

Add Custom LUT Filter saves a valid definition, while Cancel discards the pending import. BetterDisplay stores a compressed copy of the original file in its settings. You can export that copy later, so you do not need to keep the file at its import location.

Supported files and validation

The CUBE file must have a LUT_3D_SIZE from 2 to 128, and its source must be no larger than 256 MiB. One-dimensional and mixed 1D/3D CUBE files are rejected.

BetterDisplay checks the cube dimension, color values and number of entries. It also checks the input range, which tells it which color values the table covers. An invalid import produces a Custom LUT Filter alert explaining the cause, such as a missing dimension, an invalid data line or the wrong number of entries. If the file declares an input range, each maximum must be greater than its corresponding minimum.

A larger cube gives the color mapping a finer grid, with greater storage and processing requirements. It does not increase the pixel resolution of your image.

Content range, signal space and white level

The interpretation fields tell BetterDisplay what the LUT's numbers mean. Match them to the conditions for which the LUT was created. Do not rely on the filename to choose the settings.

A new import starts with HDR content range off, sRGB, and SDR/reference white: 100 nits. For SDR, the Signal space menu offers sRGB, Rec. 709, and Display P3. Choose the space used by the LUT.

Enabling HDR content range on a new import selects fixed Rec. 2100 PQ, sets reference white to 203 nits, and sets HDR target peak to 1000 nits. Turning it off resets the pending import to sRGB with 100-nit reference white. These are starting values, not measurements of your display.

Setting reference white and peak

SDR/reference white records the LUT’s authored white-level assumption. It must be a positive finite value. For HDR, HDR target peak must also be finite and must exceed reference white. These values describe the LUT and are checked for validity. They do not apply a luminance gain, or set or measure your monitor’s brightness. Enter the levels used when the LUT was created. Nits measure luminance.

Pending Guide Identity PQ LUT with HDR enabled, Rec. 2100 PQ, 203-nit reference white and 1000-nit target peak

HDR imports use a fixed PQ signal space and explicit reference-white and peak luminance values.

HDR LUT form with both reference white and target peak at 203 nits and Add Custom LUT Filter disabled

The target peak must exceed the reference white before an HDR LUT can be added.

Existing filters, replacement and export

Each existing entry summarizes its content range, signal space, reference white, optional HDR peak, filename and cube dimension. Use Edit… to change the interpretation fields or Upload… to stage a replacement CUBE.

A replacement keeps the filter's identity, assignments and configured content range. Displays and previews already using it will use the replacement too. Check the interpretation settings if the replacement was created for different conditions. Done saves the changes and updates the displays and previews using the LUT. Cancel discards the staged name, settings and replacement.

Export Original LUT… opens a save dialog with the original filename and exports the stored CUBE source. Signal space and reference white remain separate app settings. Exporting does not add them to the CUBE file. Problems reading stored data or exporting appear in a Custom LUT Filter alert.

Create a LUT color profile

For an SDR filter, choose Create LUT Color Profile… beside Export Original LUT…. This experimental feature creates an ICC color profile containing the LUT, which you can select from the display’s Color Profile menu. Creating or applying this profile does not enable the original software filter. Avoid applying both if you want the effect only once.

Profile Name starts with the saved LUT’s name. Optimize for chooses a connected display for previewing and immediate application. Choose None to create a profile without applying it to a display. Base Profile determines the RGB display characterization combined with the LUT. The initial choice is the selected display’s active profile when it is a supported system or factory profile. Otherwise, the app tries its factory profile, Display P3, sRGB and Generic RGB in that order. With None, the same fallback starts at Display P3. You can select another available matrix-based RGB base profile.

Choose Device RGB (no output conversion) for LUTs that already include the display correction. Incoming colors are still converted into the LUT’s configured input signal space, but the LUT’s output RGB values are used directly as display-device values without conversion into another base profile. ICC sampling and app rendering can still alter the final values, so this does not guarantee bit-perfect output or disable color management throughout macOS. This choice stays selected when you change Optimize for.

Preview temporarily applies the generated profile to the selected display. Stop Preview, changing the selected display or base profile, creating the saved profile, or closing the sheet restores the previous profile. If another app changes the profile during preview, its selection takes precedence. Preview is unavailable with None. The preview does not install a permanent profile.

Create saves the ICC file in ~/Library/ColorSync/Profiles without applying it. If its name is already used, the app adds a number. The sheet then confirms the saved name. Choose Done to use the profile later from the Color Profile menu, or Apply Profile to select it immediately for the chosen display. The created profile remains usable if you later edit or delete the imported LUT.

Some Apple displays use Presets and have Color Profile management disabled. The sheet explains this and disables Preview and Apply Profile. You can still create the profile. To enable profile assignment, use Settings > Displays > Overview > Advanced Display Settings… > Unlock Color Profile management for Apple displays.

Delete and apply

Importing alone does not change display colors. To use the saved definition, enable it from the target's Image Adjustments, PIP, Video Filter Window or Stream menu. Each target chooses independently whether to use it.

Several targets can share one definition. Editing or replacing that definition can therefore affect all its enabled uses, even though enabling the filter remains a per-display or per-stream choice.

Delete… always asks for confirmation. If the filter is in use, the message reports how many display or stream configurations have it enabled. Delete removes the definition and disables those assignments, including remembered displays and stream configurations. Cancel preserves them.

Guide Identity SDR in edit mode with Upload, Cancel and Done controls

Edit a saved LUT’s configuration or upload a replacement while keeping its identity.

Delete Custom LUT Filter confirmation reporting one display or stream assignment

The deletion confirmation reports assignments that will also be disabled.

See Software Image Adjustments, Upscaling & Dimming for the separate color-table and brightness controls.

Follow the whole-display and separate-preview LUT tutorial for a sample with a visible warm-color effect, separate display and preview selections, and cleanup steps.

Additional information

This section explains which features require Pro and how availability differs between Mac platforms.

Features requiring Pro license

Existing filters can still be exported or deleted when Pro editing is unavailable.

Platform compatibility

The LUT manager and its file operations are available on both Apple silicon and Intel Macs. Applying a filter depends on the target's image-filtering and capture capabilities. The stream filtering path enables extended dynamic range only on Apple silicon, so an Intel Mac can show the HDR interpretation fields without supporting HDR stream output. HDR LUT handling remains experimental and requires the fixed calibration described above.