displayplacer Documentation

You can install the displayplacer utility on macOS using Homebrew:

brew install displayplacer

macOS may change screen IDs due to race conditions when external monitors wake up. displayplacer supports three types of IDs:

• Persistent screenIds: Usually stay the same; recommended for most automation and scripting.
• Contextual screenIds: Change when switching GPUs or changing cable ports.
• Serial screenIds: Tied directly to the display hardware (use these if they are unique for all your monitors).

To set up mirroring, provide a combined ID string where the first ID is the 'Optimize for' screen (the primary screen in System Preferences). Subsequent IDs in the string represent the screens to be mirrored.

Note: You can only choose resolutions for the 'Optimize for' screen. If a specific mirroring resolution is unavailable, try reordering the IDs so a different screen is first.

displayplacer "id:<mainScreenId>+<1stMirrorScreenId>+<2ndMirrorScreenId> res:<width>x<height> scaling:<on/off> origin:(<x>,<y>) degree:<0/90/180/270>"

Apply specific settings to a screen using key-value pairs. The hz (refresh rate) and color_depth parameters are optional; if omitted, the highest available values will be applied.

Available parameters:

• id:<screenId>: The unique identifier for the screen.
• res:<width>x<height>: The desired resolution.
• hz:<num>: The refresh rate in Hz.
• color_depth:<num>: The color depth.
• scaling:<on/off>: Enable or disable scaling.
• origin:(<x>,<y>): The screen position coordinates. Setting a screen to origin:(0,0) sets it as the primary screen.
• degree:<0/90/180/270>: The screen rotation angle.
• quiet:true: Silences errors for that specific screen.

displayplacer "id:<screenId> res:<width>x<height> hz:<num> color_depth:<num> scaling:<on/off> origin:(<x>,<y>) degree:<0/90/180/270>"

Instead of specifying resolution and refresh rate manually, you can use a specific mode number provided by the displayplacer list command.

Note: Some listed modes may not be functional; if an invalid mode is selected, displayplacer will default to the next available working resolution.

displayplacer "id:<screenId> mode:<modeNum> origin:(<x>,<y>) degree:<0/90/180/270>"

Use the list command to view your current display configuration, including available screen IDs and possible resolutions for the current rotation.

Note: If you are using scripts written for older versions of displayplacer, you can use the --v1.3.0 flag to maintain backward compatibility with the previous output format.

You can turn a screen off or on using the enabled parameter.

Note: If you disable a screen, you may need to physically unplug and replug it to bring it back, though some setups allow re-enabling via command.