Apply a custom 3D LUT to a display or a live preview

A custom 3D LUT changes colors according to a mapping stored in a file. You can apply it to your whole display or just to a live Picture in Picture (PIP) preview. This tutorial uses a simple warm-color example so you can see the effect and learn how to turn it on and off.

Before you begin

Use a connected display with HDR turned off. This tutorial uses SDR, the standard range for desktop content. The whole-display steps require software image adjustments and the compositor filter layer. They do not apply to a display receiving a mirrored image.
For the preview steps, use a second display to view the PIP. Keep the preview outside the desktop it captures to avoid an image repeating inside itself.
Open a photo or webpage with several colors and some white or gray areas. Keep private windows and notifications off the desktop you plan to capture.
Note any existing LUT selections or other adjustments you plan to turn off. Leave your ICC profile, brightness and other display settings unchanged so you can compare the LUT's effect.

If macOS requests screen-recording permission, allow BetterDisplay under System Settings > Privacy & Security > Screen & System Audio Recording. Follow any request to restart the app. See Apple's permission instructions if needed.

You can follow the whole-display steps, the preview steps, or both. The two selections are independent.

Import a sample LUT

If you already have an SDR LUT you want to use, import that file and follow its author's recommended settings. Otherwise, save the text below as a plain UTF-8 file named tutorial-warm-sdr.cube. Make sure your text editor does not add a .txt extension.

This example reduces green and blue while leaving red unchanged. White and gray areas should take on a warm tint, making the effect easy to compare. It demonstrates a color effect rather than a measured display correction.

TITLE "Tutorial Warm SDR"
LUT_3D_SIZE 2
DOMAIN_MIN 0 0 0
DOMAIN_MAX 1 1 1
0 0 0
1 0 0
0 0.85 0
1 0.85 0
0 0 0.70
1 0 0.70
0 0.85 0.70
1 0.85 0.70

Open Settings > Displays > Overview > Custom LUT Filters…. Choose Import Custom LUT… and select the file.
For the sample above, leave HDR content range off. Set Signal space to sRGB and leave SDR/reference white at 100 nits. The CUBE dimension should be 2³.
Use Tutorial Warm SDR as the Unique name. If that name is already in use, choose another name you will recognize. Select Add Custom LUT Filter to save it. Importing the file does not apply it yet.

The screenshots on this page show neutral example LUTs named Guide Identity SDR or Tutorial Identity SDR. The menu locations and settings are the same. Select Tutorial Warm SDR, or your own LUT's name, when following the steps.

New custom LUT filter named Guide Identity SDR with a 2³ CUBE file, sRGB signal space, HDR off and 100-nit reference white.

The import dialog lets you check the LUT's name and settings before saving it.

Signal space tells BetterDisplay how to interpret the file's colors. Reference white records the white level assumed when the LUT was created. Entering 100 nits does not change or measure your display's brightness.

BetterDisplay accepts UTF-8 3D CUBE files with dimensions from 2 to 128 and a file size up to 256 MiB. One-dimensional and mixed 1D/3D files are not supported. See Custom LUT Filters for format details and other import settings.

Apply it to the whole display

Open Settings > Displays > [your display] > Device Control > Image Adjustments. Make sure Enable software-based video adjustments and Enable compositor filter layer are on. Both are normally enabled. Note their original state if you change them.
Open App Menu > [the same display] > Image Adjustments. Make sure Suspend Image Adjustments is off. If other LUTs are selected, note their names and temporarily deselect them to see this LUT's effect on its own.
Under Custom LUT filters:, select Tutorial Warm SDR or the LUT you imported. The selection is saved and takes effect without an Apply button.
Look at white or gray areas on that display. With the sample LUT, they should look warmer. Select the same LUT again to turn it off and compare the original appearance.

The neutral Tutorial Identity SDR LUT selected in the display’s Image Adjustments menu.

A LUT selected in Image Adjustments affects the whole display.

Turn the LUT on and off by selecting its name. Avoid Reset Image Adjustments for this comparison because it also resets other adjustments. Suspend Image Adjustments turns off several adjustments together.

Make a separate preview

A PIP lets you view a filtered copy of a desktop while leaving the source display unchanged. Use a new PIP configuration so you can keep your existing previews as they are.

Turn the LUT off in the source display's Image Adjustments. Note and temporarily deselect any other display-side LUTs that would affect the comparison. This avoids applying a LUT to both the source and its captured copy.
Open App Menu > [source display] > Picture in Picture. In the original PIP entry, choose Add PIP Configuration. Open the new entry that appears.
Leave Start Automatically off and turn on Enable Picture in Picture Window. Move the preview to your second display. Check that it shows the intended source and does not include its own window.
Turn Video Filters on to show its settings. Leave the built-in effects at their defaults and Customize Blend Mode off. If HDR Filter Pipeline is available, leave it off for this SDR example.
Under Custom LUT filters:, select Tutorial Warm SDR or your own LUT. Compare the preview with the source, then select the same LUT again to turn it off in the preview.

The neutral Tutorial Identity SDR LUT selected in the additional PIP’s Video Filters menu.

A LUT selected in the PIP's Video Filters affects that preview independently of the display's selection.

Keep the viewing display's adjustments unchanged during the comparison. A LUT applied to that display also affects how the preview looks. Leave the new PIP's cropping, flips, rotation, Alpha and Magnification at their defaults.

You can select more than one LUT. BetterDisplay applies them after the built-in effects, in the order listed in the LUT manager. There is no strength slider for an individual LUT. Blend Mode Opacity adjusts the built-in blending effect.

Changing filters or updating the LUT manager can restart an active preview. Stop the preview before opening private content on its source. Hiding or pausing its window does not reliably prevent capture after a restart.

Check the result

On the whole display: the sample LUT should give white and gray areas a warm tint. Turning it off should restore their previous appearance.
In the PIP: the preview should change while the source display stays unchanged. Compare the preview with its own unfiltered appearance too, since the two displays may show colors differently.
With your own LUT: look for the effect it was designed to produce. Keep the content, brightness, profile and other adjustments fixed while comparing.

A selected menu icon shows that the LUT is assigned. To check its visible effect, compare the image with the LUT on and off. A screenshot alone cannot establish physical color accuracy.

A creative LUT changes the look of an image. For measured color correction, use a LUT created through a suitable calibration workflow. See color profiles and calibration. BetterDisplay applies these LUTs in software. It does not write them into the monitor's hardware LUT or replace its color table.

Troubleshooting

The file will not import: check that it is plain UTF-8 text. For the sample, copy the complete block, including all eight color rows. A supported file needs a valid LUT_3D_SIZE, the matching number of numeric RGB rows and an input range whose maximum exceeds its minimum. Renaming an unsupported file to .cube does not convert it.
The LUT is missing or cannot be selected: confirm that you chose Add Custom LUT Filter after importing. For a whole-display LUT, check the two software-adjustment options above and use a connected display that is not receiving a mirrored image. Also check the Pro requirements.
There is no visible change: check that you selected the LUT for the correct display or PIP. An identity LUT deliberately leaves colors unchanged, which is why the sample uses a warm effect. If your own file fails to import, try the sample to check whether the problem is specific to that file.
The preview's effect looks too strong: check for LUTs on the source display, the viewing display and the PIP. Also check the PIP's built-in effects. Deselect the extra filters one at a time.
The preview is blank or looks different: check screen-recording permission and source availability. Try ordinary desktop content because protected content may not be capturable. Display-side effects can appear differently in different capture methods.
A custom ICC profile limits adjustments: leave the compatibility safeguard in place. See custom-profile compatibility for the distinction between color-table adjustments and compositor filters.

Use a LUT made for the content range you want to process. Enabling HDR content range does not convert an SDR LUT into an HDR LUT. HDR filtering also depends on the Mac and capture path. See Custom LUT Filters for HDR settings and requirements.

Undo, stop and remove

Deselect the LUT in the display's Image Adjustments and in the PIP's Video Filters, wherever you enabled it. Restore any original LUT selections you temporarily turned off.
In the new PIP configuration, keep Start Automatically off and turn off Enable Picture in Picture Window. If a filter change is still restarting the preview, wait for it to finish and turn the window off again if needed. Confirm the preview has stopped before opening private content.
Choose Remove PIP Configuration in the new entry if you no longer need it. Wait for that entry to disappear. Keep any PIP configurations you had before this tutorial.
To remove the imported LUT, open Settings > Displays > Overview > Custom LUT Filters…. Find that LUT, choose Delete… and confirm Delete. Deleting a LUT removes it from every display and preview using it, so check its assignments first.
Restore any software-adjustment switches or other settings you changed. Re-enable any automatic rules you temporarily paused.

Import a new LUT for experiments instead of editing a shared one. Editing or replacing a saved definition changes it for every display and preview that uses it. Export Original LUT… saves the imported file. It does not back up the settings, assignments or order you configured in BetterDisplay.

Additional information

These are the license and platform requirements for this tutorial.

Features requiring Pro license

Importing and editing LUTs, selecting them for a display or PIP, and the PIP setup used here require Pro or an eligible app trial. Keep Pro or the app trial active until you have turned the LUT off. Deselecting an enabled LUT also requires it.

You can stop an active PIP, remove an additional PIP configuration, or export or delete a LUT without Pro. Deletion affects every assignment, so use it only when you want to remove the LUT everywhere.

Platform compatibility

The SDR steps work on both Apple silicon and Intel Macs. Whole-display LUTs require an available compositor filter layer. PIP requires screen-capture access and a source that can be captured. BetterDisplay requires macOS 26.3 or later.

HDR capture filtering requires Apple silicon and a compatible source and output. The sample and steps above use SDR.