Awesome Open Source
Awesome Open Source


Intelligent adaptive brightness for your external display

M1 doesn't provide DDC support so Lunar can't work on those devices yet.

Note: Lunar changes the actual (physical) brightness and contrast of the monitor.

It doesn't use a software overlay.

Table of Contents

Installation methods

Display page Settings page Hotkeys page


  • Sync-based Adaptive Brightness (and contrast) based on the built-in light sensor of the Macbook or iMac
  • Location-based Adaptive Brightness (and contrast) based on the sunrise/sunset times in your location
  • App Exception list if you need more brightness for specific activities (watching movies, design work)
  • individual settings per display
  • Manual controls hotkeys for setting brightness and contrast that respect the min/max values per monitor

It doesn't interfere at all with the native adaptive brightness that macOS implements for the built-in display.

Tested and known to work with the following types of connections

  • HDMI (1.0 - 2.1)
  • DisplayPort (1.0 - 2.0)
  • Thunderbolt 3 (USB Type-C)
  • Thunderbolt 2 (mini DisplayPort)
  • VGA
  • Adapters that forward DDC messages properly


  1. If Lunar doesn't start at all, try installing the Swift 5 Runtime Support from Apple
    • Some older macOS versions don't have these libraries pre-installed and Lunar requires them
  2. If Lunar freezes your system, make sure you have the latest version installed
    • Version 2.9.1 was trying to read the monitor brightness periodically through DDC and if the monitor didn't support that, the system freezed
  3. If you activated the Read Monitor Brightness Periodically and your system freezes when using Lunar
    • Make sure Lunar is not running
    • Open
    • Run the following command defaults write site.lunarapp.Lunar refreshValues 0
    • If the above doesn't work, you can reset Lunar settings by deleting the following file:
      • ~/Library/Preferences/site.lunarapp.Lunar.plist
    • If Lunar starts at login and freezes the computer before you can do anything, try doing the above in Safe Mode
  4. If you get system lag or occasional UI freeze, this might be caused by a slow DDC response from the monitor
    • Make sure Smooth Transition is turned off in Lunar preferences
    • If you are using Sync mode, set the Polling Interval to a bigger value like 5 seconds to avoid making DDC requests too often
  5. If you don't get the Location Permissions prompt, run the following commands in a terminal and restart Lunar:
    sudo defaults delete /var/db/locationd/clients.plist site.lunarapp.Lunar
    sudo pkill -9 locationd


  • Lunar usually doesn't work with monitors connected through USB hubs/docks/adapters because a lot of them don't forward DDC messages properly
  • Sync mode doesn't work when the Macbook lid is closed because the light sensor is completely covered


Run make dev to prepare dev environment.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
swift (7,540
macos (1,661
monitor (162
swift5 (110
display (35
brightness (26
contrast (17
macbook (16

Find Open Source By Browsing 7,000 Topics Across 59 Categories