Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ghostty-org/ghostty/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers common issues you might encounter when using Ghostty and how to resolve them.

​
General Troubleshooting

​
Finding Logs

Logs are essential for diagnosing issues. Ghostty writes logs to different locations depending on your platform and how it was launched.
Ghostty logs to the macOS unified log system by default.View logs in real-time:
sudo log stream --level debug --predicate 'subsystem=="com.mitchellh.ghostty"'
View recent logs:
log show --predicate 'subsystem=="com.mitchellh.ghostty"' --last 1h

​
Enabling Debug Logging

Set the GHOSTTY_LOG environment variable to control logging: 
# Enable all logging destinations
GHOSTTY_LOG=true ghostty

# Enable stderr logging
GHOSTTY_LOG=stderr ghostty

# Enable macOS unified log (macOS only)
GHOSTTY_LOG=macos ghostty

# Combine multiple destinations
GHOSTTY_LOG=stderr,macos ghostty

​
Crash Reports

Ghostty has a built-in crash reporter that saves crash reports to disk. Crash report location:
  • $XDG_STATE_HOME/ghostty/crash (if $XDG_STATE_HOME is set)
  • ~/.local/state/ghostty/crash (default)
List crash reports: 
ghostty +crash-report
Crash reports are generated the next time Ghostty starts after a crash. You must restart Ghostty at least once to generate a crash report.
Crash reports can contain sensitive information from stack memory. Review before sharing publicly.

​
Common Issues

Steps to diagnose:
  1. Check logs for error messages (see Finding Logs)
  2. Try safe mode by disabling your config: 
    ghostty --config-file=/dev/null
  3. Check GPU compatibility:
    • Ghostty uses Metal on macOS and OpenGL on Linux
    • Update graphics drivers
    • Try disabling GPU acceleration in config: 
      # Add to config file
renderer = software
  4. Verify installation: 
    which ghostty
ghostty --version
  5. Check crash reports: 
    ghostty +crash-report
Common font issues:
  • Font not found: Verify the font is installed 
    # List available fonts (macOS)
fc-list : family | sort | uniq
  • Wrong font being used: Check config file syntax 
    font-family = "JetBrains Mono"
font-size = 14
  • Font looks blurry: Try adjusting font hinting 
    font-hinting = full
  • Ligatures not working: Enable font features 
    font-feature = +calt
font-feature = +liga
  • Emoji not displaying: Ensure an emoji font is available 
    # macOS usually has Apple Color Emoji by default
# Linux may need:
sudo apt install fonts-noto-color-emoji
Check config file location:Ghostty looks for config files in this order:
  1. $XDG_CONFIG_HOME/ghostty/config (if $XDG_CONFIG_HOME is set)
  2. ~/.config/ghostty/config (Linux/macOS default)
  3. ~/Library/Application Support/com.mitchellh.ghostty/config (macOS app)
Verify syntax:
# Run with explicit config file
ghostty --config-file=/path/to/config
Common syntax errors:
  • No quotes around values with spaces: font-family = "Fira Code"
  • Incorrect option names (check documentation)
  • Comments must start with #
Test with minimal config:
# Minimal config for testing
font-family = monospace
font-size = 12
Check color configuration:
  1. Verify theme file location:
    • Themes should be in ~/.config/ghostty/themes/
  2. Check theme syntax: 
    # In config file
theme = my-theme
  3. Test with explicit colors: 
    background = 000000
foreground = ffffff
  4. Check terminal TERM value: 
    echo $TERM
# Should be: xterm-ghostty or xterm-256color
  5. True color support: 
    # Test true color
awk 'BEGIN{
    s="/\\-"; s=s s s s s s s s;
    for (colnum = 0; colnum<77; colnum++) {
        r = 255-(colnum*255/76);
        g = (colnum*510/76);
        b = (colnum*255/76);
        if (g>255) g = 510-g;
        printf "\033[48;2;%d;%d;%dm", r,g,b;
        printf "\033[38;2;%d;%d;%dm", 255-r,255-g,255-b;
        printf "%s\033[0m", substr(s,colnum+1,1);
    }
    printf "\n";
}'
Optimization steps:
  1. Check GPU acceleration:
    • Ensure GPU drivers are up to date
    • Verify Ghostty is using GPU: 
      GHOSTTY_LOG=true ghostty 2>&1 | grep -i render
  2. Disable expensive features: 
    # Disable ligatures
font-feature = -calt
font-feature = -liga

# Reduce background opacity
background-opacity = 1.0

# Disable blur
background-blur-radius = 0
  3. Check scrollback buffer size: 
    # Reduce if very large
scrollback-limit = 10000
  4. Monitor resource usage: 
    # macOS
top -pid $(pgrep ghostty)

# Linux
htop -p $(pgrep ghostty)
  5. Test with clean config: 
    ghostty --config-file=/dev/null
Debugging keybindings:
  1. Check for conflicts:
    • System keybindings may override Ghostty
    • Desktop environment shortcuts
    • Terminal multiplexer keybindings (tmux, screen)
  2. Test keybinding syntax: 
    # Format: modifier+key=action
keybind = ctrl+shift+c=copy_to_clipboard
keybind = ctrl+shift+v=paste_from_clipboard
  3. Clear conflicting bindings: 
    # Unbind a key
keybind = ctrl+shift+c=unbind
  4. Check logs for keybinding errors: 
    GHOSTTY_LOG=stderr ghostty 2>&1 | grep -i keybind
Platform-specific solutions:
Wayland:
  • Ensure wl-clipboard is installed: 
    sudo apt install wl-clipboard
X11:
  • Ensure xclip or xsel is installed: 
    sudo apt install xclip
Config:
keybind = ctrl+shift+c=copy_to_clipboard
keybind = ctrl+shift+v=paste_from_clipboard
Enable shell integration:Shell integration provides features like:
  • Jump between prompts
  • Semantic prompt detection
  • Command history integration
Installation:
# Bash
echo 'eval "$(ghostty +shell-integration bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(ghostty +shell-integration zsh)"' >> ~/.zshrc

# Fish
ghostty +shell-integration fish | source
echo 'ghostty +shell-integration fish | source' >> ~/.config/fish/config.fish
Verify installation:
# Check if GHOSTTY environment variable is set
echo $GHOSTTY
Troubleshooting:
  • Restart your shell after adding integration
  • Check shell integration is enabled in config: 
    shell-integration = true
  • Verify resource directory: 
    ghostty +show-config | grep resource
Common IME issues:Ghostty supports multiple IME systems on Linux:
  • ibus
  • fcitx
  • Wayland and X11
Verify IME environment:
echo $GTK_IM_MODULE
echo $QT_IM_MODULE
echo $XMODIFIERS
Test dead keys:
  1. Set keyboard to Spanish or similar layout
  2. Press ' then a - should produce á
Test CJK input:
  1. Enable Japanese/Chinese input method
  2. Type text and verify preedit display
  3. Press Enter to commit
Known issues:
  • ibus versions 1.5.29, 1.5.30, 1.5.31 may exhibit different behaviors
  • Some IME features may work differently on Wayland vs X11

​
Platform-Specific Issues

​
macOS

If you installed via Homebrew:
brew install ghostty
# App should be in /Applications/Ghostty.app
If building from source, the app bundle is in:
zig-out/Ghostty.app
macOS may block unsigned apps. To allow Ghostty:
  1. Open System Settings
  2. Go to Privacy & Security
  3. Look for message about Ghostty being blocked
  4. Click “Open Anyway”
Or via command line:
xattr -cr /Applications/Ghostty.app

​
Linux

Check desktop entry:
cat ~/.local/share/applications/com.mitchellh.ghostty.desktop
Verify Ghostty is in PATH:
which ghostty
Test launch from terminal:
gtk-launch com.mitchellh.ghostty
Force X11 backend (if using Wayland):
GDK_BACKEND=x11 ghostty
Force Wayland backend:
GDK_BACKEND=wayland ghostty
Check current session:
echo $XDG_SESSION_TYPE

​
Getting Help

If you’re still experiencing issues:
  1. Search existing issues: GitHub Issues
  2. Check discussions: GitHub Discussions
  3. Join Discord: Ghostty Discord Server
  4. Open an issue triage discussion: Use the Issue Triage template
When reporting issues, always include:
  • Ghostty version (ghostty --version)
  • Operating system and version
  • Config file contents (if relevant)
  • Steps to reproduce
  • Relevant log output