sway-output(5)

📦
version 1.12_rc3 · 13 versions
, in alpine 3.24

🌸 sway-output(5) — like, the entire vibe of output config, bestie 🌸

Okay so real talk: this is sway-output, from the File Formats Manual — literally the page that tells you how to boss your monitors around in sway. Sit down, grab a strawberry 🍓, we're gonna go through every single thing.

✨ NAME ✨

sway-output — output configuration commands for sway. That's it, that's the whole name, and honestly? Iconic. 👑

🦋 DESCRIPTION 🦋

You can stack multiple output commands into one line, like the multitasking queen you are:

output HDMI-A-1 mode 1920x1080 pos 1920 0 bg ~/wallpaper.png stretch

Wanna know what outputs you even have? Run swaymsg -t get_outputs, babe. 💅

You can also match any output at all by using the output name "*". And there's more matching magic:

  • - can be used to match the focused output by name
  • -- can be used to match the focused output by its identifier

Okay but here's the annoying part (not me, the hardware 🙈): some outputs may have different names when disconnecting and reconnecting. So to identify those, the name can be substituted for a string consisting of the make, model and serial — all of which you can get from swaymsg -t get_outputs. Each value must be separated by one space. Like so:

output "Some Company ABC123 0x00000000" pos 1920 0

See? One space between each, no cap. ✨

💖 COMMANDS 💖

output <name> mode|resolution|res [--custom] <width>x<height>[@<rate>Hz]

Configures the specified output to use the given mode. Modes are a combination of width and height (in pixels) plus a refresh rate that your display can be configured to use. Wanna see the list of available modes for each output? swaymsg -t get_outputs, obviously. 🫶

To set a custom mode that isn't in the list of available modes, use --custom. You should probably only use this if you know what you're doing. (Like, genuinely know. Not "I saw it in a dotfiles repo" know.)

Examples:

output HDMI-A-1 mode 1920x1080
output HDMI-A-1 mode 1920x1080@60Hz

output <name> modeline <clock> <hdisplay> <hsync_start> <hsync_end> <htotal> <vdisplay> <vsync_start> <vsync_end> <vtotal> <hsync> <vsync>

Configures the specified output to use the given modeline. You can generate one with the cvt(1) and gtf(1) commands — go check out xorg.conf(5) too. Heads up though: only supported on DRM backend. 💀

Example:

output HDMI-A-1 modeline 173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync

output <name> position|pos <X> <Y>

Places the specified output at the specific position in the global coordinate space. The cursor may only be moved between immediately adjacent outputs. If scaling is active, you have to consider it when positioning. For example, if the scaling factor for the left output is 2, the relative position for the right output has to be divided by 2. Also the reference point is the top left corner, so if you want the bottoms aligned, that has to be considered as well. Math is unfortunately involved, sorry bestie 😭

Example:

output HDMI1 scale 2

output HDMI1 pos 0 1020 res 3200x1800

output eDP1 pos 1600 0 res 1920x1080

Note that the left x-pos of eDP1 is 1600 = 3200/2 and the bottom y-pos is 1020 + (1800 / 2) = 1920 = 0 + 1920

(Yeah I know, but it checks out. 🧮)

output <name> scale <factor>

Scales the specified output by the specified scale factor. An integer is recommended, but fractional values are also supported. Honestly you may be better served by setting an integer scale factor and adjusting your font sizes in your apps to taste. Also: HiDPI isn't supported with Xwayland clients (your windows will blur, unfortunately 😔). And a fractional scale may be slightly adjusted to match requirements of the protocol. It's giving "we tried our best" and honestly that's fine.

output <name> scale_filter linear|nearest|smart

Indicates how to scale application buffers that are rendered at a scale lower than the output's configured scale — think lo-dpi applications on hi-dpi screens. 🎀

  • linear is smoother and blurrier
  • nearest (also known as nearest neighbor) is sharper and blockier
  • smart will apply nearest scaling when the output has an integer scale factor, otherwise linear

The default is "smart". Slay. ✨

output <name> subpixel rgb|bgr|vrgb|vbgr|none

Manually sets the subpixel hinting for the specified output. This value is usually auto-detected, but some displays may misreport their subpixel geometry (rude of them). Using the correct subpixel hinting allows for sharper text. Incorrect values will result in blurrier text. 👀

When changing this via swaymsg, some applications may need to be restarted to use the new value. Just a lil heads up.

output <name> background|bg <file> <mode> [<fallback_color>]

Sets the wallpaper for the given output to the specified file, using the given scaling mode — one of "stretch", "fill", "fit", "center", "tile". If the specified file cannot be accessed, or if the image does not fill the entire output, a fallback color may be provided to cover the rest of the output. fallback_color should be specified as #RRGGBB. Alpha is not supported. No fancy translucent wallpaper energy, sorry.

output <name> background|bg <color> solid_color

Sets the background of the given output to the specified color. color should be specified as #RRGGBB. Again — alpha is not supported. 💅

output <name> transform <transform> [clockwise|anticlockwise]

Sets the background transform to the given value. Can be one of:

  • "90", "180", "270" for rotation
  • "flipped", "flipped-90", "flipped-180", "flipped-270" to apply a rotation and flip
  • "normal" to apply no transform at all

The rotation is performed clockwise. 🔄

If a single output is chosen and a rotation direction is specified (clockwise or anticlockwise) then the transform is added or subtracted from the current transform — but heads up, this cannot be used directly in the configuration file. 🙈

output <name> disable|enable

Enables or disables the specified output (all outputs are enabled by default, bestie).

As opposed to the power command, the output will lose its current workspace and windows. So like, be careful. 😭

output <name> toggle

Toggle the specified output. Short, sweet, to the point. 🎀

output <name> power on|off|toggle

Turns on or off the specified output.

As opposed to the enable and disable commands, the output keeps its current workspaces and windows. See, this one's the gentle option. 🫶

output <name> dpms on|off|toggle

Deprecated. It's just an alias for power. She had a good run. 💀

output <name> max_render_time off|<msec>

Controls when sway composites the output, as a positive number of milliseconds before the next display refresh. A smaller number leads to fresher composited frames and lower perceived input latency, but if set too low, sway may not finish compositing in time for display refresh, leading to delayed frames. It's giving balancing act. ⚖️

When set to off, sway composites immediately after display refresh, maximizing time available for compositing.

To adjust when applications are instructed to render, see max_render_time in sway(5).

To set this up for optimal latency:

  1. Launch some full-screen application that renders continuously, like glxgears.
  2. Start with max_render_time 1. Increment by 1 if you see frame drops.

This setting only has an effect on Wayland and DRM backends, as support for presentation timestamps and predicted output refresh rate is required. No cap. 🔥

output <name> adaptive_sync on|off|toggle

Enables or disables adaptive synchronization — often referred to as Variable Refresh Rate, or by the vendor-specific names FreeSync/G-Sync. ✨

Adaptive sync allows clients to submit frames a little too late without having to wait a whole refresh period to display it on screen. Enabling adaptive sync can improve latency, but can cause flickering on some hardware. So like, vibe check your monitor first. 👀

output <name> render_bit_depth 6|8|10

Controls the maximum color channel bit depth at which frames are rendered; the default is currently 8 bits per channel.

Setting higher values will not have an effect if hardware and software lack support for such bit depths. And successfully increasing the render bit depth will not necessarily increase the bit depth of the frames sent to a display. An increased render bit depth may provide smoother rendering of gradients, and screenshots which can more precisely store the colors of programs which display high bit depth colors. 🌈

Warnings: this can break screenshot/screencast programs which have not been updated to work with different bit depths. This command is experimental, and may be removed or changed in the future. Don't say nobody told you. 💀

output <name> color_profile [--device-primaries] gamma22|srgb

Sets the color profile for an output. The default is gamma22.

--device-primaries will use the output's self-reported color primaries when available (e.g. from display EDID). Trusting your monitor to know itself, love that for it. 🎀

Not all renderers support this feature; currently it only works with the the Vulkan renderer. (Yes, "the the" — I'm just the messenger.) It is not compatible with HDR support features.

output <name> color_profile icc <file>

Sets the color profile for an output.

<file> should be a path to a display ICC profile.

Not all renderers support this feature; currently it only works with the the Vulkan renderer. Even where supported, the application of the color profile may be inaccurate. 🙈

This command is experimental, and may be removed or changed in the future. It may have no effect or produce unexpected output when used together with future HDR support features. Literally "we'll see", bestie. 😭

output <name> allow_tearing yes|no

Allows or disallows screen tearing as a result of immediate page flips, and an immediate presentation mode from a client. The default is that no screen tearing is allowed.

With immediate page flips, frames from the client are presented as soon as possible instead of synchronizing with the monitor's vblank interval (VSync). Speed over smoothness, basically. 🔥

It is recommended to set max_render_time to off. In that case a page flip happens as soon as a client updates. Otherwise, tearing will only happen if rendering takes longer than the configured milliseconds before the next display refresh.

To adjust whether tearing is allowed for specific applications, see allow_tearing in sway(5). Note that tearing will only be enabled when it's allowed for both the output and the application. Teamwork, periodt. 💅

This setting only has effect when a window is fullscreen on the output.

output <name> hdr on|off|toggle

Enables or disables HDR (High Dynamic Range). HDR enables a larger color gamut and brightness range. HDR uses the BT2020 primaries and the PQ transfer function. Gorgeous. 🌈✨

When HDR is enabled, render_bit_depth is implicitly set to 10 unless explicitly configured. Using a lower render bit depth may result in color banding artifacts. (Banding is not the vibe. 😭)

HDR needs to be supported by the output and renderer to be enabled. Fingers crossed, bestie. 🫶

👑 SEE ALSO 👑

sway(5) sway-input(5)

Okay so that's literally everything, and I mean everything — every flag, every default, every warning. Go forth and configure your outputs, you absolute main character. 🦋💜

Later, bestie — this was sway-output(5) from the File Formats Manual, dated 2026-04-26. Mwah. 💅🎀

📦 where this page comes from