Scroll to navigation

QUICKSHELL(1) User Commands QUICKSHELL(1)

NAME

quickshell - flexible QtQuick-based desktop shell toolkit

SYNOPSIS

quickshell [OPTIONS] [SUBCOMMAND]

DESCRIPTION

Quickshell is a toolkit for building status bars, widgets, lockscreens, and other desktop components using Qt6 and QtQuick. It supports both Wayland and X11, with integrations for PipeWire, MPRIS, system tray, PAM, Bluetooth, and compositor-specific features for Hyprland and Sway/i3. Configuration is done declaratively in QML with live hot-reloading.

OPTIONS

Print help message and exit.
Print quickshell's version and exit.
Exit immediately if another instance of the given config is running.
Detach from the controlling terminal.

Config Selection

Quickshell detects configurations as named directories under each XDG config directory as <xdg dir>/quickshell/<config name>/shell.qml.

If <xdg dir>/quickshell/shell.qml exists, it will be registered as the 'default' configuration, and no subdirectories will be considered. If --config is not passed, 'default' will be assumed.

Alternatively, a config can be selected by path with --path.

Path to a QML file or config folder. Excludes --config and --manifest. Environment variable: QS_CONFIG_PATH.
Name of a quickshell configuration to run. Excludes --path. Environment variable: QS_CONFIG_NAME.
[DEPRECATED] Path to a quickshell manifest. Excludes --path. Environment variable: QS_MANIFEST.

Logging

Disables colored logging. Can also be disabled by setting the NO_COLOR environment variable.
--log-times
Log timestamps with each message.
--log-rules TEXT
Log rules to apply, in the format of QT_LOGGING_RULES.
Increases log verbosity. -v shows INFO level internal logs. -vv shows DEBUG level internal logs.

Debugging

Open the given port (0-65535) for a QML debugger connection.
Wait for a QML debugger to connect before executing the configuration. Requires --debug.

SUBCOMMANDS

Print quickshell logs.
List running quickshell instances.
Kill quickshell instances.
Communicate with other Quickshell instances.
[DEPRECATED] Moved to ipc call.

EXAMPLES

qs
qs -c myconfig
qs -p ~/myshell
qs -p ~/myshell/randomfile.qml

ENVIRONMENT

Path to a QML file or config folder.
Name of a quickshell configuration to run.
If set to a non-empty value, disables colored logging.

SEE ALSO

qs(1)

AUTHORS

Quickshell was written by outfoxxed <outfoxxed@outfoxxed.me>.

2026-02-26 quickshell 0.2.1