GTK Single Instance Mode

Ghostty uses GTK single instance mode by default when it detects it is not launched from a CLI environment.

GTK single instance mode is recommended by the GTK project and is the idiomatic way official Gnome applications are expected to behave. When a second instance of Ghostty is launched, the original instance will create a new window, gain focus, and terminate the second instance.

Tip

If you're using Ghostty on Linux and are experiencing slow startup times or high memory usage, GTK single instance detection may not be working for your environment and you may need to force it on. Continue reading this page to learn more.

The default behavior of Ghostty is to use GTK single instance mode when not launched from a CLI environment.

Ghostty has this behavior because CLI terminal usage is common (i.e. ghostty -e "some command") and in those cases the expected behavior is to launch a new process and block until it exits. Single instance mode doesn't allow us to easily do this so we only want to enable single instance mode when launched from a non-CLI environment.

There isn't a standard API to detect if an application is launched from a non-CLI environment, so Ghostty uses the following heuristic:

1. If the TERM_PROGRAM environment variable is set to any non-empty value, we're assume we're in a graphical terminal emulator and disable GTK single instance mode.

2. If any command line arguments are passed to Ghostty, we assume we want instance-specific configuration and disable GTK single instance mode.

You can force GTK single instance mode on or off by setting the gtk-single-instance option:

gtk-single-instance = true

A value of true forces Ghostty to run in single instance mode. In this mode, each new ghostty process will result in a new window in an existing instance of Ghostty if one is running.

Ghostty is a GTK application. The GTK framework has unavoidable overhead when starting up, both in terms of how long it takes and how much memory it uses. Ghostty can't do anything about this.

GTK single instance mode avoids this overhead for subsequent instances of Ghostty. Launching a second instance of Ghostty will be extremely fast and use very little memory since it is just creating a new window in the existing instance.