Skip to content

About

Beautifully simple display management for macOS. Take control of brightness, contrast, HiDPI resolutions, color profiles, and more – seamlessly integrated, completely free, and open source.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

 
 

Latest commit

 

History

27 Commits

Folders and files

Repository files navigation

FreeDisplay: free, open-source display control for macOS

Latest release macOS 14+ Swift 6 Zero dependencies

A free, open-source menu bar app for managing your displays.
Hardware brightness, HiDPI, resolutions, color profiles, presets, and keyboard shortcuts.

Download · Features · Install · Report an issue

Credit: FreeDisplay was created by huberdf. This repository is a fork maintained by teezyyoxo. It adds a redesigned Liquid Glass interface, configurable brightness shortcuts, a Settings window, and a number of fixes. The original app, its architecture, and its DDC and HiDPI groundwork are huberdf's work. See the original repository.


Why FreeDisplay?

BetterDisplay is a great app, but its best features sit behind a paid Pro license. FreeDisplay implements the essentials as a free menu bar app with no third-party dependencies and no account.

Screenshots

Menu panel with a brightness slider for each display
One panel for every display. Per-display brightness, presets, and tools.
Expanded display card showing modes, color profiles, and image adjustments
Everything per display. HiDPI, resolutions tagged Native or HiDPI, color profiles, and image adjustments.

Settings

Brightness Keys settings with permission status
Brightness Keys
Shortcut recorder for primary, secondary, and both displays
Shortcuts
Appearance settings with System, Light, and Dark themes
Appearance

Features

Brightness

  • Hardware brightness and contrast (DDC/CI) for external displays, over IOKit I2C on Intel and IOAVService on Apple Silicon.
  • Software brightness through per-display gamma tables, with smooth transitions.
  • HDR / XDR extra brightness enabled by default on compatible displays, with three steps at 110%, 120%, and 130% and an optional per-display opt-out. See HDR brightness.
  • Brightness keys for external displays. The keys adjust the display under the mouse pointer. FreeDisplay's HUD shows the display, percentage, and HDR step count. Media keys and keyboards that send F14 and F15 are supported.
  • Custom shortcuts for the primary display, the secondary display, both displays, and "match secondary to primary".
  • Auto brightness that follows the built-in display's brightness.

Resolution and HiDPI

  • Browse and switch every display mode, each tagged Native or HiDPI.
  • HiDPI through display override plists, plus virtual HiDPI displays.
  • Display arrangement. Drag displays into position.
  • Virtual (dummy) displays for headless setups.

Color and image

  • ICC color profiles per display, through ColorSync.
  • Image adjustments. Contrast, gamma, gain, color temperature, quantization, and per-channel RGB.
  • Notch management. Hide the MacBook notch with a black overlay.

Everything else

  • Presets. Save and restore a full display setup with one click.
  • Liquid Glass interface on macOS 26 and later, with a blur material fallback on macOS 14 and 15. Choose System, Light, or Dark.
  • Launch at login and optional update checks.

Not included

  • Screen streaming and picture-in-picture
  • EDID override, which requires SIP to be disabled

Installation

Download

  1. Download the latest FreeDisplay ZIP from Releases.
  2. Unzip it and move FreeDisplay.app to Applications.
  3. Open FreeDisplay. The current release is development-signed and not notarized.

Gatekeeper: If macOS blocks the app, open System Settings → Privacy & Security, select Open Anyway, and confirm. Only do this if you trust the download.

macOS may ask you to grant the permissions below again after an update.

Build from source

brew install xcodegen
git clone https://github.com/teezyyoxo/FreeDisplay.git
cd FreeDisplay
xcodegen generate
xcodebuild -scheme FreeDisplay -configuration Release build

Builds are ad-hoc signed by default. To sign with your own identity, create Config/Local.xcconfig. It is gitignored and overrides the defaults:

CODE_SIGN_IDENTITY = <your certificate name or SHA-1>
DEVELOPMENT_TEAM = <your team ID>

Running ./build.sh also builds a DMG, exporting ad-hoc signed by default. A gitignored ExportOptions.local.plist overrides the export options.


Permissions

Permission Why
Accessibility Intercept brightness keys and shortcuts
Input Monitoring See key presses system-wide

Grant both to FreeDisplay itself, not to the app that launched it. Settings → Brightness Keys shows whether each is granted.

FreeDisplay needs no internet connection. The only network request is the optional update check against the GitHub Releases API.


How it works

  • External monitors: DDC/CI over I2C (Intel) or IOAVService (Apple Silicon) controls hardware brightness, contrast, and more.
  • Built-in display: CoreGraphics gamma tables provide software brightness.
  • Brightness keys: a CGEventTap intercepts the keys and routes them to the display under your pointer.
  • Auto brightness: the built-in display's brightness is read through the CoreDisplay private API, and external displays follow it proportionally.
  • HiDPI: display override plists give persistent HiDPI modes. A replug is needed before macOS loads them.

Tech stack

  • Swift 6 and SwiftUI (MenuBarExtra), with AppKit where needed
  • IOKit for DDC/CI
  • CoreGraphics for enumeration, resolution, and arrangement
  • ColorSync for ICC profiles
  • CGVirtualDisplay and CoreDisplay (private APIs, loaded at runtime)
  • No third-party dependencies

Project structure

FreeDisplay/
├── App/        # AppDelegate and app entry point
├── Models/     # DisplayInfo, DisplayMode, DisplayPreset, ShortcutBinding
├── Services/   # DDC, brightness, gamma, resolution, HiDPI, shortcuts, and more
└── Views/      # Menu panel, Settings window, shared glass design system

Contributing

Issues and pull requests are welcome.

  • Edit project.yml, not the .xcodeproj, then run xcodegen generate.
  • Swift 6 with SWIFT_STRICT_CONCURRENCY: minimal.
  • MVVM: View → ViewModel → Service.
  • Keep personal signing details in Config/Local.xcconfig, never in tracked files.

License

The original project's README declares the MIT License, and this fork keeps it. The original repository does not currently include a LICENSE file, so see huberdf/FreeDisplay for the author's terms. Original work © huberdf.

Acknowledgments

About

Beautifully simple display management for macOS. Take control of brightness, contrast, HiDPI resolutions, color profiles, and more – seamlessly integrated, completely free, and open source.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages