Quick Start Guide

Get up and running with Ghostty in under 5 minutes

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:

Basic Setup

# Font configuration
font-family = "JetBrains Mono"
font-size = 13

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

# Cursor settings
cursor-style = block
cursor-color = #f5e0dc

# Font with ligatures
font-family = "Fira Code"
font-size = 12
font-feature = +liga
font-feature = +calt

# Catppuccin Mocha theme
background = #1e1e2e
foreground = #cdd6f4

# Palette colors
palette = 0=#45475a
palette = 1=#f38ba8
palette = 2=#a6e3a1
palette = 3=#f9e2af
palette = 4=#89b4fa
palette = 5=#f5c2e7
palette = 6=#94e2d5
palette = 7=#bac2de

# Window settings
window-padding-x = 10
window-padding-y = 10
window-theme = dark

# Just the essentials
font-family = "SF Mono"
font-size = 13
theme = catppuccin-mocha

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

Action	Keybinding
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

Action	Keybinding
New Window	Ctrl + Shift + N
New Tab	Ctrl + Shift + T
Close Tab/Window	Ctrl + Shift + W
Split Horizontal	Ctrl + Shift + D
Next Tab	Ctrl + Tab
Previous Tab	Ctrl + Shift + Tab
Clear Screen	Ctrl + 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

Bash

Add to your ~/.bashrc:

if [ -n "$GHOSTTY_RESOURCES_DIR" ]; then
    source "$GHOSTTY_RESOURCES_DIR/shell-integration/bash/ghostty.bash"
fi

Zsh

Add to your ~/.zshrc:

if [ -n "$GHOSTTY_RESOURCES_DIR" ]; then
    source "$GHOSTTY_RESOURCES_DIR/shell-integration/zsh/ghostty.zsh"
fi

Fish

Add to your ~/.config/fish/config.fish:

if set -q GHOSTTY_RESOURCES_DIR
    source "$GHOSTTY_RESOURCES_DIR/shell-integration/fish/ghostty.fish"
end

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.