ptyxis - Man Page

a container-oriented terminal

Examples (TL;DR)

Open a new Ptyxis window: ptyxis --new-window
Execute a specific command in a new terminal window: ptyxis [-x|--execute] command
Open new tab in the last opened window: ptyxis --tab
Set the title for a new: ptyxis --tab [-T|--title] title
Specify the working directory for a new tab, window, or command execution: ptyxis [-d|--working-directory] path/to/directory --tab

Synopsis

ptyxis [OPTION]... [-- PROGRAM ARGUMENTS]

ptyxis is a container-oriented terminal, designed for the GNOME desktop. It provides tight integration with podman, toolbox, distrobox, and jhbuild to simplify container-based development and system management.

--version

Show the version of the program.

--preferences

Show the preferences window.

--new-window

Open a new window in an existing instance of Ptyxis. If Ptyxis is not running, a new instance is started.

May be combined with --working-directory and --execute and --title options.

--tab

Open a new tab in the most-recently-used window of an existing Ptyxis instance. If Ptyxis is not running, a new instance is started.

May be combined with --working-directory and --execute and --title options.

-x, --execute

Execute a custom command.

This is similar to using -- to provide the custom command except that the entire command line should be provided as a single argument.

In general, you should use -- instead of this option. This is primarily available to be similar to bash -c 'command'

May be combined with --working-directory and --title options.

-d, --working-directory

Set the current working directory for a new tab [--tab], window [--window], or custom command [-- COMMAND...].

--title=TITLE

Sets the title for a new terminal page created with either --tab or --new-window.

--maximize

Maximize a newly created window.

--fullscreen

Fullscreen a newly created window.

--tab-with-profile=PROFILE

Creates a new tab in an existing instance using the specified profile. The profile should be a UUID string which can be found in the profile editor of the preferences dialog.

-s, --standalone

Start a new instance of Ptyxis, in single instance mode, ignoring any instances already running.

Single instance mode is implied when running a -- command.

-s, --gapplication-app-id=ID

Override the application ID in single instance mode.

-h, --help

Show a summary of options.

Other standard GNOME options not listed here are also supported.

Palette Files

Ptyxis supports custom color palettes defined in INI-style files with a .palette extension. Palette files can be placed in ~/.local/share/org.gnome.Ptyxis/palettes/ to be available in the palette selector.

Palette files use the GKeyFile format (similar to INI files) and must contain at minimum a [Palette] section with a Name key. The palette can define colors in two ways:

Single Scheme: If neither [Light] nor [Dark] sections are present, color keys may be placed directly in the [Palette] section. The same colors will be used for both light and dark themes, with Ptyxis automatically determining which theme to use based on the system color scheme.
Dual Scheme: If both [Light] and [Dark] sections are present, each section defines colors for its respective theme. Both sections must contain the same required color keys.

The [Palette] section supports the following keys:

Name: (Required) The display name of the palette as shown in the palette selector.
Primary: (Optional) Boolean value (true/false). If set to true, marks this palette to be included in the initial set of palettes shown to the user. This is generally used for a limited set of palettes shipped with Ptyxis.
UseSystemAccent: (Optional) Boolean value (true/false). If set to true, the palette will use the system accent color.

Each color scheme section ( [Palette] , [Light] , or [Dark] ) must contain the following required color keys:

Foreground: Text foreground color.
Background: Terminal background color.
Color0: through Color15 The 16 standard terminal colors (0-7 are normal colors, 8-15 are bright colors).

The following color keys are optional and will use computed defaults if omitted:

Cursor: or CursorBackground Cursor background color. If not specified, defaults to the foreground color.
CursorForeground: Cursor foreground color.
TitlebarBackground: Titlebar background color. Defaults to a shaded version of the background.
TitlebarForeground: Titlebar foreground color. Defaults to a shaded version of the foreground.
BellForeground: Visual bell foreground color. Defaults to the titlebar foreground color.
BellBackground: Visual bell background color. Defaults to a mix of Color11 and titlebar background.
SuperuserForeground: Foreground color when running as superuser. Defaults to a shaded version of the titlebar foreground.
SuperuserBackground: Background color when running as superuser. Defaults to a mix of Color1 and the background.
RemoteForeground: Foreground color when connected remotely. Defaults to a shaded version of the titlebar foreground.
RemoteBackground: Background color when connected remotely. Defaults to a mix of Color12 and the background.

All color values must be specified in hexadecimal format, either as #RRGGBB or #RRGGBBAA (with optional alpha channel). For example: #ffffff (white) or #000000ff (black with full opacity).

Example palette file:

[Palette]
Name=My Custom Palette

[Light]
Foreground=#000000
Background=#ffffff
Color0=#000000
Color1=#cc0000
Color2=#00cc00
Color3=#cccc00
Color4=#0000cc
Color5=#cc00cc
Color6=#00cccc
Color7=#cccccc
Color8=#808080
Color9=#ff0000
Color10=#00ff00
Color11=#ffff00
Color12=#0000ff
Color13=#ff00ff
Color14=#00ffff
Color15=#ffffff

[Dark]
Foreground=#ffffff
Background=#000000
Color0=#000000
Color1=#cc0000
Color2=#00cc00
Color3=#cccc00
Color4=#0000cc
Color5=#cc00cc
Color6=#00cccc
Color7=#cccccc
Color8=#808080
Color9=#ff0000
Color10=#00ff00
Color11=#ffff00
Color12=#0000ff
Color13=#ff00ff
Color14=#00ffff
Color15=#ffffff

Bugs

Bug reports can be found and filed at https://gitlab.gnome.org/chergert/ptyxis/issues

Info

16 January 2026