Skip to main content

​
Quick Start Guide

Get Ghostty running on your system in minutes. This guide assumes you’ve already installed Ghostty.

​
First Launch

1

Launch Ghostty

Open Ghostty from your Applications folder (macOS) or application launcher (Linux).
# Or launch from terminal
ghostty
You’ll see a new terminal window with Ghostty’s default theme and settings.
2

Verify Installation

Check that Ghostty is working correctly:
# Check version
ghostty --version

# List available commands
ghostty --help
3

Test Performance

Experience Ghostty’s speed:
# Fast text rendering
cat /usr/share/dict/words

# Or generate some output
for i in {1..1000}; do echo "Line $i: Ghostty is fast!"; done
Notice how smoothly text renders even under heavy load.

​
Basic Configuration

Ghostty’s configuration file is located at:
  • macOS: ~/.config/ghostty/config
  • Linux: ~/.config/ghostty/config (or $XDG_CONFIG_HOME/ghostty/config)
If the config file doesn’t exist, create it along with the directory:
mkdir -p ~/.config/ghostty
touch ~/.config/ghostty/config

​
Essential Configuration

Add these settings to your ~/.config/ghostty/config file: 
# Font configuration
font-family = "JetBrains Mono"
font-size = 13

# Theme colors
background = #1e1e2e
foreground = #cdd6f4

# Cursor settings
cursor-style = block
cursor-color = #f5e0dc
Ghostty comes with built-in themes! Use ghostty +list-themes to see all available themes, then set one with theme = theme-name in your config.

​
Apply Configuration Changes

Ghostty automatically reloads configuration when you save changes. No restart required! 
# Edit your config
ghosstty +edit-config

# Or validate your config
ghosstty +validate-config

# View current config
ghosstty +show-config

​
Essential Keybindings

Ghostty comes with sensible defaults. Here are the most important shortcuts:

​
macOS

ActionKeybinding
New Window⌘ + N
New Tab⌘ + T
Close Tab/Window⌘ + W
Split Horizontal⌘ + D
Split Vertical⌘ + Shift + D
Next Tab⌘ + Shift + ]
Previous Tab⌘ + Shift + [
Settings⌘ + ,
Clear Screen⌘ + K

​
Linux

ActionKeybinding
New WindowCtrl + Shift + N
New TabCtrl + Shift + T
Close Tab/WindowCtrl + Shift + W
Split HorizontalCtrl + Shift + D
Next TabCtrl + Tab
Previous TabCtrl + Shift + Tab
Clear ScreenCtrl + Shift + K
All keybindings are fully customizable. See Keybindings Configuration for details.

​
Working with Windows and Splits

1

Create a Split

Split your terminal horizontally or vertically:
  • Horizontal: ⌘ + D (macOS) or Ctrl + Shift + D (Linux)
  • Vertical: ⌘ + Shift + D (macOS)
Navigate between splits using focus keybindings.
2

Open Multiple Tabs

Create tabs for different tasks:
  • New Tab: ⌘ + T (macOS) or Ctrl + Shift + T (Linux)
  • Switch Tabs: ⌘ + Shift + ] / [ (macOS) or Ctrl + Tab (Linux)
3

Multiple Windows

Open multiple independent Ghostty windows:
  • New Window: ⌘ + N (macOS) or Ctrl + Shift + N (Linux)

​
Discovering Fonts and Themes

​
List Available Fonts

# See all fonts Ghostty can find
ghosstty +list-fonts

# Search for a specific font
ghosstty +list-fonts | grep -i "mono"

​
Explore Built-in Themes

# List all themes
ghosstty +list-themes

# Some popular themes:
# - catppuccin-mocha
# - dracula
# - nord
# - solarized-dark
# - tokyo-night
Add your chosen theme to config: 
theme = catppuccin-mocha

​
Enable Shell Integration

Shell integration adds powerful features like:
  • Jump between prompts
  • Semantic understanding of shell output
  • Better clipboard integration
  • Command status indicators
Add to your ~/.bashrc:
if [ -n "$GHOSTTY_RESOURCES_DIR" ]; then
    source "$GHOSTTY_RESOURCES_DIR/shell-integration/bash/ghostty.bash"
fi
Learn more about shell integration features in the Shell Integration guide.

​
Useful CLI Commands

Ghostty provides helpful CLI tools: 
# Edit config in your default editor
ghosstty +edit-config

# Validate your configuration
ghosstty +validate-config

# Show effective configuration (including defaults)
ghosstty +show-config

# List all keybindings
ghosstty +list-keybinds

# List all available actions
ghosstty +list-actions

# Check for crash reports
ghosstty +crash-report

​
Next Steps

Deep Dive into Configuration

Explore all configuration options for fonts, colors, keybindings, and more

Customize Appearance

Learn about themes, colors, and visual customization

Master Features

Discover advanced features like custom themes and performance tuning

Troubleshooting

Get help with common issues and configuration problems

​
Getting Help

If you run into issues:
  1. Check logs: Ghostty logs to stderr by default
    • macOS: sudo log stream --level debug --predicate 'subsystem=="com.mitchellh.ghostty"'
    • Linux: journalctl --user --unit app-com.mitchellh.ghostty.service
  2. Validate config: Run ghostty +validate-config to catch syntax errors
  3. Review documentation: Check the Troubleshooting Guide
  4. Join the community: Report issues on GitHub
You’re now ready to use Ghostty! Experiment with different themes, fonts, and configurations to make it your own.