Background Image

Wintty can render an image as the terminal's background, behind the cells. This pairs well with background-opacity for transparent or translucent terminals, and with background-blur on Linux compositors that support it.

Point background-image at a file path. PNG and JPEG are supported; other image formats are not yet implemented.

background-image = C:\Users\you\Pictures\wallpaper.png

The path is parsed the same way as other Wintty paths: relative paths are resolved against the configuration file's directory, so backgrounds/wallpaper.png means a file next to your config. Tilde expansion is compiled out on Windows, so ~/pictures/wallpaper.png is not expanded to your home directory; it is read as a relative path with a literal directory named ~ under the config directory. Use an absolute path or a config-relative one instead.

Note

Background images are currently per-terminal, not per-window. If you use splits, every split renders the image independently and the image texture is duplicated in VRAM for each surface. For small images this is fine. For very large images and many splits, it can use a noticeable amount of GPU memory.

background-image-opacity sets the image's opacity relative to background-opacity.

background-opacity = 0.8
background-image-opacity = 1.0

• A value of 1.0 (default) places the image on top of the background color, then applies background-opacity to the combined result.
• A value below 1.0 mixes the image into the background color before applying background-opacity. This is useful when the image is too visually loud and you want it to fade into the background color.
• A value above 1.0 overdrives the image so it stays more opaque than the background color. For example, with background-opacity = 0.5 and background-image-opacity = 1.5, the final image alpha is 0.5 * 1.5 = 0.75.

background-image-position controls where the image sits inside the terminal area. Valid values:

• top-left, top-center, top-right
• center-left, center-center, center-right
• bottom-left, bottom-center, bottom-right
• center (default), which is an alias for center-center

background-image-fit controls how the image is scaled:

Value	Behavior
contain (default)	Scale to fit while preserving aspect ratio; the whole image is visible
cover	Scale to fill while preserving aspect ratio; edges may be clipped
stretch	Scale to fill, ignoring aspect ratio
none	Don't scale; render at native pixel size

contain keeps the entire image visible at the cost of blank space around it. cover fills the surface but can clip part of the image. stretch is rarely what you want unless the image was authored to be stretched.

When the image doesn't fill the surface (typically with contain or none), the blank area is filled with the background color by default. Set background-image-repeat to true to tile the image instead:

background-image-fit = none
background-image-repeat = true

This is the right combination for small repeating textures (a pattern like fabric, paper, or a subtle noise).

Background images get most visually interesting when combined with opacity and blur:

background-image = C:\Users\you\Pictures\mountain.jpg
background-image-fit = cover
background-image-opacity = 0.6
background-opacity = 0.85

On Linux, background-blur requires a compositor that supports it (such as Hyprland or some KWin configurations). On Windows the key is parsed but never read, so setting it has no effect.

Note

On Windows, background-opacity applies, and the Mica/Acrylic material applies to the window background. Set the opacity low enough to let the desktop wallpaper show through, or layer a background image on top of the cells. The Wintty-only key background-blur-follows-opacity is the Windows equivalent of a blur knob: when it is on, the acrylic blur radius is reduced as background-opacity rises, so a more opaque window gets a less blurred backdrop.

Option	Purpose
background-image	Path to a PNG or JPEG file
background-image-opacity	Image opacity relative to background-opacity
background-image-position	Where the image sits in the surface
background-image-fit	How the image is scaled (contain, cover, stretch, none)
background-image-repeat	Tile the image when it doesn't fill the surface
background-opacity	Overall window background opacity
background-blur	Blur the wallpaper behind a transparent terminal (no effect on Windows)
background-blur-follows-opacity	Wintty-only: reduce the acrylic blur radius as background-opacity rises