Migration Guide

Migrate to Ghostty from other terminal emulators like iTerm2, Alacritty, Kitty, or Terminal.app

This guide helps you migrate to Ghostty from other popular terminal emulators. Ghostty is designed to be a drop-in replacement for your existing terminal while providing competitive performance, modern features, and native platform experiences.

Why Ghostty?

Ghostty differentiates itself by providing all three of:

• Fast performance - Competitive with the fastest terminal emulators
• Feature-rich - Modern terminal features and UI capabilities
• Native - True platform-native UIs (SwiftUI on macOS, GTK on Linux)

Most terminal emulators force you to choose between these categories. Ghostty provides all three without compromise.

Quick Start for Migration

1. Install Ghostty

   See the installation guide for your platform.

2. Convert your config

   Use the sections below for your current terminal emulator to convert your configuration.

3. Set up shell integration

   # Bash
   echo 'eval "$(ghostty +shell-integration bash)"' >> ~/.bashrc
   
   # Zsh  
   echo 'eval "$(ghostty +shell-integration zsh)"' >> ~/.zshrc
   
   # Fish
   echo 'ghostty +shell-integration fish | source' >> ~/.config/fish/config.fish
   
4. Set as default terminal

   Make Ghostty your default terminal in your system settings.

Migration from iTerm2

iTerm2

Feature-rich macOS terminal with extensive customization

Ghostty

Native SwiftUI app with Metal renderer and modern features

Feature Comparison

Feature	iTerm2	Ghostty
Tabs	✅	✅
Splits	✅	✅
Profiles	✅	✅ (via config files)
Metal Rendering	⚠️ (except with ligatures)	✅
Ligatures	✅ (CPU renderer)	✅ (GPU accelerated)
Shell Integration	✅	✅
Triggers	✅	⚠️ (limited)
Themes	✅	✅
True Color	✅	✅
tmux Integration	✅	➖

Configuration Migration

iTerm2 uses a GUI preferences panel while Ghostty uses a text configuration file.

Config file location:

• iTerm2: ~/Library/Preferences/com.googlecode.iterm2.plist
• Ghostty: ~/.config/ghostty/config

Common settings:

# Font
font-family = "SF Mono"
font-size = 14

# Colors (example)
background = 000000
foreground = ffffff

# Window
window-padding-x = 2
window-padding-y = 2

# Cursor
cursor-style = block
cursor-style-blink = true

# Scrollback
scrollback-limit = 10000

# Shell
shell-integration = true

Keyboard Shortcuts

iTerm2 and Ghostty have different default keybindings. Here are common mappings:

# Tabs
keybind = cmd+t=new_tab
keybind = cmd+w=close_tab
keybind = cmd+shift+left_bracket=goto_tab:previous
keybind = cmd+shift+right_bracket=goto_tab:next

# Splits
keybind = cmd+d=new_split:right
keybind = cmd+shift+d=new_split:down

# Copy/Paste
keybind = cmd+c=copy_to_clipboard
keybind = cmd+v=paste_from_clipboard

# Clear
keybind = cmd+k=clear_screen

Migration from Alacritty

Alacritty

GPU-accelerated, minimal, cross-platform terminal

Ghostty

GPU-accelerated with additional features and native UI

Feature Comparison

Feature	Alacritty	Ghostty
GPU Acceleration	✅	✅
Performance	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Config File	YAML/TOML	Custom format
Tabs	➖	✅
Splits	➖	✅
Ligatures	✅	✅
Shell Integration	➖	✅
True Color	✅	✅
Cross-platform	✅	✅ (macOS, Linux)

Configuration Migration

Alacritty uses YAML/TOML while Ghostty uses a simpler key-value format.

Alacritty config location:

• ~/.config/alacritty/alacritty.yml or .toml

Ghostty config location:

• ~/.config/ghostty/config

Example conversion:

Alacritty (alacritty.yml)

font:
  normal:
    family: JetBrains Mono
  size: 12.0

colors:
  primary:
    background: '#1e1e1e'
    foreground: '#d4d4d4'

window:
  padding:
    x: 8
    y: 8
  decorations: full

cursor:
  style:
    shape: Block
    blinking: On

scrollback:
  limit: 10000

font-family = "JetBrains Mono"
font-size = 12

background = 1e1e1e
foreground = d4d4d4

window-padding-x = 8
window-padding-y = 8

cursor-style = block
cursor-style-blink = true

scrollback-limit = 10000

Key Differences

• Tabs/Splits: Ghostty has built-in tabs and splits, whereas Alacritty requires tmux or similar
• Shell Integration: Ghostty includes shell integration features
• Native UI: Ghostty has native window management vs Alacritty’s custom rendering

Migration from Kitty

Kitty

GPU-accelerated with advanced features and scripting

Ghostty

Native UI with competitive features and performance

Feature Comparison

Feature	Kitty	Ghostty
GPU Acceleration	✅	✅
Tabs	✅	✅
Splits/Layouts	✅	✅
Ligatures	✅	✅
Images	✅ (Kitty graphics protocol)	⚠️ (Limited)
Extensions	✅ (Kittens)	➖
Remote Control	✅	⚠️ (Limited)
Native UI	➖	✅
True Color	✅	✅

Configuration Migration

Kitty and Ghostty both use key-value configuration formats, making migration straightforward.

Config locations:

• Kitty: ~/.config/kitty/kitty.conf
• Ghostty: ~/.config/ghostty/config

Example conversion:

Kitty (kitty.conf)

font_family      JetBrains Mono
font_size        12.0

background       #1e1e1e
foreground       #d4d4d4

window_padding_width  8

cursor_shape     block
cursor_blink_interval  0.5

scrollback_lines 10000

tab_bar_style    powerline

font-family = "JetBrains Mono"
font-size = 12

background = 1e1e1e
foreground = d4d4d4

window-padding-x = 8
window-padding-y = 8

cursor-style = block
cursor-style-blink = true

scrollback-limit = 10000

Key Differences

• Syntax: Kitty uses underscores (font_family), Ghostty uses hyphens (font-family)
• Kittens: Ghostty doesn’t have an equivalent extension system
• Layouts: Both support splits, but with different management approaches
• Graphics: Kitty’s graphics protocol is more extensive

Migration from Terminal.app

Terminal.app

macOS default terminal with basic features

Ghostty

Modern native macOS terminal with advanced features

Feature Comparison

Feature	Terminal.app	Ghostty
Native macOS	✅	✅
Tabs	✅	✅
Splits	➖	✅
GPU Acceleration	⚠️	✅ (Metal)
Ligatures	✅	✅
Profiles	✅	✅ (via config)
Shell Integration	Basic	Advanced
Performance	⭐⭐⭐	⭐⭐⭐⭐⭐
True Color	✅	✅

Configuration Migration

Terminal.app uses GUI preferences while Ghostty uses a text config file.

Basic Ghostty config:

# Font (Terminal.app default)
font-family = "SF Mono"
font-size = 11

# Colors (Terminal.app "Basic" theme)
background = ffffff
foreground = 000000

# Cursor
cursor-style = block
cursor-style-blink = true

# Window
window-padding-x = 2
window-padding-y = 2

# Shell integration
shell-integration = true

General Configuration Tips

Theme/Color Schemes

Many terminal color schemes are available online. To use them with Ghostty:

1. Create a theme file: ~/.config/ghostty/themes/my-theme
2. Add colors in the format:
   background = 282c34
   foreground = abb2bf
   # ... more colors
   
3. Reference in config:
   theme = my-theme
   

Popular theme collections:

• Gogh
• iTerm2 Color Schemes

Font Configuration

# Basic font setup
font-family = "JetBrains Mono"
font-size = 13

# Enable ligatures
font-feature = +calt
font-feature = +liga

# Font variations
font-style = Regular
font-style-bold = Bold
font-style-italic = Italic

Performance Tuning

If migrating from a slower terminal:

# Ensure GPU rendering is enabled (default)
renderer = auto

# Adjust scrollback for performance
scrollback-limit = 10000

# Disable expensive features if needed
background-opacity = 1.0
background-blur-radius = 0

Tmux Users

If you use tmux heavily:

• Ghostty has built-in tabs and splits that may reduce your need for tmux
• Ghostty works great with tmux if you still need it
• Shell integration works inside tmux sessions

Example config for tmux users:

# Ensure true color support
shell-integration = true

# Good defaults for tmux
scrollback-limit = 50000

# Copy mode compatibility
keybind = ctrl+shift+c=copy_to_clipboard
keybind = ctrl+shift+v=paste_from_clipboard

Next Steps

After migrating:

1. Explore the config reference: Configuration Documentation
2. Set up shell integration: Enhanced prompt features and navigation
3. Customize keybindings: Make Ghostty feel like home
4. Try advanced features:
   • Custom inspector for debugging
   • Shell integration features
   • Native platform features

Ghostty is actively developed. Check the GitHub repository for the latest features and updates.

Getting Help

If you need help during migration:

• GitHub Discussions - Q&A and community help
• Discord Server - Real-time help in the #help channel
• Troubleshooting Guide - Common issues and solutions