Overview: What custom screen resolution means on Mac
On Mac, custom screen resolution lets you target a display pixel count that macOS does not offer in the default list. This is useful when an external display or projector requires a specific mode, when a lower resolution provides sharper text on very high‑DPI screens, or when troubleshooting compatibility with legacy software. macOS generally protects you from settings that can damage the display, but not all custom modes are guaranteed to look sharp or remain stable across reboots, sleep, or display reconnects. This article explains safe methods, realistic expectations, and when to avoid custom resolutions.
When to use a custom resolution
Typical scenarios and alternatives
Use a custom resolution when a connected display needs an exact timing that macOS does not expose, such as a projector or a niche monitor with a required pixel clock. Common cases include matching a native panel mode to avoid scaling artifacts, working with older software that requires a specific size, or working around window‑scaling limitations on high‑DPI external screens. Before creating a custom mode, try macOS Display Scaling (System Settings > Displays) or third‑party apps that offer more preset options, because those are safer and persist across updates.
- Display requires a pixel clock or timing not listed in System Settings.
- UI elements appear too large or too small despite using macOS scaling options.
- Legacy apps demand a specific width × height that macOS does not expose.
- You need 1:1 pixel mapping with a TV or capture device that expects a known mode.
If none of these apply, prefer the default scaled or resolution options in System Settings, which are tested for quality and stability.
Built‑in method to add a custom resolution
macOS does not expose a direct UI for arbitrary custom resolutions, but you can add one using DisplayLink Manager or the command‑line tool displayplacer, a widely used open‑source utility. These approaches work by writing a mode line (a concise description of timing and resolution) to the display configuration. This is a low‑level operation; if the mode line is incorrect, the display may show a distorted image or fail to sync. Always back up your configuration and test changes with the display connected to power and seated securely before relying on the mode.
Create a mode line safely
Using displayplacer (recommended workflow)
The recommended workflow is to install displayplacer via Homebrew, list your current modes, duplicate an existing mode as a baseline, modify the resolution and refresh, then apply it. This minimizes risk because you start from a verified mode. Steps include installing Homebrew, installing displayplacer, dumping current modes, editing the target mode string, and applying the new mode. After testing, you can save the command in a startup script or shortcut for reuse. Note that custom modes may disappear after macOS updates or display firmware changes, so keep your setup script versioned.
Important limitations and risks
When custom resolutions may not work or can cause issues
Not all displays support arbitrary modes. Some cables, adapters, and graphics hardware require specific pixel clocks; if the mode exceeds the hardware limits, macOS may refuse to apply it or the display may report no signal. Apple silicon Macs and Intel Macs handle timings differently, and external GPUs (eGPUs) can further change which modes are valid. Additionally, some apps assume a single native resolution and can misbehave when the coordinate space differs from expected. Always test a new mode for a full work session, including wake from sleep, display sleep, and reconnect cycles.
| Attribute | Verified Detail | Source Type |
|---|---|---|
| Installation method | Homebrew (command-line) | Package manager |
| Primary tool | displayplaster | Open‑source CLI utility |
| Risk level | Low to moderate (invalid timings may cause no signal) | Community consensus and vendor guidance |
| Persistence | May be lost after macOS or firmware updates | Observed behavior |
| Hardware dependency | Cables, adapters, and display firmware can limit supported modes | Hardware notes |
Safer alternatives to consider first
Before adding a custom mode, evaluate safer alternatives that achieve similar goals with lower risk. macOS Display Scaling can effectively make everything larger or smaller without custom timings. Some third‑party tools provide additional preset resolutions that are tested for compatibility. If you need precise pixel mapping for capture or broadcast work, consult the display manufacturer’s EDID or provided preset modes; many devices expose required modes automatically when connected correctly. Use custom resolutions only when these alternatives do not meet your needs.
- Use a scaled resolution in System Settings for better UI size control.
- Check the display’s native mode and available presets in its On‑Screen Display (OSD).
- Update cables, adapters, and firmware; some issues are resolved by correct hardware setup.
- Consult the manufacturer’s documentation for recommended mode strings.
Step‑by‑step example (illustrative)
The following example shows the general pattern for adding a custom mode with displayplacer. Adjust values to match your target resolution, refresh rate, and timing. This is informational; verify each parameter against your display’s specifications before applying.
- Install Homebrew if not present: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- Install displayplacer: brew install displayplacer
- List current modes: displayplater list
- Choose a baseline mode and note its string.
- Edit the string to change width, height, and refresh as needed.
- Apply the new mode: displayplacer "id:
mode: " - Test for clarity, stable refresh, and behavior after sleep.
Troubleshooting and verification
Check stability and correctness
If the display shows artifacts, incorrect aspect ratio, or fails to wake, revert to a known good mode immediately using System Settings or the original displayplister command. Verify that the target mode matches the panel’s native timing; if possible, obtain a working mode string from the display’s OSD or user guide. Log each change so you can roll back quickly. Remember that security updates and macOS upgrades can reset or block unsigned custom modes; keep your setup scripts in a versioned location so you can reapply them safely.
Summary: Balanced approach to custom screen resolutions
You can set a custom screen resolution on Mac using command‑line tools like displayplacer, but do so only when necessary and after trying safer macOS scaling options. Always start from a verified mode line, test thoroughly across sleep and reconnect cycles, and keep your configuration documented so you can restore it after updates. For most users, built‑in scaled options or manufacturer‑provided modes are the best choice; reserve custom resolutions for cases where no other configuration matches the display’s requirements or your workflow needs.