Info

This guide provides a quickstart using ghostty — from the config file itself, to theming, transparency, and window sizing.

Master quick append

Paste into ~/.config/ghostty/config.ghostty, then reload with Ctrl+Shift+,. Each option is explained in the sections below.

~/.config/ghostty/config.ghostty

# transparency: lower is more transparent (blur needs Blur my Shell on GNOME)
background-opacity = 0.8
background-blur = true

# initial window grid size in columns and rows
window-width = 120
window-height = 40

# restore window state across launches: default | never | always
window-save-state = never

On GNOME, Ctrl+Alt+Up/Down conflicts with ghostty's split-focus shortcuts — see Focus-Split Up/Down on GNOME below to fix it.

Installation

For the official install guide from Ghostty, see the upstream documentation.

Note that ghostty has no single official Linux package except for Arch — the methods below are the recommended community approaches.

Fedora (Terra)

With Terra enabled:

sudo dnf install ghostty

Debian/Ubuntu

Ubuntu users can use the community install script:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/mkasberg/ghostty-ubuntu/HEAD/install.sh)"

Warning

This is an Ubuntu-focused installer and may not be compatible with Debian. Before running any curl | bash script, we recommend inspecting it first at mkasberg/ghostty-ubuntu. For anything outside Ubuntu, refer to the official install guide.

Arch

ghostty is in the official [extra] repository:

sudo pacman -S ghostty

Prerelease builds are available in the AUR as ghostty-git.

Config File

Location and syntax

ghostty reads its configuration from ~/.config/ghostty/config.ghostty.

The file uses a simple key = value format

• One key per line.
• Keys are case-sensitive.
• Comments must be on their own line starting with #; inline trailing comments are not supported.
• Setting a key to an empty value (e.g. theme =) resets it to its default.

~/.config/ghostty/config.ghostty

# This is a valid comment
theme = Everforest Dark Hard
background-opacity = 0.8

Reloading the config

Ctrl+Shift+, (the default keybind on Linux) to reload it at runtime.

Theme and Transparency

Applying a theme

Tips

Run ghostty +list-themes in a terminal to browse all built-in themes before committing to one.

~/.config/ghostty/config.ghostty

theme = Everforest Dark Hard

Background transparency and blur

~/.config/ghostty/config.ghostty

# background-opicity: lower is more transparent
background-opacity = 0.8
background-blur = true

Warning

background-blur relies on the KDE blur protocol; on a standard GNOME Wayland session, background-blur is ignored. Transparency (background-opacity) still works — only blur is N/A.

If you want blur on GNOME, install the Blur my Shell extension and enable its application blur to blur for ghostty.

Default Window Size

The keys window-width and window-height set the initial terminal grid size in rows and columns.

The default 0 lets the OS or window manager decide. Both keys must be set together for the config to be valid.

~/.config/ghostty/config.ghostty

window-width = 120
window-height = 40

window-save-state controls whether ghostty restores the previous window state (including size) across launches. Accepted values are default, never, and always.

~/.config/ghostty/config.ghostty

window-save-state = never

Keyboard Shortcuts

ghostty ships with sensible default keybinds. For reference, see this keyboard shortcuts cheatsheet.

Focus-Split Up/Down on GNOME

Ctrl+Alt+Up and Ctrl+Alt+Down are grabbed by the GNOME compositor for vertical workspace switching. This means the default focus-split up/down shortcuts do not fire. The left/right directions (Ctrl+Alt+Left / Ctrl+Alt+Right) are unaffected.

Quick fix

gsettings set org.gnome.desktop.wm.keybindings switch-to-workspace-up "[]"
gsettings set org.gnome.desktop.wm.keybindings switch-to-workspace-down "[]"

GNOME Keyboard Shortcut

We can bind a key combo in GNOME Settings to launch ghostty to access the terminal quickly.

• Open keyboard shortcuts

  Open Settings -> Keyboard. Under "Keyboard Shortcuts", click View and Customise Shortcuts.

• Navigate to custom shortcuts

  Scroll to the bottom of the list and select Custom Shortcuts, then click the + button to add a new entry.

• Fill in the shortcut details

  Enter a name (e.g. "Ghostty") and set the command to ghostty.

• Set the key combo

  Click Set Shortcut and press your desired combination — for example Super+Return or Ctrl+Alt+T.

• Confirm

  Click Add to save. The shortcut is active immediately — no logout required.

Contributors

aier9500

Changelog

8/3/26, 2:59 AM

View All Changelog

• 3c19f-Fedora guide: codecs, RPM Fusion, firmware, hardware decodeon 8/3/26
• c1fd3-Install via terra repo: ghostty and yazion 7/23/26
• dfe76-one assets folder,, ghostty migrationon 7/21/26
• 7150e-1. Fresh Editor → editors-choice.md. Verified as getfresh.dev (sinelaw/fresh) — Rust terminal editor, VS Code-feel. Install tabs: AUR fresh-editor-bin + official script. Several GitHub lookalikes exist; agent confirmed canonical project across independent sources. 2. Focus changer → aiers-gnome.md under Others, next to Tiling Shell. Link verified, plain 2-sentence description, no screenshot (none available). 3. Ghostty GNOME fix simplified — dropped alt+shift+arrow rebinds and the duplicate GNOME quick-append block. One master quick append now; GNOME section teaches clearing "Switch to workspace above/below" in Settings, gsettings fallback in :::details. Schema keys source-verified from gschema XML. 4. New keyd settings propagated — your root default.conf moved to resources/key-remapping-with-keyd/, stale header comment fixed (said double-shift→caps; body actually uses [shift] layer capslock = capslock). Guide example, mapping table, and keyd-setup.sh heredoc all synced; folder got first README.on 7/4/26
• 47a19-Ghostty approved.on 6/22/26
• 87203-Updated configs from canonical setup aierNix.on 6/19/26
• 5ba10-Update default terminal height to 40 (modern)on 6/17/26
• d1c34-Too transparent, up the opacity.on 6/12/26
• e8637-ghosty higher transparencyon 6/11/26
• f30ac-graphifyon 6/11/26
• b2019-Ghostty guideon 6/11/26