Skip to main content

​
Window Size and Position

​
Initial Window Size

# Set initial window size (in grid cells)
window-width = 120
window-height = 40
Both window-width and window-height must be set to take effect. If only one is set, it’s ignored.
Not currently. Window size is specified in terminal grid cells. Pixel-based sizing may be added in the future.
Windows smaller than 10 columns by 4 rows are not allowed.
Linux/GTK: Window size doesn’t properly account for window decorations. Grid dimensions won’t exactly match when decorations are enabled. Disable decorations (window-decoration = none) for accurate sizing.

​
Window Position

# Set window position (in pixels)
window-position-x = 100
window-position-y = 100
Position is relative to the top-left corner of the visible screen area (below the menu bar if visible).✅ Supported
Both window-position-x and window-position-y must be set to take effect.

​
Maximize and Fullscreen

# Start maximized
maximize = true

# Start fullscreen
fullscreen = true
These settings apply to all new windows, not just the first one.
macOS: fullscreen = true doesn’t work with window-decoration = none (native fullscreen requires decorations).

​
Window Decorations

Control window chrome (titlebar, borders, etc.): 
window-decoration = auto      # Auto-detect (default)
window-decoration = none      # No decorations
window-decoration = client    # Client-side decorations
window-decoration = server    # Server-side decorations

# Legacy boolean values
window-decoration = true      # Same as "auto"
window-decoration = false     # Same as "none"
Only none and auto/true are meaningful:
  • none: Removes titlebar and borders, disables tabs
  • auto/true: Standard macOS window
Use macos-titlebar-style = hidden to hide titlebar while keeping borders.
Toggle decorations at runtime with the toggle_window_decorations keybind action.

​
Window Padding

​
Horizontal and Vertical Padding

# Symmetric padding
window-padding-x = 4  # 4pt left and right
window-padding-y = 4  # 4pt top and bottom

# Asymmetric padding
window-padding-x = 2,4  # 2pt left, 4pt right
window-padding-y = 2,8  # 2pt top, 8pt bottom
Excessive padding will squish the grid. Pick reasonable values. Warnings appear in logs for unreasonable values.
Padding changes at runtime only affect new terminals (windows, tabs, splits).

​
Padding Balance

# Automatically balance extra padding
window-padding-balance = true
When viewport dimensions aren’t perfectly divisible by cell size, extra padding exists. This option balances it across all edges instead of leaving it on the right and bottom.

​
Padding Color

window-padding-color = background      # Use background color (default)
window-padding-color = extend          # Extend nearest cell color
window-padding-color = extend-always   # Always extend (ignore heuristics)
On primary screen applications (not alternate screen like Vim), vertical extension is disabled if:
  • Nearest row has default background color cells
  • Nearest row is a prompt (requires shell integration)
  • Nearest row contains powerline characters
These heuristics prevent ugly powerline artifacts.

​
Window Behavior

​
VSync (macOS)

# Sync rendering with screen refresh
window-vsync = true   # Minimize tearing (default)
window-vsync = false  # Maximize responsiveness
macOS: Out-of-sync rendering can cause kernel panics (macOS 14.4+) and performance issues with external displays over DisplayLink.Set to false only if you need minimal input latency and understand the risks.
Changing window-vsync at runtime only affects new terminals.

​
Step Resize (macOS)

# Resize window in cell-size increments
window-step-resize = true
When enabled, window resizing snaps to grid cell sizes. When disabled, resizes in pixel increments.

​
Working Directory Inheritance

# New windows inherit working directory
window-inherit-working-directory = true  # Default

# New tabs inherit working directory
tab-inherit-working-directory = true     # Default

# New splits inherit working directory
split-inherit-working-directory = true   # Default
Inheritance requires shell integration. Without it, the default working-directory is used.

​
Font Size Inheritance

# New windows inherit font size from focused window
window-inherit-font-size = true  # Default
When false, new windows use the configured font-size.

​
Window Title

​
Fixed Title

# Force a specific window title
title = My Terminal

# Blank title (effectively hides it)
title = " "
When set, Ghostty ignores all title change escape sequences from programs.
Reload config with title unset or removed. The next title change escape sequence will be honored, but you may need to restart programs (like Neovim) to trigger it.

​
Window Subtitle (GTK)

window-subtitle = false                # No subtitle (default)
window-subtitle = working-directory    # Show working directory
GTK only (since 1.1.0)

​
Title Font (macOS)

# Set custom titlebar font
window-title-font-family = SF Pro Display
If unset, the system default font is used. Any font available on the system may be used (not limited to monospace).

​
Tabs

​
Tab Visibility (GTK)

window-show-tab-bar = auto     # Show when 2+ tabs (default)
window-show-tab-bar = always   # Always show
window-show-tab-bar = never    # Never show (use keybinds/overview)
Currently only supported on Linux (GTK).

​
Tab Position

window-new-tab-position = current  # After focused tab (default)
window-new-tab-position = end      # At end of tab list

​
Splits

​
Split Appearance

# Unfocused split opacity (0.15-1.0)
unfocused-split-opacity = 0.7

# Unfocused split dim color
unfocused-split-fill = #000000

# Split divider color (since 1.1.0)
split-divider-color = #3E4451

​
Preserve Zoom

Control zoom behavior when navigating splits: 
split-preserve-zoom = navigation  # Keep zoom when switching splits
split-preserve-zoom = no-navigation  # Unzoom when switching (default)
By default, any operation changing focus or layout unzooms. With navigation, the zoomed state moves to the newly focused split.Available since 1.3.0.

​
Resize Overlay

​
When to Show

resize-overlay = always       # Always show
resize-overlay = never        # Never show
resize-overlay = after-first  # Not on first creation (default)

​
Overlay Position

resize-overlay-position = center        # Default
resize-overlay-position = top-left
resize-overlay-position = top-center
resize-overlay-position = top-right
resize-overlay-position = bottom-left
resize-overlay-position = bottom-center
resize-overlay-position = bottom-right

​
Overlay Duration

# How long to show overlay (default: 750ms)
resize-overlay-duration = 1s
resize-overlay-duration = 500ms
resize-overlay-duration = 1s500ms

​
Window State

​
Save and Restore (macOS)

window-save-state = default  # System behavior (default)
window-save-state = always   # Always save on exit
window-save-state = never    # Never save
On macOS:
  • Saves state if app is forcibly terminated
  • Saves state if configured systemwide in Settings.app
On Linux: No effect (not implemented).
Changing to never while Ghostty isn’t running prevents restoring state on next launch. Changing from never while not running won’t restore previous state (state only saved on exit).

​
Window Theme

window-theme = auto     # Based on terminal background (default)
window-theme = system   # Follow system theme
window-theme = light    # Always light
window-theme = dark     # Always dark
window-theme = ghostty  # Use Ghostty colors (Linux only)
On macOS with macos-titlebar-style = tabs or transparent, window theme is automatically determined by background luminosity.

​
Titlebar Colors (GTK)

# Only works with window-theme = ghostty
window-titlebar-background = #282C34
window-titlebar-foreground = #FFFFFF

​
Linux/GTK-Specific

​
Application Class

# X11 WM_CLASS, Wayland app ID, DBus name
class = com.mitchellh.ghostty  # Default
Changing class creates separate Ghostty instances with gtk-single-instance=true. May break .desktop file launching and DBus activation.Must follow GTK ID requirements.

​
X11 Instance Name

# X11 WM_CLASS instance name
x11-instance-name = ghostty  # Default
Only affects X11. No effect on Wayland.

​
macOS-Specific

​
Titlebar Style

macos-titlebar-style = transparent  # Transparent titlebar (default)
macos-titlebar-style = native       # Native macOS titlebar
macos-titlebar-style = tabs         # Custom integrated tab bar
macos-titlebar-style = hidden       # Hidden titlebar, keeps borders
  • native: Standard macOS titlebar matching window theme
  • transparent: Native but transparent, shows background color
  • tabs: Custom titlebar integrating tab bar, matches terminal background
  • hidden: Removes titlebar but keeps rounded corners and borders
tabs style on macOS 13 and below: Saved window state won’t restore tabs correctly. macOS 14+ works fine.
hidden style: Window can’t be dragged by titlebar. Use option+click on resizable frame areas to drag (standard macOS behavior).

​
Window Buttons (macOS)

macos-window-buttons = visible  # Show traffic lights (default)
macos-window-buttons = hidden   # Hide traffic lights
No effect when window-decoration = none or macos-titlebar-style = hidden (buttons always hidden).Changing at runtime only affects new windows. Since 1.2.0.

​
Proxy Icon (macOS)

macos-titlebar-proxy-icon = visible  # Show folder icon (default)
macos-titlebar-proxy-icon = hidden   # Hide folder icon
The proxy icon represents the current working directory. Only visible with native titlebar style.
Changes at runtime apply to all windows, but only take effect after their working directory changes again (e.g., cd to another directory).

​
Window Shadow (macOS)

macos-window-shadow = true   # Show shadow (default)
macos-window-shadow = false  # No shadow
With window managers and transparency, false may look better.

​
Non-Native Fullscreen (macOS)

macos-non-native-fullscreen = false          # Native fullscreen (default)
macos-non-native-fullscreen = true           # Fast fullscreen, hide menu
macos-non-native-fullscreen = visible-menu   # Fast fullscreen, show menu
macos-non-native-fullscreen = padded-notch   # Fast fullscreen, pad notch
Important: Tabs do not work in non-native fullscreen mode (titlebar is removed, macOS tabs require it).If you fullscreen a tabbed window, the focused tab goes fullscreen while others remain in a background window.
  • Native: Uses macOS spaces with animations (slower)
  • Non-native: Instant fullscreen without animations (faster)
padded-notch prevents window from being obscured by the notch on applicable devices.

​
Initial Window

# Create initial window on startup
initial-window = true   # Default
initial-window = false  # Don't create window
If quit-after-last-window-closed = true and initial-window = false, Ghostty quits after the delay if no window is ever created.

​
Resources

Appearance

Colors and visual customization

Terminal Behavior

Terminal-specific settings

Keybindings

Window and split navigation keybinds

Shell Integration

Working directory inheritance