Window Configuration

Configure window appearance, size, padding, and decorations in WezTerm

Window Configuration

WezTerm provides extensive options for customizing the appearance and behavior of terminal windows.

Window Size

Initial Dimensions

initial_cols · number · default: "80"

The width of a new window, expressed in character cells.

initial_rows · number · default: "24"

The height of a new window, expressed in character cells.

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.initial_cols = 120
config.initial_rows = 30

return config

Font Size Change Behavior

adjust_window_size_when_changing_font_size · boolean · default: "true"

When true, the window size adjusts to maintain the same number of rows and columns when font size changes.

config.adjust_window_size_when_changing_font_size = false

Window Padding

window_padding · table

Controls the amount of padding between the window border and terminal cells. Values can be specified in pixels, points, cells, or percentage.

config.window_padding = {
  left = 20,
  right = 20,
  top = 10,
  bottom = 10,
}

Padding Units

You can specify padding using different units:

Pixels

config.window_padding = {
  left = '20px',
  right = '20px',
  top = '10px',
  bottom = '10px',
}

If enable_scroll_bar is true, the right padding value controls the scrollbar width.

Window Decorations

window_decorations · string · default: "'TITLE | RESIZE'"

Controls which window decorations are enabled. Can be combined with |.

Valid values:

• NONE: No decorations
• TITLE: Show title bar
• RESIZE: Allow window resizing
• MACOS_FORCE_ENABLE_SHADOW: Enable shadow on macOS
• MACOS_FORCE_DISABLE_SHADOW: Disable shadow on macOS
• INTEGRATED_BUTTONS: Use integrated title bar buttons

No Decorations

config.window_decorations = 'NONE'

Integrated Title Buttons

Configure the appearance of integrated title bar buttons:

integrated_title_buttons · array · default: "['Hide', 'Maximize', 'Close']"

Array of button names to show in the integrated title bar.

config.integrated_title_buttons = { 'Hide', 'Maximize', 'Close' }

integrated_title_button_style · string · default: "'Windows'"

Style of integrated buttons. Valid values: Windows, Gnome, MacOsNative

config.integrated_title_button_style = 'Windows'

integrated_title_button_alignment · string · default: "'Right'"

Alignment of integrated buttons. Valid values: Left, Right

config.integrated_title_button_alignment = 'Left'

integrated_title_button_color · string · default: "'Auto'"

Color for integrated title buttons. Can be Auto or a hex color value.

config.integrated_title_button_color = '#808080'

Window Frame

Configure the window frame appearance when using client-side decorations:

config.window_frame = {
  -- Title bar colors
  active_titlebar_bg = '#333333',
  inactive_titlebar_bg = '#1e1e1e',
  
  -- Title text colors
  active_titlebar_fg = '#ffffff',
  inactive_titlebar_fg = '#cccccc',
  
  -- Title bar border
  active_titlebar_border_bottom = '#2b2042',
  inactive_titlebar_border_bottom = '#1b1032',
  
  -- Button colors
  button_fg = '#cccccc',
  button_bg = '#333333',
  button_hover_fg = '#ffffff',
  button_hover_bg = '#3b3052',
  
  -- Font settings
  font = wezterm.font({ family = 'Roboto', weight = 'Bold' }),
  font_size = 12.0,
  
  -- Border widths (in pixels)
  border_left_width = '0.5cell',
  border_right_width = '0.5cell',
  border_bottom_height = '0.25cell',
  border_top_height = '0.25cell',
  
  -- Border colors
  border_left_color = '#444444',
  border_right_color = '#444444',
  border_bottom_color = '#444444',
  border_top_color = '#444444',
}

window_frame · table

Configuration object for window frame appearance.

Window Background

Solid Color Background

The background color is set via the color scheme or colors configuration:

config.colors = {
  background = '#1e1e1e',
}

Background Opacity

window_background_opacity · number · default: "1.0"

The opacity of the window background, from 0.0 (fully transparent) to 1.0 (fully opaque).

config.window_background_opacity = 0.9

Background opacity requires compositor support on Linux and may not work on all systems.

Background Images

background · array · default: "[]"

An array of background layer specifications. Layers can include images, gradients, and solid colors.

config.background = {
  {
    source = {
      File = '/path/to/wallpaper.jpg',
    },
    hsb = {
      brightness = 0.3,
    },
    width = '100%',
    height = '100%',
    opacity = 0.8,
  },
}

Background Gradients

config.background = {
  {
    source = {
      Gradient = {
        colors = { '#1e1e1e', '#3e3e3e' },
        orientation = 'Vertical',
      },
    },
    width = '100%',
    height = '100%',
  },
}

window_background_gradient · table · default: "nil"

Shorthand for configuring a gradient background.

config.window_background_gradient = {
  colors = { '#1e1e1e', '#3e3e3e' },
  orientation = {
    Linear = {
      angle = -45.0,
    },
  },
}

Window Content Alignment

window_content_alignment · string · default: "'Left'"

Horizontal alignment of terminal content within the window. Valid values: Left, Center, Right

config.window_content_alignment = 'Center'

Window Blur Effects

macOS Window Blur

macos_window_background_blur · number · default: "0"

macOS-specific blur radius for window background. Values typically range from 0 to 100.

config.macos_window_background_blur = 30

Windows System Backdrop

win32_system_backdrop · string · default: "'Auto'"

Windows 11-specific backdrop material. Valid values: Auto, Disable, Acrylic, Mica, Tabbed

config.win32_system_backdrop = 'Acrylic'

win32_acrylic_accent_color · string · default: "nil"

Accent color for Windows Acrylic backdrop effect. Specify as hex color.

config.win32_acrylic_accent_color = '#1e1e1e'

KDE Window Blur

kde_window_background_blur · boolean · default: "false"

Enable KDE Plasma window background blur effect.

config.kde_window_background_blur = true

Window Close Confirmation

window_close_confirmation · string · default: "'AlwaysPrompt'"

Controls when to show close confirmation. Valid values:

• AlwaysPrompt: Always ask for confirmation
• NeverPrompt: Never ask for confirmation

config.window_close_confirmation = 'NeverPrompt'

Skip Close Confirmation for Processes

skip_close_confirmation_for_processes_named · array · default: "[]"

Array of process names that won’t trigger close confirmation.

config.skip_close_confirmation_for_processes_named = {
  'bash',
  'sh',
  'zsh',
  'fish',
  'tmux',
}

Window Behavior

Quit When All Windows Closed

quit_when_all_windows_are_closed · boolean · default: "true"

When true, WezTerm quits when the last window is closed.

config.quit_when_all_windows_are_closed = false

Native macOS Fullscreen

native_macos_fullscreen_mode · boolean · default: "false"

When true, uses native macOS fullscreen mode with animations and separate Space.

config.native_macos_fullscreen_mode = true

macOS Fullscreen Notch Behavior

macos_fullscreen_extend_behind_notch · boolean · default: "false"

On macOS with notch, extend fullscreen content behind the notch.

config.macos_fullscreen_extend_behind_notch = true

Window Resize Behavior

Use Resize Increments

use_resize_increments · boolean · default: "false"

When true, window resizing snaps to character cell boundaries.

config.use_resize_increments = true

Tiling Desktop Environments

tiling_desktop_environments · array · default: "['X11 LG3D', 'X11 bspwm', ...]"

List of desktop environments detected as tiling window managers.

config.tiling_desktop_environments = {
  'X11 bspwm',
  'X11 i3',
  'X11 dwm',
}

Complete Window Configuration Example

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Window size
config.initial_cols = 120
config.initial_rows = 30

-- Window padding
config.window_padding = {
  left = '2cell',
  right = '2cell',
  top = '1cell',
  bottom = '1cell',
}

-- Window decorations
config.window_decorations = 'INTEGRATED_BUTTONS | RESIZE'
config.integrated_title_buttons = { 'Hide', 'Maximize', 'Close' }
config.integrated_title_button_style = 'Windows'

-- Window frame
config.window_frame = {
  active_titlebar_bg = '#2b2042',
  inactive_titlebar_bg = '#1b1032',
  font = wezterm.font({ family = 'JetBrains Mono', weight = 'Bold' }),
  font_size = 11.0,
}

-- Background
config.window_background_opacity = 0.95
config.macos_window_background_blur = 20

-- Behavior
config.adjust_window_size_when_changing_font_size = false
config.window_close_confirmation = 'AlwaysPrompt'

return config

See Also

• Color Schemes - Configure colors
• Fonts - Font configuration
• Tab Bar Configuration - Tab bar appearance