> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField path="initial_cols" type="number" default="80">
  The width of a new window, expressed in character cells.
</ParamField>

<ParamField path="initial_rows" type="number" default="24">
  The height of a new window, expressed in character cells.
</ParamField>

```lua theme={null}
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.initial_cols = 120
config.initial_rows = 30

return config
```

### Font Size Change Behavior

<ParamField path="adjust_window_size_when_changing_font_size" type="boolean" default="true">
  When true, the window size adjusts to maintain the same number of rows and columns when font size changes.
</ParamField>

```lua theme={null}
config.adjust_window_size_when_changing_font_size = false
```

## Window Padding

<ParamField path="window_padding" type="table" default="{left='1cell', right='1cell', top='0.5cell', bottom='0.5cell'}">
  Controls the amount of padding between the window border and terminal cells. Values can be specified in pixels, points, cells, or percentage.
</ParamField>

```lua theme={null}
config.window_padding = {
  left = 20,
  right = 20,
  top = 10,
  bottom = 10,
}
```

### Padding Units

You can specify padding using different units:

<CodeGroup>
  ```lua Pixels theme={null}
  config.window_padding = {
    left = '20px',
    right = '20px',
    top = '10px',
    bottom = '10px',
  }
  ```

  ```lua Cells theme={null}
  config.window_padding = {
    left = '1cell',
    right = '1cell',
    top = '0.5cell',
    bottom = '0.5cell',
  }
  ```

  ```lua Points theme={null}
  config.window_padding = {
    left = '10pt',
    right = '10pt',
    top = '5pt',
    bottom = '5pt',
  }
  ```

  ```lua Percentage theme={null}
  config.window_padding = {
    left = '2%',
    right = '2%',
    top = '1%',
    bottom = '1%',
  }
  ```
</CodeGroup>

<Note>
  If `enable_scroll_bar` is true, the `right` padding value controls the scrollbar width.
</Note>

## Window Decorations

<ParamField path="window_decorations" type="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
</ParamField>

<CodeGroup>
  ```lua No Decorations theme={null}
  config.window_decorations = 'NONE'
  ```

  ```lua Title Bar Only theme={null}
  config.window_decorations = 'TITLE'
  ```

  ```lua Resize Only theme={null}
  config.window_decorations = 'RESIZE'
  ```

  ```lua Title and Resize (Default) theme={null}
  config.window_decorations = 'TITLE | RESIZE'
  ```

  ```lua Integrated Buttons (macOS) theme={null}
  config.window_decorations = 'INTEGRATED_BUTTONS | RESIZE'
  ```
</CodeGroup>

### Integrated Title Buttons

Configure the appearance of integrated title bar buttons:

<ParamField path="integrated_title_buttons" type="array" default="['Hide', 'Maximize', 'Close']">
  Array of button names to show in the integrated title bar.
</ParamField>

```lua theme={null}
config.integrated_title_buttons = { 'Hide', 'Maximize', 'Close' }
```

<ParamField path="integrated_title_button_style" type="string" default="'Windows'">
  Style of integrated buttons. Valid values: `Windows`, `Gnome`, `MacOsNative`
</ParamField>

```lua theme={null}
config.integrated_title_button_style = 'Windows'
```

<ParamField path="integrated_title_button_alignment" type="string" default="'Right'">
  Alignment of integrated buttons. Valid values: `Left`, `Right`
</ParamField>

```lua theme={null}
config.integrated_title_button_alignment = 'Left'
```

<ParamField path="integrated_title_button_color" type="string" default="'Auto'">
  Color for integrated title buttons. Can be `Auto` or a hex color value.
</ParamField>

```lua theme={null}
config.integrated_title_button_color = '#808080'
```

## Window Frame

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

```lua theme={null}
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',
}
```

<ParamField path="window_frame" type="table">
  Configuration object for window frame appearance.
</ParamField>

## Window Background

### Solid Color Background

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

```lua theme={null}
config.colors = {
  background = '#1e1e1e',
}
```

### Background Opacity

<ParamField path="window_background_opacity" type="number" default="1.0">
  The opacity of the window background, from 0.0 (fully transparent) to 1.0 (fully opaque).
</ParamField>

```lua theme={null}
config.window_background_opacity = 0.9
```

<Warning>
  Background opacity requires compositor support on Linux and may not work on all systems.
</Warning>

### Background Images

<ParamField path="background" type="array" default="[]">
  An array of background layer specifications. Layers can include images, gradients, and solid colors.
</ParamField>

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

### Background Gradients

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

<ParamField path="window_background_gradient" type="table" default="nil">
  Shorthand for configuring a gradient background.
</ParamField>

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

## Window Content Alignment

<ParamField path="window_content_alignment" type="string" default="'Left'">
  Horizontal alignment of terminal content within the window. Valid values: `Left`, `Center`, `Right`
</ParamField>

```lua theme={null}
config.window_content_alignment = 'Center'
```

## Window Blur Effects

### macOS Window Blur

<ParamField path="macos_window_background_blur" type="number" default="0">
  macOS-specific blur radius for window background. Values typically range from 0 to 100.
</ParamField>

```lua theme={null}
config.macos_window_background_blur = 30
```

### Windows System Backdrop

<ParamField path="win32_system_backdrop" type="string" default="'Auto'">
  Windows 11-specific backdrop material. Valid values: `Auto`, `Disable`, `Acrylic`, `Mica`, `Tabbed`
</ParamField>

```lua theme={null}
config.win32_system_backdrop = 'Acrylic'
```

<ParamField path="win32_acrylic_accent_color" type="string" default="nil">
  Accent color for Windows Acrylic backdrop effect. Specify as hex color.
</ParamField>

```lua theme={null}
config.win32_acrylic_accent_color = '#1e1e1e'
```

### KDE Window Blur

<ParamField path="kde_window_background_blur" type="boolean" default="false">
  Enable KDE Plasma window background blur effect.
</ParamField>

```lua theme={null}
config.kde_window_background_blur = true
```

## Window Close Confirmation

<ParamField path="window_close_confirmation" type="string" default="'AlwaysPrompt'">
  Controls when to show close confirmation. Valid values:

  * `AlwaysPrompt`: Always ask for confirmation
  * `NeverPrompt`: Never ask for confirmation
</ParamField>

```lua theme={null}
config.window_close_confirmation = 'NeverPrompt'
```

### Skip Close Confirmation for Processes

<ParamField path="skip_close_confirmation_for_processes_named" type="array" default="[]">
  Array of process names that won't trigger close confirmation.
</ParamField>

```lua theme={null}
config.skip_close_confirmation_for_processes_named = {
  'bash',
  'sh',
  'zsh',
  'fish',
  'tmux',
}
```

## Window Behavior

### Quit When All Windows Closed

<ParamField path="quit_when_all_windows_are_closed" type="boolean" default="true">
  When true, WezTerm quits when the last window is closed.
</ParamField>

```lua theme={null}
config.quit_when_all_windows_are_closed = false
```

### Native macOS Fullscreen

<ParamField path="native_macos_fullscreen_mode" type="boolean" default="false">
  When true, uses native macOS fullscreen mode with animations and separate Space.
</ParamField>

```lua theme={null}
config.native_macos_fullscreen_mode = true
```

### macOS Fullscreen Notch Behavior

<ParamField path="macos_fullscreen_extend_behind_notch" type="boolean" default="false">
  On macOS with notch, extend fullscreen content behind the notch.
</ParamField>

```lua theme={null}
config.macos_fullscreen_extend_behind_notch = true
```

## Window Resize Behavior

### Use Resize Increments

<ParamField path="use_resize_increments" type="boolean" default="false">
  When true, window resizing snaps to character cell boundaries.
</ParamField>

```lua theme={null}
config.use_resize_increments = true
```

## Tiling Desktop Environments

<ParamField path="tiling_desktop_environments" type="array" default="['X11 LG3D', 'X11 bspwm', ...]">
  List of desktop environments detected as tiling window managers.
</ParamField>

```lua theme={null}
config.tiling_desktop_environments = {
  'X11 bspwm',
  'X11 i3',
  'X11 dwm',
}
```

## Complete Window Configuration Example

```lua theme={null}
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](./color-schemes) - Configure colors
* [Fonts](./fonts) - Font configuration
* [Tab Bar Configuration](/config/appearance#tab-bar) - Tab bar appearance