Kodi can make a movie library feel wonderfully polished, but its video settings can also look intimidating at first glance. One setting that often raises questions is the Whitelist. It sounds technical, but the idea is simple: it tells Kodi which display modes it is allowed to use when playing videos.
TLDR: Kodi’s whitelist is a list of approved screen resolutions and refresh rates that Kodi may switch to during playback. You should use it if you want videos to play at their native resolution or frame rate, especially on a 4K TV or projector. If everything already looks smooth and correct, you may not need to change it. When in doubt, start with an empty whitelist and adjust only if you have a specific display issue or quality goal.
What Is the Kodi Whitelist?
In Kodi, the Whitelist is found under the display settings and contains combinations such as 1920×1080 at 23.976Hz, 3840×2160 at 24Hz, or 1280×720 at 60Hz. These are video output modes supported by your TV, monitor, projector, or AV receiver.
When you select modes in the whitelist, you are telling Kodi: “These are the resolutions and refresh rates I trust. Use these when they match the video I am playing.”
This matters because movies, TV shows, live sports, and streaming videos are not all produced the same way. A film might be 23.976 frames per second, a TV broadcast might be 50Hz, and a game clip might be 60Hz. If Kodi can switch your display to a matching refresh rate, motion may look smoother and more natural.
Resolution and Refresh Rate: The Two Key Pieces
The whitelist is about two things: resolution and refresh rate.
- Resolution refers to the size of the video image, such as 720p, 1080p, or 4K.
- Refresh rate refers to how many times per second the display updates, such as 24Hz, 50Hz, or 60Hz.
A common example is watching a 1080p movie on a 4K TV. If Kodi is set to output everything at 4K, Kodi may upscale the 1080p movie before sending it to the TV. If you whitelist 1080p modes, Kodi can send the movie at 1080p and let the TV handle the upscaling instead.
That can be useful because many modern TVs have excellent upscaling processors. In some setups, the TV may produce a sharper or cleaner image than Kodi or the playback device. In other setups, Kodi’s scaling may look just as good. The best option depends on your hardware.
When Should You Use the Whitelist?
You should consider using the Kodi whitelist when you want more control over how videos are displayed. It is especially helpful in the following situations:
- You have a 4K TV and watch a lot of 1080p content. Whitelisting 1080p modes allows your TV to do the upscaling.
- You notice motion judder. Matching a movie’s frame rate to your display’s refresh rate can reduce uneven motion.
- You use a projector or AV receiver. Some home theater setups handle certain video modes better than others.
- You want native playback whenever possible. The whitelist can help Kodi output video closer to its original format.
- You have problems with black screens or signal drops. Limiting Kodi to reliable modes can prevent it from choosing problematic ones.
For many users, the most important reason is smooth playback. Most films are close to 24 frames per second. If your display is locked to 60Hz, Kodi has to fit those frames into a refresh cycle that does not divide evenly. This can create subtle stutter, especially during slow camera pans.
When Should You Leave It Alone?
The whitelist is powerful, but it is not something everyone needs to configure. If your videos already look smooth, your TV switches correctly, and you are not bothered by scaling quality, leaving the whitelist empty is often perfectly fine.
An empty whitelist does not mean Kodi is broken or poorly configured. It simply means Kodi will generally use the current display mode rather than trying to switch between several approved modes. For a simple setup, such as a streaming box connected directly to a TV, this may be the easiest and most stable choice.
You should also be careful if your display is slow to change modes. Some TVs go black for several seconds when switching from 60Hz to 24Hz or from 1080p to 4K. If you find this annoying, you may prefer fewer whitelisted modes or no whitelist at all.
How the Whitelist Works With “Adjust Display Refresh Rate”
The whitelist is closely related to Kodi’s Adjust display refresh rate setting. This option allows Kodi to change the display mode when a video starts or stops. Without it, the whitelist has much less practical value.
Most users who use the whitelist should set Adjust display refresh rate to On start/stop. This lets Kodi switch to a better matching refresh rate when playback begins and return to the normal interface mode afterward.
There is another setting called Sync playback to display, but it is different. That option adjusts playback speed slightly to match the display. It can be useful in some situations, but it may interfere with audio passthrough formats such as Dolby TrueHD or DTS HD MA. If you use an AV receiver and want bitstream audio, you will usually leave sync playback disabled.
How to Set Up the Kodi Whitelist
To configure the whitelist, go to Kodi’s settings and make sure the settings level is set to Expert. Then open:
Settings > System > Display > Whitelist
You will see a list of modes supported by your display chain. This includes the playback device, HDMI cable, AV receiver if present, and the TV or projector. Select only the modes you actually want Kodi to use.
A sensible setup might look like this:
- For a 4K TV: whitelist 3840×2160 at 23.976Hz, 24Hz, 50Hz, and 60Hz if supported.
- For 1080p content on a 4K TV: also whitelist 1920×1080 at common refresh rates if you want the TV to upscale.
- For a 1080p display: whitelist 1920×1080 modes that match your content, especially 23.976Hz, 24Hz, 50Hz, and 60Hz.
Do not select every mode blindly. Old or unusual modes may cause flickering, black screens, or handshake problems. Start with the obvious modes, test real videos, and expand only if needed.
Common Mistakes to Avoid
- Whitelisting unsupported modes: If a mode causes dropouts or blank screens, remove it.
- Forgetting about the AV receiver: Your receiver must support the same modes as your TV.
- Assuming 4K output is always best: Sometimes your TV does better upscaling than your Kodi device.
- Ignoring refresh rate: Smooth motion often depends more on refresh rate than resolution.
Final Thoughts
The Kodi whitelist is not a magic quality button, but it is one of the most useful tools for fine tuning playback. It gives you control over which resolutions and refresh rates Kodi can use, helping your display match the content more accurately.
If you enjoy tweaking your home theater setup, the whitelist is worth exploring. If you prefer simplicity, you can safely leave it empty unless you notice stutter, scaling issues, or unreliable mode switching. The best approach is practical: change one thing at a time, test with familiar videos, and keep the modes that make your movies and shows look their best.
