Almost nobody finds displayplacer by browsing. People find it after the third time macOS shuffled their monitors into the wrong order and reset a resolution they had set carefully. It is the right tool for that, it is free, and it fixes exactly half of the problem you probably have.
The short answer
brew install displayplacer, then displayplacer list: it prints the command that recreates your current screen arrangement, and running that command later puts it back. It is a command line tool that does nothing until you run it, so pair it with a login item or a hotkey. It restores displays, not windows, and those are two different jobs that break at the same moment.
What it is
The README is admirably direct: “macOS command line utility to configure multi-display resolutions and arrangements. Essentially XRandR for macOS.” If XRandR means nothing to you, read it as: one command that sets every screen's resolution, refresh rate, rotation, mirroring and position relative to the others, so a setup you spent ten minutes arranging in System Settings becomes a line of text you can rerun.
| What it is | Command line utility, no interface |
|---|---|
| Price | Free, MIT licensed |
| Install | brew install displayplacer, or a build from GitHub releases |
| What it sets | Resolution, refresh rate, colour depth, rotation, mirroring, and each display's position |
| How you save a setup | displayplacer list prints the command that recreates the current one |
| Runs automatically | No. It applies a configuration when invoked |
| Restores window positions | No. Displays only |
Saving and reapplying a setup
The workflow is two steps and it is the whole tool. Arrange your displays the way you want them in System Settings, then run displayplacer list. Among the details of every connected screen it prints the exact displayplacer command that reproduces what you are looking at. Keep that line. When macOS scrambles things, run it.
Because a saved setup is just a shell command, one per desk works well: one line for the office with two monitors, one for the single screen at home, one for the ultrawide. A shell alias per desk is usually all the structure this needs.
Making it run on its own
This is the part its documentation leaves to you, on purpose: displayplacer applies a configuration and exits. To get it to fire when a monitor appears, people reach for a login item, a Shortcuts or Automator action, a hotkey in a tool like BetterTouchTool, or a launch agent watching for a display change. None of that ships with displayplacer, so budget an evening for the automation rather than the tool.
Why macOS forgets in the first place
Worth knowing, because it explains why this keeps happening rather than being a one-off. macOS stores display settings against its identification of each screen, and that identification is less stable than it seems. A dock or hub can present the same monitor differently between connections, and two identical monitors are genuinely hard to tell apart. When the match fails, macOS falls back to a default layout instead of yours. The same fragility drives the window side of this, which is set out in why your Mac windows move when you unplug a monitor.
The half it does not fix
Here is the distinction that costs people the most time. There are two things macOS loses when a display comes and goes:
The screens.Which monitor is on the left, what resolution each one runs, where the menu bar lives. That is displayplacer's job, and it does it well.
The windows. Which app sat where on those screens, at what size. displayplacer does not touch this, and restoring the screens does not bring it back: your displays return to the right arrangement with every window still piled on one of them, because macOS moved them while the monitor was gone and never moved them home.
People often assume the second follows the first, install displayplacer, get the screens right, and conclude the tool did not work. It did. It solved the problem it describes.
What handles the windows
A window restorer, and Putback is one, which we make, so weigh this accordingly. It records where every window sits for each display setup you use, notices when the setup changes, and puts them all back in about 0.4 seconds. It learns as you work instead of asking you to save a snapshot, which is the same reason a saved displayplacer command is easy to live with: nothing to remember at the moment things break.
The two sit together cleanly. displayplacer puts the screens back, Putback puts the windows back on them, and neither is trying to do the other's job. If you would rather have one tool, Putback covers the windows only, so keep the displayplacer command for the screens. More on arranging the desk in the Mac multi-monitor setup guide, and on the alternatives in Putback compared with every Mac window tool.
Questions, answered.
What does displayplacer do?
Its README describes it as a "macOS command line utility to configure multi-display resolutions and arrangements. Essentially XRandR for macOS." It sets resolution, refresh rate, colour depth, rotation, mirroring and where each display sits relative to the others, from one command you can save and reuse.
How do I install displayplacer?
brew install displayplacer, or download a build from the releases page on its GitHub repository. It is MIT licensed and free.
How do I save my current display arrangement?
Run displayplacer list. Alongside the details of every connected screen it prints the exact displayplacer command that recreates the arrangement you are looking at. Copy that line somewhere you can find it; running it later puts your screens back.
Does displayplacer run automatically when I plug a monitor in?
No. It applies a configuration when you run it, and nothing more. Its own documentation points you at automation tools to trigger it, so people wire it to a login item, an Automator or Shortcuts action, a hotkey in something like BetterTouchTool, or a launch agent that fires on a display change.
Does displayplacer restore my window positions?
No, and it does not claim to. It restores displays: resolutions, arrangement, rotation, mirroring. Where your app windows sit on those displays is a separate problem, and one that macOS also gets wrong for the same reason. Restoring the screens does not put the windows back on them.
Why does my Mac forget my display arrangement at all?
macOS keys display settings to how it identifies each screen, and identification is less stable than it looks: docks and hubs can present the same monitor differently between connections, and two identical monitors are genuinely hard to tell apart. When the match fails, macOS falls back to a default arrangement instead of the one you set.
Is there a GUI alternative to displayplacer?
SwitchResX is the long-standing paid GUI tool in the same territory. We have not tested it, so nothing on this page should be read as a comparison of the two. If a command line is not something you want in this workflow, that is the name to look up.
How we checked this
Prices, licences, minimum macOS versions and feature claims on this page were read from each tool's own website, App Store listing or repository documentation on 5 August 2026. We build one of the tools mentioned here, which is a conflict of interest worth knowing about, so every claim about a competitor is either quoted from its own documentation or described as something that documentation does not cover. Where a tool does not state something, we say so instead of guessing. Prices and features change: check the linked source before you buy anything.
Screens back with displayplacer. Windows back with Putback.
Restoring your display arrangement does not move a single window. Putback remembers where each one was and puts it there.
Free for 7 days · then $19, once · macOS 14+