Archives / Search ›

Setting display brightness: updated tool

Here is my cleaned-up brightness tool, which now uses the IOKit APIs instead of the weird O3Engine SPIs that the old version did.

Quick example:

% ./brightness 
usage: ./brightness [-m|-d display] [-v] <brightness>
   or: ./brightness -l [-v]
% ./brightness -l
display 0: main display, ID 0x4270a80
display 0: brightness 0.734375
% ./brightness -v 0.3
display 0: brightness 0.296875

-m changes the brightness of the main display; -d changes brightness of whatever display number/ID you provide. -l -v dumps display attributes—sorry for the ugly XML output, but CoreFoundation claims to be unable to output an OpenStep-format property list even though Cocoa has no problem doing the same.

(February 2014: Please see an updated version of this code on GitHub; it makes the -v output more readable among other changes.)

28 comments on “Setting display brightness: updated tool”

  1. matt
    7 July 2006 | 11:28 PM


    i had to move the “const CFString…” (line 9) to inside of the main function to get this to compile on os x 10.4.7, xcode 2.3 (using your 1st line comment in the terminal to compile).


  2. 15 August 2006 | 4:57 AM

    When you say “Cocoa has no problem”, are you referring to -description or NSPropertyListSerialization? AFAIK, the latter simply maps to the CF functions, and will fail in the same way.

  3. 15 August 2006 | 11:11 AM

    I’m just referring to -description. I don’t care about serialization, just making something human-readable.

  4. 13 November 2006 | 12:03 PM
  5. dirk schelfhout
    5 January 2007 | 4:30 AM

    I run this code on an intel imac with external 23 inch display. It doesn’t work for the external display :
    [Session started at 2007-01-05 11:26:18 +0100.]
    display 0: main display, ID 0x424a6d5
    /Users/schelfd/dev/testB/bright/build/Debug/bright: failed to get brightness of display 0x424a6d5 (error -536870201)display 1: ID 0x4271600
    display 1: brightness 0.000000

    bright has exited with status 0.

    I believe the error is : // device read locked
    I tried running as root as well and changing the main display
    I run 40.4.8

  6. 8 January 2007 | 11:26 AM

    Yeah, I’ve had this report from someone else too. I don’t have a dual-display machine to test with unfortunately – when I first wrote it, I had access to a Power Mac G5 with two displays and it did work fine on both.

    You are using an external Apple Cinema display (aluminum bezel, DVI)?

  7. Grant
    12 October 2007 | 4:10 PM

    Confirmed that the IOKit-based methods do not work with Intel-based desktop systems with externally-attached Apple Cinema displays.

    In my specific case, IODisplayGetFloatParameter(…, CFSTR(kIODisplayBrightnessKey), …) returns ‘kIOReturnUnsupported’ on a Mac Pro with twin 20″ Apple Cinema displays whereas it works just fine on my MacBook Pro C2D.

  8. Drew
    26 February 2009 | 6:03 PM

    I’m running into this problem too; IODisplaySetFloatParameter() is returning ‘kIOReturnUnsupported’ when I have multiple displays attached.


  9. Grant
    3 March 2009 | 9:41 AM

    With dual monitors and Intel vs. PowerPC environments, the only thing I have found to work reliably across all system configurations is the O3EngineWireProtocol using the private DisplayServices framework. More at:

  10. 3 March 2009 | 9:44 AM

    That is the case, unfortunately; that reverse-engineering time was worth it after all.

  11. Ryan
    28 December 2009 | 9:54 AM

    On my MacBookPro with “automatically adjust brightness as ambient light changes” checked, the brightness does change to what I set it to but then goes back to the original setting. Instead of trying to change the code of brightness, I was trying to find out how to uncheck the above checkbox, run brightness and then recheck the above checkbox all via the command line. I figure it’s defaults write something -bool YES/NO

    Any help would be great.


  12. 28 December 2009 | 10:42 PM

    Sorry, no idea… you’d have to twiddle some private stuff in IOKit I think; wouldn’t be as simple as setting a user default.

  13. Ryan
    29 December 2009 | 12:42 AM

    Well, that’s no fun. Probably why nothing useful has been showing up in any Google searches though.

  14. NIXin
    30 January 2011 | 3:13 PM

    Hi there!
    What’s the license on this code? Could I change it and use for a little script to remember the brightness value on hackintoshes? ;)

  15. 30 January 2011 | 10:28 PM

    BSD-ish – basically just give me credit in whatever you write based on it and I’ll be happy.

  16. NIXin
    31 January 2011 | 2:54 AM

    Great, thanks man!

  17. Ken
    8 October 2011 | 9:30 AM

    Solved my problem, thanks. Looks like some output strings are missing newlines though; check lines 59, 79, 96, 98, 117, 133, 143. Cheers.

  18. 8 October 2011 | 2:32 PM

    errexit prints a newline (see line 17). Glad it helped!

  19. Jon
    13 December 2012 | 8:13 AM

    Does this work in Mountain Lion?
    Is it capable of adjusting the brightness below GUI settings (1 bar with F1/F2, prefpane slider)?

  20. 13 December 2012 | 12:33 PM

    Yes, brightness.c works in Mountain Lion. If you’re seeing discrete “steps” with the prefpane slider, that’s a hardware limitation; using another method to set the brightness won’t help. It really depends on the display. On some external Apple Cinema Displays I’ve tried with, you get relatively continuous brightness; on most if not all laptop displays I’ve tried, you get the same ~15 steps you get elsewhere.

  21. Jon
    13 December 2012 | 1:22 PM

    Can it efectively adjust brightness between 0 and 1/16? The quarter steps with ⇧⌥F1/F2 don’t work actually, and besides I’m searching for a command line method to dim the display when working late at night.

  22. 13 December 2012 | 1:29 PM

    Yes, sure. It’ll just round to the closest brightness percentage. On my MBP, a quarter step from 0 is 0.015625; a full step is 0.0625, but just as you describe, they both map to the same brightness level.

    Incidentally, you could have answered these questions a lot faster by just trying it :-)

  23. Steven
    13 May 2013 | 5:35 AM

    Unfortunately, i cannot get it to adjust my external display on mbp 13″ early 2011 via HDMI (on thunderbolt).

    ./brightness\ 2 -l
    display 0: main display, ID 0x335841c1
    ./brightness 2: failed to get brightness of display 0x335841c1 (error -536870201)display 1: ID 0x4273140
    display 1: brightness 0.752930

    any ideas?

  24. 13 May 2013 | 10:11 AM

    Are you able to adjust the brightness through Displays System Preferences? I’ve not had the opportunity to test with HDMI or Thunderbolt displays.

  25. Steven
    14 May 2013 | 2:43 AM

    Well as you can see in my previous post, i can adjust monitor 1 (mbp display) but monitor0 (hdmi, full hd external) refuses.

    So yes, i can change my internal screen’s brightness through keyboard or display prefpane but there are no such settings for an external monitor.

  26. 14 May 2013 | 10:15 PM

    The brightness command line tool uses the same mechanism as the Display System Preferences pane, so it’s not going to help you in this case. I’m not sure if HDMI supports remote brightness control. Sorry!

  27. 5 September 2014 | 10:30 AM

    Since part of this code is deprecated by Apple as of OSX 10.9, you may want to check out the implementation here. ( It has no deprecated component. Compiles fine once the SDK is changed.

    PPS. Hats off to any MD/PhD. As my son is part of the same program you graduated from.

  28. 27 September 2015 | 2:56 AM

Leave a reply