Frequently Asked Questions - Lunar.fyi

Frequently Asked Questions How do I uninstall Lunar?Copied Link

If you want to uninstall Lunar completely:

Using brew:

brew uninstall --cask --force --zap lunar

Using AppCleaner or PearCleaner:

• Download and open AppCleaner or PearCleaner
• Drag and drop the Lunar app from the Applications folder into the AppCleaner/PearCleaner window

Using LaunchPad (pre macOS Tahoe 26):

• Open Launchpad from the Dock or Spotlight
• Type Lunar to find the app
• Hold the ⌥ option key and click on the x button

If you only want to make sure Lunar is not running:

• Disable Launch at login
• Quit Lunar

The app does not have any daemons or background services.

Monitor flickers on specific colors.Copied Link

This is usually caused by either a bug in monitor firmware or a faulty color profile.

Try using a different Colour Profile.

Lunar can't cause any hardware damage, so if the monitor didn't have a hidden problem before, the issue should be fixable.

MacBook screen is black, can't loginCopied Link

On very rare conditions, the MacBook screen can get into a state where it shows a black screen and you can't see the login screen because of a color profile issue.

Possible solutions

1. If you have access to another monitor, open a Terminal and run the following commands:

sudorm/Library/Preferences/com.apple.windowserver.displays.plist sudorm/Library/ColorSync/Profiles/Displays/* rm~/Library/Preferences/ByHost/com.apple.windowserver*.plist sudonvram-c

Then restart the MacBook.

2. If you only have the MacBook screen:

• shut down the Macbook
• boot into recovery mode by holding the power button (on Apple Silicon) or ⌘ Command + R while booting (on Intel Macs)
• open Disk Utility and mount the Data volume then close Disk Utility
• open a Terminal in recovery mode by going to the Utilities menu at the top and selecting Terminal
• run the following commands to reset the color profile to the default one:

rm/Volumes/*/Library/Preferences/com.apple.windowserver.displays.plist rm/Volumes/*/Library/ColorSync/Profiles/Displays/* rm/Volumes/*/Users/*/Library/Preferences/ByHost/com.apple.windowserver*.plist sudonvram-c

Then restart the MacBook.

3. Try to login using VoiceOver:

• Restart the computer to get to the login screen
  • Hold the power button until the MacBook turns off
  • Press the power button again to turn it on
  • Wait about 10 seconds to make sure you got to the login screen, even if you can't see it
• Press ⌘ Command + F5 to enable VoiceOver
• Press Volume Up once or twice to make sure the volume is not muted
• If the voice over says username press Enter or Tab to get into the password field
• If the voice over says password, type your password and press Enter

The MacBook screen should be back to normal after you login.

Technical explanation

This is a problem in the system color profile logic and it can happen with or without Lunar.

It can be aggravated by Lunar's use of Gamma tables because the dimming might get the color formula into a state where all the computed colors are 0 or black, if the color profile used can't cover the full range of colors.

It can also happen when Lunar activates XDR Brightness or Full Range on a MacBook screen in very specific scenarios that we haven't identified yet.

Monitors are black, have no signal or switch on/off constantly.Copied Link First thing to try

1. Quit Lunar
2. Unplug the monitor from the power socket
3. Plug the monitor back

Possible causes

Color Profiles

Because of a macOS bug in the Gamma API, your screen can go black then get back to normal after a few seconds.

There's no complete fix for this as it is a macOS bug, but you can lower the chances of it appearing using the following steps:

• Use a default color profile in System Preferences -> Displays
• Minimise future Gamma resets by disabling the HDR compatibility workaround from HDR Settings

If that doesn't fix the issue, you can try to disable the usage of Gamma completely from Advanced Settings

Technical explanation

This usually happens when custom color profiles are used, but it was reported on some default monitor profiles as well.

The bug is usually triggered when Lunar tries to reset the gamma tables to their default values by calling the CGDisplayRestoreColorSyncSettings() system method.

This should be a completely normal use case, and the call should simply do nothing if the gamma tables are already at their default values. But for unknown reasons, this API call will sometimes set all RGB Gamma tables to 0 and all colors will show up as black.

The flash you see comes from Lunar detecting this zero-gamma problem in the background, and applying a default Gamma table forcefully to avoid being stuck with a blacked out display.

Firmware bugs

Some monitors have firmware bugs and don't react well to DDC commands.

You can try to open Advanced Settings and enable the Delay DDC after wake experimental setting:

If the problem persists, you will need to disable DDC completely.

To do that, disable Hardware (DDC) controls from the Controls menu:

Lunar will fallback to adjusting brightness and contrast in software using Gamma values.

Notes about Gamma:

• Conflicts with other apps that use Gamma like f.lux so you have to quit them
  • Night Shift is a good alternative as it doesn't use Gamma
• Can only lower the brightness, not increase it
  • That's why you have to manually set the monitor brightness and contrast to maximum using its physical buttons
• Can't change the volume or input of the monitor
  • Those features require DDC

Brightness controls are locked after standby/wake.Copied Link

This is either a macOS or a monitor problem, and it happens for a small number of people.

Brightness might be working fine until the Mac/monitor enters standby, then after wake you might see the lock icon.

This is caused by the DDC port for the monitor not being visible anymore inside the macOS I/O Registry tree.

Unfortunately the only way to fix it is to restart Lunar so it can get a new refreshed view of the I/O Registry.

I have added an instant Restart hotkey on the Hotkeys page of the Lunar preferences window, to allow for a faster recovery when this happens.

The brightness or volume doesn't change.Copied Link

Some monitors don't accept DDC commands (which Lunar uses to control brightness and volume).

Below are some possible causes for this issue.

Built-in HDMI port of the 2018 Mac Mini

The HDMI port of these devices is blocking DDC requests without a known cause.

Using one of the Thunderbolt ports usually fixes this (through USB-C-to-HDMI cable, Thunderbolt hub, etc.).

HDMI-to-USB-C Cables

Some users report that DDC controls are blocked on specific monitors when using HDMI to USB-C cables and that switching to DisplayPort fixes their problem.

If possible, try a DisplayPort to USB-C cable.

Samsung M7, M9, G7, G9 on USB-C

DDC seems to only work through the HDMI port of these monitors. The USB-C connection blocks hardware brightness/volume control.

Smart Monitors

In most cases, DDC is blocked by a monitor setting that tries to take complete control of Brightness, Contrast or Volume.

Usually disabling those functions in the monitor settings will allow Lunar control brightness.

Below are some settings that are known to block DDC, grouped by monitor vendor.

Samsung

• Disable Input Signal Plus
• Disable Magic Bright
• Disable Eye Saver Mode
• Disable Eco Saving Plus
• Disable Smart ECO Saving
• Disable PIP/PBP Mode
• Disable Dynamic Brightness

Dell

• Disable Uniformity Compensation
• Set Preset Mode to Custom or Standard to allow DDC

LG

• Disable Uniformity
• Disable Auto Brightness
• Set Picture Mode to Custom or Standard to allow DDC

BenQ

• Disable Bright Intelligence
• Disable Bright Intelligence Plus or B.I.+
• Set Picture Mode to Standard

Lenovo

• Disable Local Dimming
• Disable HDR
• Disable Dynamic Contrast
• Set Color Mode Custom
• Set Scenario Modes to Panel Native

Xiaomi Mi Monitor

• Disable Dynamic Brightness
• Set Smart Mode to Standard

PRISM

• Set On-the-Fly Mode to Standard to allow DDC

Others

• Disable Ambient Light Sensing
• Disable Dual DisplayPort
• Set Dynamic Picture Mode to Custom or Standard to allow DDC
• Set Color Presets to Custom or Standard to allow DDC

DDC blockers

Other cases where DDC will not work:

• TV working as monitor
  • TVs don't support the VESA Monitor Control Command Set which is needed for sending DDC requests
• DisplayLink
  • DisplayLink uses proprietary drivers and while it has support for DDC, that functionality is not provided on macOS
  • Lunar can control DisplayLink monitors using the Network Control feature
• HDMI port of the 2018 Mac Mini
  • The HDMI port of these devices is blocking DDC requests without a known cause
  • Using the Thunderbolt connector fixes this (through USB-C-to-HDMI cable, Thunderbolt hub, etc.)
• Non-compliant hub/dock/adapter
  • This is the most common issue and it can't be fixed in software
  • Because most new Macs only have USB-C ports, most users use some kind of Thunderbolt hub or dock
  • A lot of these hubs block DDC requests completely,
  • If the hub supports more than one monitor, it usually forwards DDC requests to only one of them
  • Here are some of the hubs that are known to work:
    • Baseus HDMI, USB-C PD, 3 USB-A
    • Baseus HDMI, USB-C PD, 3 USB-A + Ethernet
    • Baseus HDMI, USB-C PD, 3 USB-A + Ethernet + SD/microSD reader

If Lunar doesn't fallback automatically to a working control mode, you can manually disable Hardware (DDC) controls from the Controls menu:

Lunar will fallback to adjusting brightness and contrast in software using Gamma values.

Notes about Gamma:

• Conflicts with other apps that use Gamma like f.lux so you have to quit them
  • Night Shift is a good alternative as it doesn't use Gamma
• Can only lower the brightness, not increase it
  • That's why you have to manually set the monitor brightness and contrast to maximum using its physical buttons
• Can't change the volume or input of the monitor
  • Those features require DDC

How can I go back to controlling only the monitor with the cursor on it?Copied Link

The active monitor hotkey behaviour was changed because a lot of users requested it.

Basically, Ctrl+Brightness is now the way to control the external monitor as that is also how macOS works natively with Ultrafine and Thunderbolt monitors.

You can still go back to the old behaviour (mostly) by setting the Brightness keys adjust in other modes dropdown to Display with cursor:

Why is Lunar changing my monitor colors?Copied Link

Lunar does not change colors in its default configuration. The app only sends brightness and contrast commands.

The problem is most likely that the monitor is reacting to those commands by switching to a custom color profile and affecting how the colors appear.

You can try locking the contrast to see if the monitor starts behaving correctly:

If that doesn't fix the issue, it means that your monitor doesn't accept brightness control on the color profile you have chosen. There's nothing we can do to fix this as the problem is inside the monitor firmware.

Is DDC safe? Will DDC commands lower the lifetime of my monitor?Copied Link

The EEPROM write limit

It is commonly believed that DDC commands will lower the lifetime of a monitor because the brightness values need to be stored in the EEPROM memory of the monitor and EEPROMs have a limited number of write cycles (usually around 100000).

I can't be certain for all monitor models, but I'm pretty sure this is no longer a real problem.

I've tested millions of writes on my LG 27UD88 and the monitor eventually failed because of the backlight controller chip. The memory chip was still working after 5 years of testing Lunar far more than what an average user would do in 15 years of usage.

Modern monitor chips

Most monitors use flash memory instead of EEPROM nowadays, and they also have RAM which can cache the DDC values without any write cycle limit, and only set them persistently in the flash after specific events.

For example my LG monitor was similar to this one from the iFixit teardown: LG 25UM58-P Teardown

It has a Novatek NT68 chip whose datasheet mentions the following:

• 128 Kbytes of on-chip flash memory for program memory
• 512 Bytes RAM Buffer for hardware DDC Port

So when doing a lot of DDC writes, like what Lunar does with smooth brightness transitions, those values will be stored in RAM, and won't affect the EEPROM write cycles.

Why do I see 300nits max when my MacBook can go up to 500 nits?Copied Link

The maximum brightness value is adapted by the macOS system based on the ambient light around you, Lunar simply reports that value directly.

If you flash a bright light on the MacBook's light sensor, you will see the brightness value go up to the real maximum nits.

To disable this behaviour, you can disable Automatically adjust brightness from the System Settings:

Is XDR Brightness safe?Copied Link

Yes, it is mostly safe. The MacBook and Pro Display XDR have been designed to sustain higher than 500nits of brightness.

1. macOS has a hard limit on the LED temperature and it will start lowering brightness forcefully way before it can do any damage
2. If used with mostly non-white backgrounds/apps, only the really close-to-white pixels will actually reach 1600 nits, while the rest will hover below 1000 nits, so they'll have plenty of time to cool down

While sifting through macOS internals, I've discovered a lot of logic for temperature thresholds, local dimming zones to keep pixels at their most efficient brightness, and safe measures for high power usage.

Based on the current knowledge, I'd say this is pretty safe to use, given that the system will not allow you to go past unsafe limits.

LED lifespan

Yes, the lifespan of the LEDs will be lowered if XDR Brightness is used daily, but no one can say by how much.

That's just how LEDs work.

Heat degrades the junction between the semiconductors, causing less of the electrical current to be converted to light which will make LEDs dimmer over time.

How are LEDs affected by heat?

macOS will stop XDR when the heat passes a threshold, but if you find that the warning icon (⚠️) appears often in the menu bar you might want to use higher brightness less often, or consider using Dark Mode.

Light text on dark backgrounds will keep the LEDs much cooler for longer periods of time, while still improving readability.

XDR acts strange, overblown or too bright colors, too much contrastCopied Link

The new Full Range mode is now the successor of XDR Brightness and is preferred because it removes most of the limitations that XDR had, like:

• It doesn't clip colors in HDR content
• The system adaptive brightness keeps working and uses the full range
• There's no lag when going from SDR to XDR brightness
• Can be kept on all the time without any downsides
• Can work in tandem with f.lux or other color management tools

Some downsides of Full Range:

• It only works on MacBook Pro XDR screens (can't be used on external monitors)
• The screen will flash one or two times when toggling Full Range

The system will still adapt the maximum nits of brightness based on the ambient light, so you might get a max of 800 nits in a dark room and 1600 nits in sunlight.

Disabling the system adaptive brightness will turn off this behaviour.

Why is Sub-zero Dimming disabled or not working?Copied Link

Sub-zero Dimming needs the range between 0% and 1% to be reserved for Lunar, otherwise when you get from 1% to 0%, the display will just turn off.

Make sure the Min Brightness of the MacBook screen is set to 1 or higher in Display Settings:

Is Sub-zero Dimming safe?Copied Link

Perfectly safe.

Sub-zero dimming darkens the colours in software after the lowest possible native brightness has been reached.

This can't cause any damage. It is equivalent to having dark colored or black pixels on the screen which is completely normal.

Why are the brightness/volume keys not working?Copied Link

Lunar needs Accessibility permissions to listen for Media Keys (brightness and volume).

To make sure the permissions are enabled, launch System Preferences->Security & Privacy and check if Lunar is present and enabled in the Accessibility list.

If it is, try removing it and re-adding it just be sure it isn't a code signing issue.

If the keys still don't work, it's possible that:

• the F14/F15 as brightness keys option is disabled and the keyboard used doesn't send brightness key events
  • enable the option on the Hotkeys page to allow Lunar to listen for default brightness key events
• the system permissions database is corrupted
  • Launch Terminal.app and run the following command: /usr/bin/tccutil reset All fyi.lunar.Lunar
  • Reboot the system, launch Lunar again, then give Lunar permissions when it asks
• your monitor doesn't support brightness/volume control

To check why brightness doesn't work, try running diagnostics by clicking on Open Lunar Diagnostics from the Lunar menu.

These are some of the cases where volume control is not available:

• If you see Software Control under your monitor name in Lunar
• If DDC is not responsive because of a non-compliant hub/dock/adapter (Lunar should prompt you about that)
  • In this case you could try a different way to connect the monitor to your Mac

Can I disable round corners when removing the MacBook notch?Copied Link

Yes, there's a hidden Round Corners setting on the built-in page.

Hover your mouse above the Auto Blackout button to make the setting appear, then scroll to change the setting:

Why are the brightness/contrast offsets not applied with App Presets?Copied Link

Lunar needs Accessibility permissions to know where the windows of an app are placed.

To make sure the permissions are enabled, launch System Preferences->Security & Privacy and check if Lunar is present and enabled in the Accessibility list.

If it is, try removing it and re-adding it just be sure it isn't a code signing issue.

If offsets still don't work, it's possible that the system permissions database is corrupted (see fix here)

How can I hide the monitor volume OSD?Copied Link

Unfortunately most monitors don't offer a way to hide their volume indicator OSD.

But Lunar offers a way to hide the macOS volume OSD so that at least you can see only one volume indicator.

Toggle the macOS Volume OSD setting to Hide inside the Lunar DDC menu

I disabled the F14/F15 keys but Lunar still controls brightness when pressing them.Copied Link

These are system settings and are not honored by any macOS app

Lunar (and all other apps) have to listen for brightness keys explicitly and the above settings don't have any effect on apps.

To disable Lunar's own media keys listener, uncheck F14/F15 as brightness keys on the Hotkeys page.

Note: not all keyboards have brightness keys that send non-F14/F15 key events.

Re-check the checkbox if brightness keys stop working after unchecking it.

Lunar asks for Accessibility permissions even though I already gave it permissions.Copied Link

Corrupted permissions database

First thing to try is to reset the System's permissions database.

Launch Terminal.app and run the following command:

Note: to run a command, paste the text in the Terminal and press Enter after that

/usr/bin/tccutil reset All fyi.lunar.Lunar

Then reboot the system and launch Lunar again.

If you get a message saying you don't have permissions to do the above, you can try resetting all permissions:

/usr/bin/tccutil reset All

Note: This will reset the permissions for all apps on the system.

And as a last resort, you can delete the whole permissions database using the following steps:

1. Open Finder
2. Go to /Library/Application Support/com.apple.TCC
3. Find TCC.db and move it to Trash

Then reboot the system and launch Lunar again.

Wrong app location

Where Lunar is launched from matters.

If you, for example, launched Lunar from Downloads and gave it permissions then, and then you moved it to Applications, then those permissions are not valid.

The macOS system stores permissions based on path and code signature.

You have to manually remove Lunar from the Accessibility list and add it again from the path you always launch it.

The system froze and I had to reboot the Mac. What happened?Copied Link

When a Mac device sends a command to a monitor through DDC, the whole system has to pause until the monitor replies.

Some monitors have very slow response times, and some don't respond at all.

You can try disabling Smooth Transition from the Lunar UI if possible:

If your system is constantly freezing and you can't disable those options in the Lunar UI, try doing the following steps in Safe Mode:

• Make sure Lunar is not running
• Open Terminal.app
• Run the following commands
  • defaults write fyi.lunar.Lunar refreshValues 0
  • defaults write fyi.lunar.Lunar smoothTransition 0
  • defaults write fyi.lunar.Lunar brightnessTransition 0
• If the above doesn’t work, you can reset Lunar settings by deleting the following file:
  • ~/Library/Preferences/fyi.lunar.Lunar.plist

Monitors behaving weird, system lag on screen wake?Copied Link

When the screens wake, Lunar forcefully re-applies the brightness and contrast values to all monitors to avoid a mismatch between what's in the UI and the actual monitor values.

This can cause lag if monitors take longer to respond or the monitors might behave in weird ways if the re-apply happens at the same time as the macOS display reconfiguration process.

You can disable this behaviour from Advanced Settings by unchecking the following checkbox (see the image below):

Controlling a monitor, actually changes brightness/volume/input on the other monitor.Copied Link

This is a fundamental issue with some monitor vendors.

You can read more about it in my blog post: Weird monitor bugs people sent me in the last 5 years

Does Lunar work with monitor X?Copied Link

Lunar doesn't implement controls on a per-monitor basis. It implements a standard called Display Data Channel (or DDC for short) that should be supported by all monitors.

So Lunar works with all monitors that:

• support DDC
• and are connected in such a way to the Mac so as to not block DDC commands

We can't give a clear answer because it depends on more than just the monitor itself.

It can depend on:

• the cable/adapter/hub used
• the Mac in question
• which port is used on the Mac
• which port is used on the monitor
• what settings the monitor has

The only way to know is to try it.

Lunar has a 14-day trial that activates automatically on first launch for the Pro features. After the 14 days, you can keep using Lunar's free features indefinitely.

How does Lunar change the brightness, contrast, volume, or input of a monitor?Copied Link

Display Data Channel

For most monitors, Lunar uses DDC (Display Data Channel) to read data or send commands directly to the monitor.

Examples of DDC commands:

• set brightness to 30 (or any value between 0 and 255)
• set contrast to 15 (or any value between 0 and 255)
• set volume to 80 (or any value between 0 and 255)
• mute audio
• switch input to HDMI 2
• power off (power on is not possible because a powered off monitor does not accept any commands)

After Lunar sends a DDC command, it's up to the monitor firmware to do something with that command.

Lunar can't know if, for example set brightness to 50, did actually cause a brightness change in the monitor.

Some monitors don't accept DDC in some cases and can react in a few various ways to DDC commands:

• Ignore the command and do nothing
  • e.g. you change the brightness value in Lunar but the monitor doesn't change at all
• Crash, lose video signal, turn off
  • see here how to disable DDC in that case: Bad DDC issue
• Flicker green screen or weird colors
  • disabling DDC is the only solution here as well: Bad DDC issue

Lunar also doesn't have any control on the monitor OSD so if brightness or volume appears as changing in both macOS and monitor OSD, that's just how your monitor works and can't be changed.

Apple DisplayServices

Apple vendored displays get special treatment as Lunar uses an implementation hidden inside macOS Display Services to control them natively. The list of Apple displays include:

• Studio Display
• Pro Display XDR
• LG Ultrafine for Mac
• Thunderbolt Display
• LED Cinema (when connected via USB)

You can see when Lunar uses this method when you see Apple Native written under the monitor name in the Lunar window.

The DisplayServices method doesn't use DDC for brightness, it uses a proprietary protocol implemented by Apple through USB (as opposed to I2C for DDC).

Contrast, volume, input and power will still be controlled through DDC as DisplayServices only supports brightness changing.

Auto/Sync mode is switched to Manual mode when the MacBook lid is closed.Copied Link

This can be caused by the clamshell mode detection setting from Advanced settings:

Try disabling the clamshell mode detection to see if it fixes the issue.

Lunar quits randomly.Copied Link

This can be caused by the following setting from Advanced settings:

The setting is for people running into macOS bugs where a monitor can no longer be controlled until the app is restarted. They might see a lock icon when brightness keys are pressed.

Try disabling Auto Restart to see if it fixes the issue.

How do hotkeys work in Lunar?Copied Link

Media Keys

Media Key events are sent when the checkbox for Use F1, F2, etc. keys as standard function keys on external keyboards is not checked and you press:

• F1/F2 (brightness)
• F10/F11/F12 (volume)
• Touchbar buttons for brightness and volume
• Touchbar slider for brightness when using Lunar's Sync Mode

Media Keys also need Accessibility permissions to be enabled for Lunar, while simple hotkeys can work without that.

Hotkeys

Simple hotkeys are what you can configure on Lunar's HOTKEYS page under the Function Keys section. These don't need special permissions.

If you haven't checked the checkbox for Use F1, F2, etc. keys as standard function keys on external keyboards, you will have to hold Fn when pressing hotkeys that contain function keys like F1, F2 etc. Otherwise, something like Command+F1 will actually send Command+Brightness which is a Media Key.

Why does the monitor look so dark?Copied Link

If you see the Software Dimming tag under the monitor name in the Lunar UI, then Lunar can't use DDC to control this monitor.

Lunar can approximate a decrease in brightness by changing the software gamma tables to make the colors look darker.

This doesn't change the hardware brightness as DDC does and can only decrease brightness, not increase it.

You have to manually set the monitor's brightness and contrast (using the monitor physical buttons) to the highest possible values that look good for your monitor.

Can I use Lunar with f.lux?Copied Link

Yes, but with a few caveats.

F.lux adjusts the colour temperature of your screen using the macOS Gamma API, which is the same method used by Lunar for a bunch of features:

• Software Dimming
• Sub-zero Dimming
• Facelight
• Blackout
• XDR Brightness

If two apps use the Gamma API at the same time, conflicts will appear and unexpected color problems will happen until those apps are quit.

Possible solutions

Disable Gamma

If you don't need the above features, you can disable the usage of Gamma completely from Advanced Settings

Use Overlays

If XDR Brightness is not used and you want to keep using the other features, you can move to using an Overlay-based approach from the Controls menu of each display.

Use Night Shift

macOS Night Shift doesn't conflict with Lunar at all as it uses a lower level API to alter color temperature.

It can also get smarter schedules, app exclusion, keyboard temperature control and more using the free Shifty app.

HDR breaks when using Lunar. Overblown, washed-out colors for HDR videos and photos.Copied Link

This is actually macOS disabling HDR whenever there's an app using the system Gamma API.

Any app using the Gamma API will trigger this until the app is quit: f.lux, MonitorControl, Gamma Control etc.

To fix this, you can disable the usage of Gamma completely from Advanced Settings

This will make the following features use an overlay instead of the Gamma API:

• Software Dimming
• Sub-zero Dimming
• Facelight
• Blackout
• XDR Brightness

Technical explanation

HDR on macOS uses an electro-optical transfer function (EOTF) that's incompatible with the Gamma transfer function.

So whenever an app changes the default Gamma tables of a display, macOS has to disable HDR to allow for that new Gamma value to be applied.

It should be possible to switch HDR back on when Gamma is reset to default, but unfortunately this doesn't seem to happen. macOS keeps turning off HDR even after Lunar tries to reset Gamma using CGDisplayRestoreColorSyncSettings().

The only solution is to quit the app to make macOS re-enable HDR.

Location mode doesn't work very well on cloudy days. Can you fix this?Copied Link

I tried to include the local cloud cover into the Location Mode algorithm but failed because of multiple reasons.

• Weather APIs are expensive
  • Location Mode computes brightness and contrast every minute, doing an API request per minute, per user, would add up to a lot of requests
  • I tried implementing some caching mechanism but it didn't help much
• Cloud Cover percentage can be quite irrelevant
  • On some days, I would get a 95% cloud cover yet it was sunny where I stood
  • This can happen if the weather station sensors are not close to your specific location
• Factoring in cloud cover is hard
  • The way the current algorithm is written doesn't allow for adding additional factors easily
  • A major refactor would be needed to make this work

If you can't use Sync Mode but would like your monitors to better react to the changes in the ambient light around you, you could try Sensor Mode.

One monitor is brighter than the other. How can I adjust so that they look the same?Copied Link

If you use one of Lunar's adaptive modes (Sync, Location, Sensor), you can simply decrease the brightness/contrast of the brighter monitor until it looks the same as the other one.

You can use Shift+Brightness keys to adjust only the active monitor when the MacBook lid is closed, or use the Lunar UI otherwise.

Lunar will learn from that manual adjustment and try to match the monitors better in the future.

If the discrepancy appears again, just keep adjusting the brighter/darker monitor until Lunar has enough data to match a perfect curve.

I have 3 monitors but only 2 of them can be controlled by Lunar. Can this be fixed?Copied Link

This usually happens if you use identical monitors which have the exact same firmware data. Lunar tries to differentiate between them using multiple workarounds but it can still fail.

This can also happen if you use a Thunderbolt hub with two or more monitor connections. Most of these hubs forward DDC messages to only one of the monitors.

Finally, it's possible that the not-working monitor is connected through a non-compliant adapter.

Check the Non-compliant hub/dock/adapter section in this question for more details.

Can Lunar turn off the MacBook display while external monitors are used?Copied Link

Yes, Lunar can do that using a feature called BlackOut.

Read more about it here: https://lunar.fyi/#blackout

Does Blackout really disable the screen and free up GPU resources?Copied Link

Apple Silicon

Yes, BlackOut really disables the screen, just like it would be off/disconnected.

On Apple Silicon, BlackOut uses a hidden Disconnect API of macOS to do that, which works from macOS 13.0 and up. If you take a look at System's Display Settings, you'll see that the MacBook display is not listed there when BlackOut is active.

Intel

No, BlackOut doesn't disconnect the screen completely on Intel Macs because the Disconnect API is not available there.

What BlackOut does on Intel (example with turning off the MacBook display) is the following:

1. Sets the native brightness of the MacBook display to 0
2. Sets the Gamma tables of the MacBook display to a list of zeroes (which makes all the colors compute to black)
3. Mirrors the external monitor to the MacBook display so that:
   • the monitor keeps its native resolution
   • windows and apps don’t get trapped in a non-visible display
4. Keeps all the above things in place even when the system forcefully re-enables the display when not wanted

Can Blackout enable the second monitor on M3 MacBooks without closing the lid?Copied Link

Short answer: not yet

Entry-level M1 and M2 MacBooks are notorious for only having support for one external monitor.

Since M3, closing the lid of the MacBook enables using a second monitor (because it frees up one internal Display Coprocessor by disabling the built-in screen).

While Blackout does indeed disable the built-in screen without closing the lid, it seems that this action doesn't also enable the second monitor on M3 chips and later.

We're working on reverse engineering and implementing the function for newer chips.

Monitor looks weird after screen orientation or resolution change!Copied Link

This happens in rare cases and the cause is still unknown.

To fix the issue, restart your computer.

The system will revert automatically to the last known good resolution.

Usually after restarting, the orientation/resolution controls in Lunar start to work reliably.

Why does Lunar need to 'control this computer using accessibility features'?Copied Link

Accessibility Permissions are needed for the following features:

• Media Keys (listening for brightness/volume key presses)
• App Presets (applying offsets based on what app is visible on each monitor)

Lunar has to tap into the global key events pipeline to know when a brightness or volume key has been pressed.

Brightness and volume key events are always global, not dispatched to the currently active app like other keys.

This means there's no way to listen to brightness/volume keys in a private way, but there's no privacy issue here as Lunar only cares about the following keys:

• Brightness Down (or F1)
• Brightness Up (or F2)
• Audio Mute (or F10)
• Volume Down (or F11)
• Volume Up (or F12)

All the other key events are ignored by Lunar.

If you don't need the Media Keys or the App Presets functions, you can disable them so Lunar doesn't ask for Accessibility Permissions.

Disabling App Presets

Disabling Media Keys

Input switching doesn't work. The monitor just blinks.Copied Link

This is a common problem in some newer monitors.

If the monitor is LG, try using the LG specific inputs added in v6.2.0:

The new inputs can also be accessed from macOS Shortcuts or from the CLI using commands like:

lunardisplayslginputlgHdmi1 # Newly added inputs: # lgHdmi1 lgHdmi2 lgHdmi3 lgHdmi4 # lgUsbC1 lgUsbC2 lgUsbC3 lgUsbC4 # lgDisplayPort1 lgDisplayPort2 lgDisplayPort3 lgDisplayPort4

Some LG models respond to the 3 and 4 inputs while others use the 1 and 2 inputs.

For example 32UD99 uses USB-C 3 and DisplayPort 3 while 32QN650 uses USB-C 1 and DisplayPort 1.

If the monitor is not LG, then it's possible that the vendor chose to not implement the input switching DDC control code, and there's nothing we can do about it.

High CPU Usage?Copied Link

Looking at the % CPU usage is not a very accurate way of judging the app's efficiency.

Especially on M1, read more about it in this article: CPU percentage is misleading on M1 Macs by The Eclectic Light Company

Usually, you shouldn't look at the % CPU field, but at the CPU Time metric. By default Activity Monitor updates every 5 seconds, so even if the CPU % was at 20% for a few milliseconds, you'll still see it for 5 seconds.

Even with the Very often (1 sec) setting, the % CPU metric is still not best for judging app efficiency.

In the following case, from the time Lunar started running (1 day and 2 hours ago) until now, it only consumed about 3 minutes of CPU time.

That's an incredibly small amount of CPU power used for an app that has to:

• Constantly poll the MacBook display to check for brightness changes
• Listen for monitor connection/disconnection
• React to built-in display brightness changes in less than 100ms when there are a lot of small changes (see Dynamic Polling)
• Send low-level I²C messages to all monitors
• Check if visible app windows are included in the App Presets list
• Search for external light sensors on the network periodically

❯echo"Lunar was launched "(soulver'(now - '(lsappinfoinfo-onlykLSLaunchTimeKeyLunar|cut-d=-f2)') as time')" ago" Lunarwaslaunched1day1hour50min5sago ❯soulver'(3 min 25 s) is what % of (1 day 1 hour 50 min 5 s)' 0.220%

If you compare that to other frequently used utilities like the native macOS Messages.app for example, you'll see their CPU Time can be much higher than what Lunar uses.

For example in the same case, Messages was also launched 1 day and 2 hours ago and it already consumed 18 minutes of CPU time.

❯echo"Messages was launched "(soulver'(now - '(lsappinfoinfo-onlykLSLaunchTimeKeyMessages|cut-d=-f2)') as time')" ago" Messageswaslaunched1day1hour54min18sago soulver'(18 min 35 s) is what % of (1 day 1 hour 54 min 18 s)' 1.196% The brightness decreases after 37/38/39 then increases again.Copied Link

Your monitor has a non-standard DDC value range.

Adjust the max value in the DDC menu in Lunar as following:

• If the max value for brightness is 255, set it to 100
• If the max value for brightness is already 100, set it to 37

Is Lunar native or an Electron app?Copied Link

It's native

Lunar is a native app written in efficient Swift code. It doesn't use Electron or browser-based technologies.

Lunar is also open-source so you can check that for yourself: Github - alin23/Lunar

Checking for Electron

You can see if an app is Electron based by looking at its Frameworks folder.

For example, this is Discord containing Electron Framework.framework:

Discord.app

based on Electron

And this is Lunar:

Lunar.app

does not contain Electron

License doesn't stay activatedCopied Link

This can happen for a number of reasons:

• App bundle was modified in any way
• The license files were corrupted
• Paddle domains are blocked
• Lunar’s internet access has been blocked

To fix this, you can try uninstalling Lunar completely then reinstalling it and making sure Paddle can be reached.

1. Uninstall

To uninstall Lunar completely there are two methods:

Using brew:

brew uninstall --cask --force --zap lunar

Using AppCleaner or PearCleaner:

• Download and open AppCleaner or PearCleaner
• Drag and drop the Lunar app from the Applications folder into the AppCleaner/PearCleaner window

Using LaunchPad (pre macOS Tahoe 26):

• Open Launchpad from the Dock or Spotlight
• Type Lunar to find the app
• Hold the ⌥ option key and click on the x button

2. Reinstall

Download the latest version of Lunar and move it to Applications.

3. Make sure Paddle can be reached

Make sure the following domains are not blocked in your network:

• paddle.com
• paddleapi.com
• v3.paddleapi.com

For example, loading v3.paddleapi.com/3.2/license/verify in a browser (or with curl) should show a response like the following:

{ "success":false, "error":{ "code":102, "message":"Unable to authenticate" } }

If it shows a browser error or if it keeps loading continuously, then the domain is blocked.

4. Activate the license

How can I see Lunar logs?Copied Link

You can do that either through Console.app or through the log Terminal command.

Terminal

Streaming logs for viewing:

logstream--leveldebug--source--stylecompact--predicate'subsystem BEGINSWITH "fyi.lunar.Lunar"'

Streaming and collecting logs to a file:

logstream--leveldebug--stylecompact--predicate'subsystem BEGINSWITH "fyi.lunar.Lunar"'|tee~/Desktop/lunar.txt # Compress the logs for sending gzip-9-f~/Desktop/lunar.txt

Console.app

1. Write fyi.lunar.Lunar in the search bar and press Enter
2. Click on Any and choose Subsystem
3. Make sure Info and Debug messages are enabled in the Action menu
4. Start streaming logs

Saving logs License availability on multiple MacsCopied Link

The license can be used on up to 5 Macs at the same time.

Once you activate the license on a 6th Mac, the first Mac will be automatically deactivated so you can keep using the license indefinitely.

You can use the license on both personal and work computers, as long as you don't share the license code with others.

Can Lunar fix DPI or do flexible scaling and custom resolutions like BetterDisplay?Copied Link

In short, no, but BetterDisplay can be used alongside Lunar with minimal configuration to achieve the same results.

Why doesn't Lunar have these features?

Me and BetterDisplay's dev are friends and often collaborate on features that can be shared between the two apps.

We agreed to keep the core features of each app separate to avoid conflicts and to keep the apps lightweight and focused on their main goals.

What are some alternatives for Windows/Linux?Copied Link

Windows

• TwinkleTray
• Monitorian
• ClickMonitorDDC
• ControlMyMonitor

Linux

• ddcutil (a command-line tool, and what most UI tools are based on)
• Luminance
• Gnome applet
• KDE Plasma widget

Lunar does not start on macOS SequoiaCopied Link

It appears macOS Sequoia corrupts some secure settings files of Lunar.

To fix it:

1. Uninstall Lunar as seen here: How to uninstall
2. Then reinstall by downloading from here: Lunar.dmg

Lunar is lagging, hanging or constantly restartingCopied Link

Usually this is caused by temporary problems in various subsystems of macOS like CoreLocation or CoreAudio.

Some possible causes:

Location service

If you don't use Location Mode, run the following command in Terminal to stop Lunar from checking for location permissions which can cause hangs on some systems:

defaultswritefyi.lunar.LunarmanualLocationtrue

Volume keys

Try restarting the CoreAudio service by running the following command in Terminal:

killallcoreaudiod

If this fixes the lag, then the problem comes from the audio subsystem of macOS. If you don't need to change the volume of the monitor audio interface, disable Listen for volume keys from the Hotkeys page.

How does Auto Mode choose the best mode?Copied Link

Auto Mode

1. Sync Mode

Conditions:

• MacBook with lid open
• iMac
• monitor configured as Sync Source

Reason:

Sync Mode is chosen because the system adaptive brightness will use the integrated light sensor to adapt the built-in display, and Lunar can take advantage of a hidden observer API to react to those changes and sync them to the external monitors as fast as possible.

2. Sensor Mode

Conditions:

• wireless ambient light sensor detected on the network

Reason:

There's probably a good reason why that sensor is available, so Lunar assumes that the user wants to use the sensor over any other adaptive mode.

3. Location Mode

Conditions:

• location permissions granted
• fallback to IP geolocation works in case the system CoreLocation fails

Reason:

If sunrise/sunset times can be computed for your location, then Location Mode will be chosen to adapt the brightness automatically throughout the day.

4. Manual Mode

Conditions:

• If none of the above conditions are met

Auto Mode is not configurable in any way, it chooses the mode solely based on the hardware you have available.

The conditions are checked every 15 seconds, but may be checked less often if the system needs the CPU for something more important.