DisplayToggle

A tiny, free macOS menu bar app that soft-disconnects any display — no cable unplugging — and switches resolutions.

English · 简体中文

---

Features

• Disconnect / reconnect any display from the menu bar. macOS treats a disconnected display as if its cable were unplugged: windows move to the remaining screens and the GPU stops driving it. Works for external monitors and the MacBook built-in display.
• Resolution & refresh rate — lists every mode, including HiDPI and the system default.
• Brightness & volume sliders right in the menu. External monitors are controlled over DDC/CI (Apple silicon; the monitor must support DDC), the built-in display natively. Volume follows the current output device, using the monitor's own volume over DDC when audio goes through HDMI/DisplayPort.
• Reset — each disconnected display has a ↻ button that re-checks it: reconnect it if it's still plugged in; if it was unplugged, drop it from the menu until it's plugged back in.
• Keep Awake — Caffeine-style: keep the Mac running instead of sleeping, even with the lid closed and no display attached. Pick Always, On Battery, or Plugged In; it follows the power source automatically. Click the selected option again to turn it off. Plugged in, it works like caffeinate -i -s and needs nothing else. On battery, macOS ignores that, so preventing sleep with the lid closed needs a one-time admin approval (asked only for Always and On Battery), which installs a sudoers rule (/etc/sudoers.d/displaytoggle) allowing only pmset -a disablesleep 0|1. Below 10% battery it lets the Mac sleep again, so it never runs flat. Everything is undone when the app quits.
• Reset Connections (⌘R) — reset every display at once: reconnect everything that was disconnected and forget displays that were physically unplugged. Resolutions are left alone.
• Safety net — you can't disconnect the last active display, and with the lid open the built-in display comes back on by itself once no external display is left (e.g. built-in disconnected, then the external cable is pulled). Nothing else is reconnected behind your back: an external display that sleeps or is switched off stays the way you left the others.
• Session-only — disconnections reset on logout/restart, so you can never lock yourself out with a black screen.
• Launch at Login toggle (native macOS Login Items). The checkmark always shows the real system state; if macOS needs your approval, the item says so and a notification takes you to System Settings.
• English / 中文 UI, following the system language or chosen in the menu.
• Command-line interface for scripts, Shortcuts, and hotkeys.

Requirements

macOS 13 Ventura or later, Apple Silicon or Intel.

Install

Download: grab DisplayToggle-x.y.z.zip from Releases, unzip, and move DisplayToggle.app to /Applications. The app is ad-hoc signed (not notarized), so on first launch right-click it → Open, or run:

xattr -dr com.apple.quarantine /Applications/DisplayToggle.app

Build from source (needs Xcode Command Line Tools):

git clone https://github.com/yhshu/DisplayToggle.git
cd DisplayToggle
make install

Command line

CLI=/Applications/DisplayToggle.app/Contents/MacOS/DisplayToggle

$CLI list                          # list displays with state and current mode
$CLI off Sceptre                   # disconnect (by index, display ID, or part of the name)
$CLI on 2                          # reconnect
$CLI toggle "LG"                   # toggle
$CLI reset LG                      # reset one display: reconnect if plugged in, else forget
$CLI reset                         # reset every display
$CLI modes Sceptre                 # list all resolutions / refresh rates
$CLI res Sceptre 2560x1440 hidpi 60
$CLI brightness LG 60               # brightness 0–100 (omit the value to read it)
$CLI volume 30                     # volume of the current output device
$CLI login on|off                  # launch at login

Tip: put $CLI toggle <name> in a Shortcuts "Run Shell Script" action to bind it to a hotkey.

How it works

Disconnection uses the private CoreGraphics function CGSConfigureDisplayEnabled, applied with kCGConfigureForSession. Resolution changes use the public CGConfigureDisplayWithDisplayMode. Because the disconnect API is private, a future macOS update could break it.

Uninstall

Turn off Launch at Login in the menu, quit, and delete /Applications/DisplayToggle.app (or run make uninstall). If you used Keep Awake, also run sudo rm /etc/sudoers.d/displaytoggle.

License

PolyForm Noncommercial 1.0.0 — free for personal, educational, research, and other noncommercial use. Commercial use is not permitted.

Copyright © 2026 Yiheng Shu