Fix swapped monitors on a Mac with displayplacer
15 November 2026 · Martín Acuña Lledó · Applies to macOS 13 Ventura through macOS 27
Your monitors swap places after sleep, the main display moves, or a portrait screen turns landscape again, and you fix it in System Settings several times a day. displayplacer is a free command-line tool that can put the arrangement back with one command. This page shows how to get that command, how to run it automatically when the Mac wakes, and where it stops, because it does not touch your windows and it can lose track of identical monitors.
Try this first
Before adding a tool, two changes remove the swap for many setups:
- Give identical monitors their own ports. Swaps happen most with two monitors of the same model that report the same serial. On Apple silicon, plugging each into its own port on the Mac gives macOS something to tell them apart. Behind one dock they usually share a port. See two identical monitors swap places after sleep.
- Keep the monitors connected while locked. In System Settings → Lock Screen, set "Turn display off when inactive" to Never and use a password-protected screen saver, and turn off deep sleep in each monitor's menu. No disconnect, no swap. This covers locks, not real sleep or a dock.
What displayplacer does
displayplacer is an open source project on GitHub by Jake Hilborn, under the MIT licence. Its README describes it as a command-line utility to configure multi-display resolutions and arrangements. For each display it can set the resolution, refresh rate, colour depth, scaling, position and rotation, turn mirroring on, or disable a screen. The display placed at origin (0,0) becomes the main display. The latest release on GitHub is 1.4.0, from June 2023.
Get your command
- Install it. With Homebrew:
brew install displayplacer. The README also links prebuilt releases. - Set everything by hand once. The README's order is rotation first, then resolution, then arrangement, in System Settings → Displays. Put the menu bar on the display you want as main.
- Print the command. Run:
The output includes a fulldisplayplacer listdisplayplacer "id:… res:… origin:(…) degree:…"command for your current layout. Copy it into a text file. - Test it. Swap two monitors in System Settings, run the command, and check that everything goes back.
The README describes three kinds of screen ID in that output. Persistent IDs usually stay the same and are the default. Contextual IDs change when cables move ports, and it suggests trying them if persistent ones keep switching. Serial IDs are tied to the hardware and are the ones to use if every monitor's serial is unique. You can mix types in one command.
Run it on wake
displayplacer does nothing until something runs it. Its README suggests hotkeys through Automator or BetterTouchTool. To run it on wake, one option is sleepwatcher, another free command-line tool, which its site describes as a daemon that monitors sleep, wakeup and idleness of a Mac.
- Install and start it:
brew install sleepwatcher, thenbrew services start sleepwatcher. Homebrew's notes for it say that, run this way, it uses the scripts~/.sleepand~/.wakeup. - Create
~/.wakeupwith a short wait and your command, using the full path thatwhich displayplacerprints:#!/bin/sh sleep 10 /opt/homebrew/bin/displayplacer "id:… res:… origin:(0,0) degree:0" "id:… …" - Make it executable:
chmod +x ~/.wakeup.
The wait matters. Monitors wake a few seconds apart, and running the command before every one is back can fail or fix only half the setup. Ten seconds is a starting point, not a measured value: raise it if your dock is slow.
One catch on Apple silicon: sleepwatcher's site says its display sleep and wake options do not work on Apple silicon Macs. The wake script runs when the Mac itself wakes, so a lock where only the displays slept may not trigger it. A hotkey covers that case.
Where it stops
- It does not move windows. If macOS piled your windows onto one screen while the monitors were away, they stay there after displayplacer fixes the arrangement. On identical monitors that swapped, the windows can end up on the wrong monitor even when the arrangement is right again.
- IDs can change under it. Its own README says macOS sometimes changes the persistent IDs when external screens wake in a non-deterministic order, and points to several issues where people wrote shell scripts around it. Issue 89 (2022) reports the persistent IDs of two identical Samsung monitors changing on every sleep. Issue 158 (June 2026) reports all three ID types changing on one of two identical AOC monitors behind a j5create dock on an M5 Pro MacBook Pro. When the IDs change, the saved command points at the wrong screen or fails.
- One command per setup. A command describes one set of monitors. If you dock at home and at the office, you keep one per desk and run the right one.
- It is not very active. The last release is from 2023. It still installs and runs for many people, but a macOS change could break it with nobody fixing it quickly.
More options, including Hammerspoon and Keyboard Maestro, are in every fix for windows moving after sleep.
How Many Displays handles it
Many Displays covers the part displayplacer leaves out, and does it without a script. It keeps one layout per combination of displays, saved as you work. When the Mac wakes, unlocks or the monitors reconnect and the displays have been stable for a few seconds, it puts back the arrangement, the main display, resolution, refresh rate, rotation and HDR, one step at a time, and then returns every window to its physical display, position and size. You press nothing and keep no command per desk.
It tells identical monitors apart by system UUID, then by the physical port on Apple silicon, then by manufacture date, and only then by position, so it does not depend on the IDs that trip up a saved command.
Where it does not help:
- Two identical monitors from the same batch behind one dock. Serial, port and date can all match, and only their position is left, which is exactly what macOS may have swapped.
- Setups you change on purpose. displayplacer lets you switch to a different arrangement with a hotkey. Many Displays puts back the last one you had for that set of monitors, and has no named layouts to switch between.
- Desktops (Spaces). Since macOS 14.5 no app can move another app's window to a different Space without disabling System Integrity Protection.
It costs $19 once after a 14-day trial with no account; displayplacer is free. If you use both, remove the wake script so two tools are not changing the arrangement at the same time.
Download the free trial How it works
Questions
What does displayplacer do?
It is a free, open source command-line tool that sets the resolution, refresh rate, rotation, position and mirroring of each display. You arrange your monitors once in System Settings, run displayplacer list, and it prints one command that puts that layout back.
Can displayplacer run automatically when the Mac wakes?
Not by itself. A separate free tool, sleepwatcher, can run a script on wake. Installed with Homebrew and started with brew services, it runs ~/.wakeup, where you put the displayplacer command, ideally after a short wait so every monitor is back.
Does displayplacer move my windows back?
No. It changes how the displays are arranged and configured, not where windows are. If macOS moved your windows while the monitors were away, they stay where macOS put them.
Why does my displayplacer command stop working with identical monitors?
It finds each monitor by an ID, and its own README says macOS sometimes changes the persistent IDs when external screens wake up in a different order. Several open issues report this with identical monitors, including one from 2026 where all three ID types changed on a dock.