Built-in Widgets

AGroupBox

class libqtile.widget.AGroupBox(*args, **kwargs)[source]

A widget that graphically displays the current group

Supported bar orientations: horizontal only

Configuration options

key	default	description
`background`	`None`	Widget background color
`border`	`'000000'`	group box border color
`borderwidth`	`3`	Current group border width
`center_aligned`	`True`	center-aligned group box
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`margin`	`3`	Margin inside the box
`margin_x`	`None`	X Margin. Overrides 'margin' if set
`margin_y`	`None`	Y Margin. Overrides 'margin' if set
`markup`	`False`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`padding_x`	`None`	X Padding. Overrides 'padding' if set
`padding_y`	`None`	Y Padding. Overrides 'padding' if set
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step

Available commands

Click to view the available commands for AGroupBox

Backlight

class libqtile.widget.Backlight(*args, **kwargs)[source]

A simple widget to show the current brightness of a monitor.

If the change_command parameter is set to None, the widget will attempt to use the interface at /sys/class to change brightness. This depends on having the correct udev rules, so be sure Qtile's udev rules are installed correctly.

You can also bind keyboard shortcuts to the backlight widget with:

from libqtile.widget import backlight
Key(
    [],
    "XF86MonBrightnessUp",
    lazy.widget['backlight'].change_backlight(backlight.ChangeDirection.UP)
)
Key(
    [],
    "XF86MonBrightnessDown",
    lazy.widget['backlight'].change_backlight(backlight.ChangeDirection.DOWN)
)

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`backlight_name`	`'QTILE_BACKLIGHT_NOT_FOUND'`	ACPI name of a backlight device
`brightness_file`	`'brightness'`	Name of file with the current brightness in /sys/class/backlight/backlight_name
`change_command`	`'xbacklight -set {0}'`	Execute command to change value
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{percent:2.0%}'`	Display format
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_brightness_file`	`'max_brightness'`	Name of file with the maximum brightness in /sys/class/backlight/backlight_name
`max_chars`	`0`	Maximum number of characters to display in widget.
`min_brightness`	`0`	Minimum brightness percentage
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`step`	`10`	Percent of backlight every scroll changed
`update_interval`	`0.2`	The delay in seconds between updates

Available commands

Click to view the available commands for Backlight

Battery

class libqtile.widget.Battery(*args, **kwargs)[source]

A text-based battery monitoring widget supporting both Linux and FreeBSD.

The Linux version of this widget has functionality to charge "smartly" (i.e. not to 100%) under user defined conditions, and provides some implementations for doing so. For example, to only charge the battery to 90%, use:

Battery(..., charge_controller=lambda: (0, 90))

The battery widget also supplies some charging algorithms. To only charge the battery between 40-50% while connected to a thunderbolt docking station, but 90% all other times, use:

from libqtile.widget.battery import thunderbolt_smart_charge
Battery(..., charge_controller=thunderbolt_smart_charge)

To temporarily disable/re-enable this (e.g. if you know you're going mobile and need to charge) use either:

qtile cmd-obj -o bar top widget battery -f charge_to_full
qtile cmd-obj -o bar top widget battery -f charge_dynamically

or bind a key to:

Key([mod, "shift"], "c", lazy.widget['battery'].charge_to_full())
Key([mod, "shift"], "x", lazy.widget['battery'].charge_dynamically())

note that this functionality requires qtile to be able to write to certain files in sysfs, so make sure that qtile's udev rules are installed correctly.

Supported bar orientations: horizontal and vertical

example	config
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`battery`	`0`	Which battery should be monitored (battery number or name)
`charge_char`	`'^'`	Character to indicate the battery is charging
`charging_background`	`None`	Background color on charging battery. Set to None to disable.
`charging_foreground`	`None`	Font color on charging battery. Set to None to disable.
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`discharge_char`	`'V'`	Character to indicate the battery is discharging
`empty_char`	`'x'`	Character to indicate the battery is empty
`empty_short_text`	`'Empty'`	Short text to indicate battery is empty; see show_short_text
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{char} {percent:2.0%} {hour:d}:{min:02d} {watt:.2f} W'`	Display format
`full_char`	`'='`	Character to indicate the battery is full
`full_short_text`	`'Full'`	Short text to indicate battery is full; see show_short_text
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`hide_threshold`	`None`	Hide the text when there is enough energy 0 <= x < 1
`low_background`	`None`	Background color on low battery
`low_foreground`	`'FF0000'`	Font color on low battery
`low_percentage`	`0.1`	Indicates when to use the low_foreground color 0 < x < 1
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`not_charging_char`	`'*'`	Character to indicate the batter is not charging
`notification_timeout`	`10`	Time in seconds to display notification. 0 for no expiry.
`notify_below`	`None`	Send a notification below this battery level.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`show_short_text`	`True`	Show only characters rather than formatted text when battery is full or empty
`unknown_char`	`'?'`	Character to indicate the battery status is unknown
`update_interval`	`60`	Seconds between status updates

Available commands

Click to view the available commands for Battery

BatteryIcon

class libqtile.widget.BatteryIcon(*args, **kwargs)[source]

Battery life indicator widget.

Supported bar orientations: horizontal only

example	config
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`battery`	`0`	Which battery should be monitored
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`0`	Additional padding either side of the icon
`scale`	`1`	Scale factor relative to the bar height. Defaults to 1
`theme_path`	`'/home/docs/checkouts/readthedocs.org/user_builds/qtile/checkouts/stable/libqtile/resources/battery-icons'`	Path of the icons
`update_interval`	`60`	Seconds between status updates

Available commands

Click to view the available commands for BatteryIcon

Bluetooth

class libqtile.widget.Bluetooth(*args, **kwargs)[source]

Bluetooth widget that provides following functionality: - View multiple adapters/devices (adapters can be filtered) - Set power and discovery status for adapters - Connect/disconnect/pair devices

The widget works by providing a menu in the bar. Different items are accessed by scrolling up and down on the widget.

Clicking on an adapter will open a submenu allowing you to set power and discovery status.

Clicking on a device will perform an action based on the status of that device: - Connected devices will be disconnected - Disconnected devices will be connected - Unpaired devices (which appear if discovery is on) will be paired and connected

Symbols are used to show the status of adapters and devices.

Battery level for bluetooth devices can also be shown if available. This functionality is not available by default on all distros. If it doesn't work, you can try adding Experimental = true to /etc/bluetooth/main.conf.

Supported bar orientations: horizontal and vertical

example	config
	default
	default
	default
	default
	default

Configuration options

key	default	description
`adapter_format`	`'Adapter: {name} [{powered}{discovery}]'`	Text to display when showing adapter device.
`adapter_paths`	`[]`	List of DBus object path for bluetooth adapter (e.g. '/org/bluez/hci0'). Empty list will show all adapters.
`background`	`None`	Widget background color
`default_show_battery`	`False`	Include battery level of 'connected_devices' in 'default_text'. Uses 'device_battery_format'.
`default_text`	`'BT {connected_devices}'`	Text to show when not scrolling through menu. Available fields: 'connected_devices' list of connected devices, 'num_connected_devices' number of connected devices, 'adapters' list of bluetooth adapters, 'num_adapters' number of bluetooth adapters.
`default_timeout`	`None`	Time before reverting to default_text. If 'None', text will stay on selected item.
`device`	`None`	Device path, can be found with d-feet or similar dbus explorer. When set, the widget will default to showing this device status.
`device_battery_format`	`' ({battery}%)'`	Text to be shown if device reports battery level
`device_format`	`'Device: {name}{battery_level} [{symbol}]'`	Text to display when showing bluetooth device. The `{adapter` field is also available if you're using multiple adapters.
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`hide_unnamed_devices`	`False`	Devices with no name will be hidden from scan results
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`separator`	`', '`	Separator for lists in 'default_text'.
`symbol_connected`	`'*'`	Symbol to indicate device is connected
`symbol_discovery`	`('D', '')`	Symbols when adapter is discovering and not discovering
`symbol_paired`	`'-'`	Symbol to indicate device is paired but unconnected
`symbol_powered`	`('*', '-')`	Symbols when adapter is powered and unpowered.
`symbol_unknown`	`'?'`	Symbol to indicate device is unpaired

Available commands

Click to view the available commands for Bluetooth

CPU

class libqtile.widget.CPU(*args, **kwargs)[source]

A simple widget to display CPU load and frequency.

Widget requirements: psutil.

Supported bar orientations: horizontal and vertical

example	config
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'CPU {freq_current}GHz {load_percent}%'`	CPU display format
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`1.0`	Update interval for the CPU widget

Available commands

Click to view the available commands for CPU

CPUGraph

class libqtile.widget.CPUGraph(*args, **kwargs)[source]

Display CPU usage graph.

Widget requirements: psutil.

Supported bar orientations: horizontal only

example	config
	default
	`type='box'`
	`type='line'`
	`type='line', line_width=1`
	`start_pos='top'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`border_color`	`'215578'`	Widget border color
`border_width`	`2`	Widget border width
`core`	`'all'`	Which core to show (all/0/1/2/...)
`fill_color`	`'1667EB.3'`	Fill color for linefill graph
`frequency`	`1`	Update frequency in seconds
`graph_color`	`'18BAEB'`	Graph color
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`line_width`	`3`	Line width
`margin`	`3`	Margin inside the box
`margin_x`	`None`	X Margin. Overrides 'margin' if set
`margin_y`	`None`	Y Margin. Overrides 'margin' if set
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`samples`	`100`	Count of graph samples.
`start_pos`	`'bottom'`	Drawer starting position ('bottom'/'top')
`type`	`'linefill'`	'box', 'line', 'linefill'

Available commands

Click to view the available commands for CPUGraph

Canto

class libqtile.widget.Canto(*args, **kwargs)[source]

Display RSS feeds updates using the canto console reader

Widget requirements: canto

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`all_format`	`'{number}'`	All feeds display format
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`feeds`	`[]`	List of feeds to display, empty for all
`fetch`	`False`	Whether to fetch new items on update
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`one_format`	`'{name}: {number}'`	One feed display format
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.

Available commands

Click to view the available commands for Canto

CapsNumLockIndicator

class libqtile.widget.CapsNumLockIndicator(*args, **kwargs)[source]

Really simple widget to show the current Caps/Num Lock state.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`cmd`	`None`	command line as a string or list of arguments to execute
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse`	`None`	Function to parse output of command
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`shell`	`False`	run command through shell to enable piping and shell expansion
`update_interval`	`0.5`	Update Time in seconds.

Available commands

Click to view the available commands for CapsNumLockIndicator

CheckUpdates

class libqtile.widget.CheckUpdates(*args, **kwargs)[source]

Shows number of pending updates in different unix systems.

The following built-in options are available via the distro parameter:

'Arch' runs ('pacman -Qu', 0)
'Arch_checkupdates' runs ('checkupdates', 0)
'Arch_Sup' runs ('pacman -Sup', 0)
'Arch_paru' runs ('paru -Qu', 0)
'Arch_paru_Sup' runs ('paru -Sup', 0)
'Arch_yay' runs ('yay -Qu', 0)
'Debian' runs ('apt-show-versions -u -b', 0)
'Gentoo_eix' runs ('EIX_LIMIT=0 eix -u# --world', 0)
'Guix' runs ('guix upgrade --dry-run', 0)
'Ubuntu' runs ('aptitude search ~U', 0)
'Fedora' runs ('dnf list --upgrades -q', 1)
'FreeBSD' runs ("pkg upgrade -n | awk '/\t/ { print $0 }'", 0)
'Mandriva' runs ('urpmq --auto-select', 0)
'Void' runs ('xbps-install -nuMS', 0)

Note

It is common for package managers to return a non-zero code when there are no updates. As a result, the widget will treat any error as if there are no updates. If you are using a custom commmand/script, you should therefore ensure that it returns zero when it completes if you wish to see the output of your command.

In addition, as no errors are recorded to the log, if the widget is showing no updates and you believe that to be incorrect, you should run the appropriate command in a terminal to view any error messages.

Supported bar orientations: horizontal and vertical

example	config
	`no_update_string='No updates'`
	`no_update_string='No updates'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`colour_have_updates`	`'ffffff'`	Colour when there are updates.
`colour_no_updates`	`'ffffff'`	Colour when there's no updates.
`custom_command`	`None`	Custom shell command for checking updates (counts the lines of the output)
`custom_command_modify`	`<function CheckUpdates.<lambda> at 0x7ea819c759e0>`	Lambda function to modify line count from custom_command
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`display_format`	`'Updates: {updates}'`	Display format if updates available
`distro`	`'Arch'`	Name of your distribution
`execute`	`None`	Command to execute on click
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`initial_text`	`''`	Draw the widget immediately with an initial text, useful if it takes time to check system updates.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`no_update_string`	`''`	String to display if no updates available
`padding`	`None`	Padding. Calculated if None.
`restart_indicator`	`''`	Indicator to represent reboot is required. (Ubuntu only)
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`60`	Update interval in seconds.

Available commands

Click to view the available commands for CheckUpdates

Chord

class libqtile.widget.Chord(*args, **kwargs)[source]

Display current key chord

Supported bar orientations: horizontal and vertical

example	config
	default
	`chords_colors={'vim mode': ('2980b9', 'ffffff')}`

Configuration options

key	default	description
`background`	`None`	Widget background color
`chords_colors`	`{}`	colors per chord in form of tuple {'chord_name': ('bg', 'fg')}. Where a chord name is not in the dictionary, the default `background` and `foreground` values will be used.
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`name_transform`	`<function Chord.<lambda> at 0x7ea819c75940>`	preprocessor for chord name it is pure function string -> string
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step

Available commands

Click to view the available commands for Chord

Clipboard

class libqtile.widget.Clipboard(*args, **kwargs)[source]

Display current clipboard contents

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`blacklist`	`['keepassx']`	list with blacklisted wm_class, sadly not every clipboard window sets them, keepassx does.Clipboard contents from blacklisted wm_classes will be replaced by the value of `blacklist_text`.
`blacklist_text`	`'***********'`	text to display when the wm_class is blacklisted
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`max_width`	`10`	maximum number of characters to display (None for all, useful when width is bar.STRETCH)
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`selection`	`'CLIPBOARD'`	the selection to display(CLIPBOARD or PRIMARY)
`timeout`	`10`	Default timeout (seconds) for display text, None to keep forever

Available commands

Click to view the available commands for Clipboard

Clock

class libqtile.widget.Clock(*args, **kwargs)[source]

A simple but flexible text-based clock

Supported bar orientations: horizontal and vertical

example	config
	default
	`format='%d/%m/%y %H:%M'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'%H:%M'`	A Python datetime format string
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`timezone`	`None`	The timezone to use for this clock, either as string if pytz or dateutil is installed (e.g. "US/Central" or anything in /usr/share/zoneinfo), or as tzinfo (e.g. datetime.timezone.utc). None means the system local timezone and is the default.
`update_interval`	`1.0`	Update interval for the clock

Available commands

Click to view the available commands for Clock

Cmus

class libqtile.widget.Cmus(*args, **kwargs)[source]

A simple Cmus widget.

Show the metadata of now listening song and allow basic mouse control from the bar:

toggle pause (or play if stopped) on left click;

skip forward in playlist on scroll up;

skip backward in playlist on scroll down.

The following fields (extracted from cmus-remote -C status) are available in the format string:

status: cmus playback status, one of "playing", "paused" or "stopped".
file
position: Current position in [h:]mm:ss.
position_percent: Current position in percent.
remaining: Remaining time in [h:]mm:ss.
remaining_percent: Remaining time in percent.
duration: Total length in [h:]mm:ss.
artist
album
albumartist
composer
comment
date
discnumber
genre
title: Title or filename if no title is available.
tracknumber
stream
status_text: Text indicating the playback status, corresponds to one of playing_text, paused_text or stopped_text.

Cmus (https://cmus.github.io) should be installed.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`cmd`	`None`	command line as a string or list of arguments to execute
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{status_text}{artist} - {title}'`	Format of playback info.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`no_artist_format`	`'{status_text}{title}'`	Format of playback info if no artist available.
`noplay_color`	`''`	DEPRECATED Text colour when paused or stopped.
`padding`	`None`	Padding. Calculated if None.
`parse`	`None`	Function to parse output of command
`paused_color`	`'cecece'`	Text color when paused.
`paused_text`	`'♫ '`	Text to display when paused, if chosen.
`play_color`	`''`	DEPRECATED Text colour when playing.
`play_icon`	`'♫ '`	DEPRECATED Text to display when playing, paused, and stopped, if chosen.
`playing_color`	`'00ff00'`	Text colour when playing.
`playing_text`	`'♫ '`	Text to display when playing, if chosen.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`shell`	`False`	run command through shell to enable piping and shell expansion
`stopped_color`	`'cecece'`	Text color when stopped.
`stopped_text`	`'♫ '`	Text to display when stopped, if chosen.
`stream_format`	`'{status_text}{stream}'`	Format of playback info for streams.
`update_interval`	`0.5`	Update Time in seconds.

Available commands

Click to view the available commands for Cmus

Countdown

class libqtile.widget.Countdown(*args, **kwargs)[source]

A simple countdown timer text widget

Supported bar orientations: horizontal and vertical

example	config
	`date=datetime.datetime(2025, 12, 15, 20, 45, 13, 667348)`

Configuration options

key	default	description
`background`	`None`	Widget background color
`date`	`datetime.datetime(2025, 12, 14, 18, 10, 59, 426966)`	The datetime for the end of the countdown
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{D}d {H}h {M}m {S}s'`	Format of the displayed text. Available variables:{D} == days, {H} == hours, {M} == minutes, {S} seconds.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`1.0`	Update interval in seconds for the clock

Available commands

Click to view the available commands for Countdown

CryptoTicker

class libqtile.widget.CryptoTicker(*args, **kwargs)[source]

A cryptocurrency ticker widget, data provided by the coinbase.com or the binance.com API. Defaults to displaying currency in whatever the current locale is. Examples:

# display the average price of bitcoin in local currency widget.CryptoTicker()

# display it in Euros: widget.CryptoTicker(currency="EUR")

# or a different cryptocurrency! widget.CryptoTicker(crypto="ETH")

# change the currency symbol: widget.CryptoTicker(currency="EUR", symbol="€")

# display from Binance API widget.CryptoTicker(api="binance", currency="USDT")

Widget requirements: aiohttp.

Supported bar orientations: horizontal and vertical

example	config
	default
	`format='{crypto}:{amount:,.2f}'`

Configuration options

key	default	description
`api`	`'coinbase'`	API that provides the data.
`background`	`None`	Widget background color
`crypto`	`'BTC'`	The cryptocurrency to display.
`currency`	`''`	The baseline currency that the value of the crypto is displayed in.
`data`	`None`	Post Data
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{crypto}: {symbol}{amount:.2f}'`	Display string formatting.
`headers`	`{}`	Extra Headers
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`json`	`True`	Is Json?
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse`	`None`	Parse Function
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`symbol`	`''`	The symbol for the baseline currency.
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.
`url`	`None`	Url
`user_agent`	`'Qtile'`	Set the user agent
`xml`	`False`	Is XML?

Available commands

Click to view the available commands for CryptoTicker

CurrentLayout

class libqtile.widget.CurrentLayout(*args, **kwargs)[source]

Display the icon or the name of the current layout of the current group of the screen on which the bar containing the widget is.

If you are using custom layouts, a default icon with question mark will be displayed for them. If you want to use custom icon for your own layout, for example, FooGrid, then create a file named "layout-foogrid.png" and place it in ~/.icons directory. You can as well use other directories, but then you need to specify those directories in custom_icon_paths argument for this plugin.

The widget will look for icons with a png or svg extension.

The order of icon search is:

dirs in custom_icon_paths config argument
~/.icons
built-in qtile icons

Supported bar orientations: horizontal and vertical

example	config
	default
	`mode='icon'`
	`mode='both', icon_first=False`
	`mode='both', icon_first=True`

Configuration options

key	default	description
`background`	`None`	Widget background color
`custom_icon_paths`	`[]`	List of folders where to search icons before using built-in icons or icons in ~/.icons dir. This can also be used to provide missing icons for custom layouts.
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`icon_first`	`True`	When `mode='both'`, the icon will display before the text.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mode`	`'text'`	Display only the name of the layout with `text` or only the icon of the layout with `icon`. Altenatively display the two in order with `both`
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scale`	`1`	Icon's scale factor relative to the bar height.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step

Available commands

Click to view the available commands for CurrentLayout

CurrentScreen

class libqtile.widget.CurrentScreen(*args, **kwargs)[source]

Indicates whether the screen this widget is on is currently active or not

Supported bar orientations: horizontal and vertical

example	config
	default
	default

Configuration options

key	default	description
`active_color`	`'00ff00'`	Color when screen is active
`active_text`	`'A'`	Text displayed when the screen is active
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`inactive_color`	`'ff0000'`	Color when screen is inactive
`inactive_text`	`'I'`	Text displayed when the screen is inactive
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step

Available commands

Click to view the available commands for CurrentScreen

DF

class libqtile.widget.DF(*args, **kwargs)[source]

Disk Free Widget

By default the widget only displays if the space is less than warn_space.

Supported bar orientations: horizontal and vertical

example	config
	`warn_space=40`
	`visible_on_warn=False`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{p} ({uf}{m}\|{r:.0f}%)'`	String format (p: partition, s: size, f: free space, uf: user free space, m: measure, r: ratio (uf/s))
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`measure`	`'G'`	Measurement (G, M, B)
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`partition`	`'/'`	the partition to check space
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`60`	The update interval.
`visible_on_warn`	`True`	Only display if warning
`warn_color`	`'ff0000'`	Warning color
`warn_space`	`2`	Warning space in scale defined by the `measure` option.

Available commands

Click to view the available commands for DF

DoNotDisturb

class libqtile.widget.DoNotDisturb(*args, **kwargs)[source]

Displays Do Not Disturb status for notification server Dunst by default. Can be used with other servers by changing the poll command and mouse callbacks.

Supported bar orientations: horizontal and vertical

example	config
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`disabled_icon`	`'O'`	Icon that displays when do not disturb is disabled
`enabled_icon`	`'X'`	Icon that displays when do not disturb is enabled
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`poll_function`	`None`	Function that returns the notification server status. Define the function on your configuration file and pass it like poll_function=my_func. Must return either true or false
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`1`	How often in seconds the text must update

Available commands

Click to view the available commands for DoNotDisturb

GenPollCommand

class libqtile.widget.GenPollCommand(*args, **kwargs)[source]

A generic text widget to display output from scripts or shell commands

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`cmd`	`None`	command line as a string or list of arguments to execute
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse`	`None`	Function to parse output of command
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`shell`	`False`	run command through shell to enable piping and shell expansion
`update_interval`	`60`	update time in seconds

Available commands

Click to view the available commands for GenPollCommand

GenPollText

class libqtile.widget.GenPollText(*args, **kwargs)[source]

A generic text widget that polls using poll function to get the text

Widget requirements: aiohttp.

Supported bar orientations: horizontal and vertical

example	config
	`func= at 0x732eac7500e0>`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`func`	`None`	Poll Function
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.

Available commands

Click to view the available commands for GenPollText

GenPollUrl

class libqtile.widget.GenPollUrl(*args, **kwargs)[source]

A generic text widget that polls an url and parses it using parse function

Widget requirements: aiohttp.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`data`	`None`	Post Data
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`headers`	`{}`	Extra Headers
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`json`	`True`	Is Json?
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse`	`None`	Parse Function
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.
`url`	`None`	Url
`user_agent`	`'Qtile'`	Set the user agent
`xml`	`False`	Is XML?

Available commands

Click to view the available commands for GenPollUrl

GmailChecker

class libqtile.widget.GmailChecker(*args, **kwargs)[source]

A simple gmail checker. If 'status_only_unseen' is True - set 'fmt' for one argument, ex. 'unseen: {0}'

Supported bar orientations: horizontal and vertical

example	config
	`username='qtile', password='qtile'`
	`username='qtile', password='qtile', display_fmt='unseen[{0}]', status_only_unseen=True`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`display_fmt`	`'inbox[{0}],unseen[{1}]'`	Display format
`email_path`	`'INBOX'`	email_path
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`password`	`None`	password
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`status_only_unseen`	`False`	Only show unseen messages
`update_interval`	`30`	Update time in seconds.
`username`	`None`	username

Available commands

Click to view the available commands for GmailChecker

GroupBox

class libqtile.widget.GroupBox(*args, **kwargs)[source]

A widget that graphically displays the current group. All groups are displayed by their label. If the label of a group is the empty string that group will not be displayed.

Supported bar orientations: horizontal only

example	config
	default
	`highlight_method='block'`
	`highlight_method='text'`
	`highlight_method='line'`
	`visible_groups=['1', '5', '6']`

Configuration options

key	default	description
`active`	`'FFFFFF'`	Active group font colour
`background`	`None`	Widget background color
`block_highlight_text_color`	`None`	Selected group font colour
`borderwidth`	`3`	Current group border width
`center_aligned`	`True`	center-aligned group box
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`disable_drag`	`False`	Disable dragging and dropping of group names on widget
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`hide_unused`	`False`	Hide groups that have no windows and that are not displayed on any screen.
`highlight_color`	`['000000', '282828']`	Active group highlight color when using 'line' highlight method.
`highlight_method`	`'border'`	Method of highlighting ('border', 'block', 'text', or 'line')Uses *_border color settings
`inactive`	`'404040'`	Inactive group font colour
`invert_mouse_wheel`	`False`	Whether to invert mouse wheel group movement
`margin`	`3`	Margin inside the box
`margin_x`	`None`	X Margin. Overrides 'margin' if set
`margin_y`	`None`	Y Margin. Overrides 'margin' if set
`markup`	`False`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`other_current_screen_border`	`'404040'`	Border or line colour for group on other screen when focused.
`other_screen_border`	`'404040'`	Border or line colour for group on other screen when unfocused.
`padding`	`None`	Padding. Calculated if None.
`padding_x`	`None`	X Padding. Overrides 'padding' if set
`padding_y`	`None`	Y Padding. Overrides 'padding' if set
`rotate`	`True`	Rotate text in vertical bar.
`rounded`	`True`	To round or not to round box borders
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`spacing`	`None`	Spacing between groups(if set to None, will be equal to margin_x)
`this_current_screen_border`	`'215578'`	Border or line colour for group on this screen when focused.
`this_screen_border`	`'215578'`	Border or line colour for group on this screen when unfocused.
`toggle`	`True`	Enable toggling of group when clicking on same group name
`urgent_alert_method`	`'border'`	Method for alerting you of WM urgent hints (one of 'border', 'text', 'block', or 'line')
`urgent_border`	`'FF0000'`	Urgent border or line color
`urgent_text`	`'FF0000'`	Urgent group font color
`use_mouse_wheel`	`True`	Whether to use mouse wheel events
`visible_groups`	`None`	Groups that will be visible. If set to None or [], all groups will be visible.Visible groups are identified by name not by their displayed label.

Available commands

Click to view the available commands for GroupBox

HDD

class libqtile.widget.HDD(*args, **kwargs)[source]

Displays HDD usage in percent based on the number of milliseconds the device has been performing I/O operations.

Supported bar orientations: horizontal and vertical

example	config
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`device`	`'sda'`	Block device to monitor (e.g. sda)
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'HDD {HDDPercent}%'`	HDD display format
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.

Available commands

Click to view the available commands for HDD

HDDBusyGraph

class libqtile.widget.HDDBusyGraph(*args, **kwargs)[source]

Display HDD busy time graph

Parses /sys/block/<dev>/stat file and extracts overall device IO usage, based on io_ticks's value. See https://www.kernel.org/doc/Documentation/block/stat.txt

Supported bar orientations: horizontal only

example	config
	default
	`type='box'`
	`type='line'`
	`type='line', line_width=1`
	`start_pos='top'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`border_color`	`'215578'`	Widget border color
`border_width`	`2`	Widget border width
`device`	`'sda'`	Block device to display info for
`fill_color`	`'1667EB.3'`	Fill color for linefill graph
`frequency`	`1`	Update frequency in seconds
`graph_color`	`'18BAEB'`	Graph color
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`line_width`	`3`	Line width
`margin`	`3`	Margin inside the box
`margin_x`	`None`	X Margin. Overrides 'margin' if set
`margin_y`	`None`	Y Margin. Overrides 'margin' if set
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`samples`	`100`	Count of graph samples.
`start_pos`	`'bottom'`	Drawer starting position ('bottom'/'top')
`type`	`'linefill'`	'box', 'line', 'linefill'

Available commands

Click to view the available commands for HDDBusyGraph

HDDGraph

class libqtile.widget.HDDGraph(*args, **kwargs)[source]

Display HDD free or used space graph

Supported bar orientations: horizontal only

example	config
	default
	`type='box'`
	`type='line'`
	`type='line', line_width=1`
	`start_pos='top'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`border_color`	`'215578'`	Widget border color
`border_width`	`2`	Widget border width
`fill_color`	`'1667EB.3'`	Fill color for linefill graph
`frequency`	`1`	Update frequency in seconds
`graph_color`	`'18BAEB'`	Graph color
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`line_width`	`3`	Line width
`margin`	`3`	Margin inside the box
`margin_x`	`None`	X Margin. Overrides 'margin' if set
`margin_y`	`None`	Y Margin. Overrides 'margin' if set
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`path`	`'/'`	Partition mount point.
`samples`	`100`	Count of graph samples.
`space_type`	`'used'`	free/used
`start_pos`	`'bottom'`	Drawer starting position ('bottom'/'top')
`type`	`'linefill'`	'box', 'line', 'linefill'

Available commands

Click to view the available commands for HDDGraph

IdleRPG

class libqtile.widget.IdleRPG(*args, **kwargs)[source]

A widget for monitoring and displaying IdleRPG stats.

# display idlerpg stats for the player 'pants' on freenode's #idlerpg
widget.IdleRPG(url="http://xethron.lolhosting.net/xml.php?player=pants")

Widget requirements: xmltodict.

Supported bar orientations: horizontal and vertical

example	config
	`url='http://idlerpg.qtile.org?player=elParaguayo'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`data`	`None`	Post Data
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'IdleRPG: {online} TTL: {ttl}'`	Display format
`headers`	`{}`	Extra Headers
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`json`	`True`	Is Json?
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse`	`None`	Parse Function
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.
`url`	`None`	Url
`user_agent`	`'Qtile'`	Set the user agent
`xml`	`False`	Is XML?

Available commands

Click to view the available commands for IdleRPG

Image

class libqtile.widget.Image(*args, **kwargs)[source]

Display a PNG image on the bar

Supported bar orientations: horizontal and vertical

example	config
	`filename='/home/docs/checkouts/readthedocs.org/user_builds/qtile/checkouts/stable/test/widgets/docs_screenshots/../../scripts/qtile-logo-blue.svg'`
	`filename='/home/docs/checkouts/readthedocs.org/user_builds/qtile/checkouts/stable/test/widgets/docs_screenshots/../../scripts/qtile-logo-blue.svg', margin=5`
	`filename='/home/docs/checkouts/readthedocs.org/user_builds/qtile/checkouts/stable/test/widgets/docs_screenshots/../../scripts/qtile-logo-blue.svg', rotate=45`

Configuration options

key	default	description
`background`	`None`	Widget background color
`filename`	`None`	Image filename. Can contain '~'
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`margin`	`0`	Margin inside the box. Defaults to 0.
`margin_x`	`None`	X Margin. Overrides 'margin' if set
`margin_y`	`None`	Y Margin. Overrides 'margin' if set
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`rotate`	`0.0`	rotate the image in degrees counter-clockwise
`scale`	`True`	Enable/Disable image scaling

Available commands

Click to view the available commands for Image

ImapWidget

class libqtile.widget.ImapWidget(*args, **kwargs)[source]

Email IMAP widget

This widget will scan one of your imap email boxes and report the number of unseen messages present. I've configured it to only work with imap with ssl. Your password can be obtained from the Gnome Keyring.

Writing your password to the keyring initially is as simple as (changing out <userid> and <password> for your userid and password):

create the file ~/.local/share/python_keyring/keyringrc.cfg with the following contents:

[backend]
default-keyring=keyring.backends.Gnome.Keyring
keyring-path=/home/<userid>/.local/share/keyring/

Execute the following python shell script once:

#!/usr/bin/env python3
import keyring
user = <userid>
password = <password>
keyring.set_password('imapwidget', user, password)

mbox names must include the path to the mbox (except for the default INBOX). So, for example if your mailroot is ~/Maildir, and you want to look at the mailbox at HomeMail/fred, the mbox setting would be: mbox="~/Maildir/HomeMail/fred". Note the nested sets of quotes! Labels can be whatever you choose, of course.

If you want you can give password directly then Gnome Keyring will not be used.

Widget requirements: keyring.

Supported bar orientations: horizontal and vertical

example	config
	`user='qtile'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`hide_no_unseen`	`False`	hide when there are no unseen messages
`label`	`'INBOX: '`	label for display
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mbox`	`'"INBOX"'`	mailbox to fetch
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`password`	`None`	email password
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`server`	`None`	email server name
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.
`user`	`None`	email username

Available commands

Click to view the available commands for ImapWidget

KeyboardKbdd

class libqtile.widget.KeyboardKbdd(*args, **kwargs)[source]

Widget for changing keyboard layouts per window, using kbdd

kbdd should be installed and running, you can get it from: https://github.com/qnikst/kbdd

The widget also requires dbus-fast.

Supported bar orientations: horizontal and vertical

example	config
	`configured_keyboards=['gb', 'us']`

Configuration options

key	default	description
`background`	`None`	Widget background color
`colours`	`None`	foreground colour for each layouteither 'None' or a list of colours.example: ['ffffff', 'E6F0AF'].
`configured_keyboards`	`['us', 'ir']`	your predefined list of keyboard layouts.example: ['us', 'ir', 'es']
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`1`	Update interval in seconds.

Available commands

Click to view the available commands for KeyboardKbdd

KeyboardLayout

class libqtile.widget.KeyboardLayout(*args, **kwargs)[source]

Widget for changing and displaying the current keyboard layout

To use this widget effectively you need to specify keyboard layouts you want to use (using "configured_keyboards") and bind function "next_keyboard" to specific keys in order to change layouts.

For example:

Key([mod], "space", lazy.widget["keyboardlayout"].next_keyboard(), desc="Next keyboard layout."),

When running Qtile with the X11 backend, this widget requires setxkbmap to be available. Xmodmap will also be used if .Xmodmap file is available.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`configured_keyboards`	`['us']`	A list of predefined keyboard layouts represented as strings. For example: ['us', 'us colemak', 'es', 'fr'].
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`display_map`	`{}`	Custom display of layout. Key should be in format 'layout variant'. For example: {'us': 'us', 'lt sgs': 'sgs', 'ru phonetic': 'ru'}
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`option`	`None`	string of setxkbmap option. Ex., 'compose:menu,grp_led:scroll'
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`1`	Update time in seconds.

Available commands

Click to view the available commands for KeyboardLayout

KhalCalendar

class libqtile.widget.KhalCalendar(*args, **kwargs)[source]

Khal calendar widget

This widget will display the next appointment on your Khal calendar in the qtile status bar. Appointments within the "reminder" time will be highlighted.

Widget requirements: dateutil.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'FFFF33'`	default foreground color
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`lookahead`	`7`	days to look ahead in the calendar
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`reminder_color`	`'FF0000'`	color of calendar entries during reminder time
`remindertime`	`10`	reminder time in minutes
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.

Available commands

Click to view the available commands for KhalCalendar

LaunchBar

class libqtile.widget.LaunchBar(*args, **kwargs)[source]

This module defines a widget that displays icons to launch softwares or commands when clicked -- a launchbar. Only png icon files are displayed, not xpm because cairo doesn't support loading of xpm file. The order of displaying (from left to right) is in the order of the list.

If no icon was found for the name provided and if default_icon is set to None then the name is printed instead. If default_icon is defined then this icon is displayed instead.

To execute a software:

('thunderbird', 'thunderbird -safe-mode', 'launch thunderbird in safe mode')

To execute a python command in qtile, begin with by 'qshell:'

('/path/to/icon.png', 'qshell:self.qtile.shutdown()', 'logout from qtile')

Optional requirements: pyxdg for finding the icon path if it is not provided in the progs tuple.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`default_icon`	`'/usr/share/icons/oxygen/256x256/mimetypes/application-x-executable.png'`	Default icon not found
`font`	`'sans'`	Text font
`fontshadow`	`None`	Font shadow color, default is None (no shadow)
`fontsize`	`None`	Font pixel size. Calculated if None.
`foreground`	`'#ffffff'`	Text colour.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`icon_size`	`None`	Size of icons. `None` to fit to bar.
`markup`	`False`	Whether to allow markup in text label.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`2`	Padding between icons
`progs`	`[]`	A list of tuples (software_name or icon_path, command_to_execute, comment), for example: [('thunderbird', 'thunderbird -safe-mode', 'launch thunderbird in safe mode'), ('/path/to/icon.png', 'qshell:self.qtile.shutdown()', 'logout from qtile')]
`text_only`	`False`	Don't use any icons.
`theme_path`	`None`	Path to icon theme to be used by pyxdg for icons. `None` will use default icon theme.

Available commands

Click to view the available commands for LaunchBar

Load

class libqtile.widget.Load(*args, **kwargs)[source]

A small widget to show the load averages of the system. Depends on psutil.

Supported bar orientations: horizontal and vertical

example	config
	default
	`format='{time}: {load:.1f}'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'Load({time}):{load:.2f}'`	The format in which to display the results.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`1.0`	The update interval for the widget

Available commands

Click to view the available commands for Load

Maildir

class libqtile.widget.Maildir(*args, **kwargs)[source]

A simple widget showing the number of new mails in maildir mailboxes

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`empty_color`	`None`	Display color when no new mail is available
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`hide_when_empty`	`False`	Whether not to display anything if the subfolder has no new mail
`maildir_path`	`'~/Mail'`	path to the Maildir folder
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`nonempty_color`	`None`	Display color when new mail is available
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`separator`	`' '`	the string to put between the subfolder strings.
`sub_folders`	`[{'label': 'Home mail', 'path': 'INBOX'}, {'label': 'Home junk', 'path': 'spam'}]`	List of subfolders to scan. Each subfolder is a dict of path and label.
`subfolder_fmt`	`'{label}: {value}'`	Display format for one subfolder
`total`	`False`	Whether or not to sum subfolders into a grand total. The first label will be used.
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.

Available commands

Click to view the available commands for Maildir

Memory

class libqtile.widget.Memory(*args, **kwargs)[source]

Display memory/swap usage.

The following fields are available in the format string:

MemUsed: Memory in use.
MemTotal: Total amount of memory.
MemFree: Amount of memory free.
Available: Amount of memory available.
NotAvailable: Equal to MemTotal - MemAvailable
MemPercent: Memory in use as a percentage.
Buffers: Buffer amount.
Active: Active memory.
Inactive: Inactive memory.
Shmem: Shared memory.
SwapTotal: Total amount of swap.
SwapFree: Amount of swap free.
SwapUsed: Amount of swap in use.
SwapPercent: Swap in use as a percentage.
mm: Measure unit for memory.
ms: Measure unit for swap.

Widget requirements: psutil.

Supported bar orientations: horizontal and vertical

example	config
	default
	`measure_mem='G'`
	`format='Swap: {SwapUsed: .0f}{ms}/{SwapTotal: .0f}{ms}'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{MemUsed: .0f}{mm}/{MemTotal: .0f}{mm}'`	Formatting for field names.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`measure_mem`	`'M'`	Measurement for Memory (G, M, K, B)
`measure_swap`	`'M'`	Measurement for Swap (G, M, K, B)
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`1.0`	Update interval for the Memory

Available commands

Click to view the available commands for Memory

MemoryGraph

class libqtile.widget.MemoryGraph(*args, **kwargs)[source]

Displays a memory usage graph.

Widget requirements: psutil.

Supported bar orientations: horizontal only

example	config
	default
	`type='box'`
	`type='line'`
	`type='line', line_width=1`
	`start_pos='top'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`border_color`	`'215578'`	Widget border color
`border_width`	`2`	Widget border width
`fill_color`	`'1667EB.3'`	Fill color for linefill graph
`frequency`	`1`	Update frequency in seconds
`graph_color`	`'18BAEB'`	Graph color
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`line_width`	`3`	Line width
`margin`	`3`	Margin inside the box
`margin_x`	`None`	X Margin. Overrides 'margin' if set
`margin_y`	`None`	Y Margin. Overrides 'margin' if set
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`samples`	`100`	Count of graph samples.
`start_pos`	`'bottom'`	Drawer starting position ('bottom'/'top')
`type`	`'linefill'`	'box', 'line', 'linefill'

Available commands

Click to view the available commands for MemoryGraph

Moc

class libqtile.widget.Moc(*args, **kwargs)[source]

A simple MOC widget.

Show the artist and album of now listening song and allow basic mouse control from the bar:

toggle pause (or play if stopped) on left click;
skip forward in playlist on scroll up;
skip backward in playlist on scroll down.

MOC (http://moc.daper.net) should be installed.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`cmd`	`None`	command line as a string or list of arguments to execute
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`noplay_color`	`'cecece'`	Text colour when not playing.
`padding`	`None`	Padding. Calculated if None.
`parse`	`None`	Function to parse output of command
`play_color`	`'00ff00'`	Text colour when playing.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`shell`	`False`	run command through shell to enable piping and shell expansion
`update_interval`	`0.5`	Update Time in seconds.

Available commands

Click to view the available commands for Moc

Mpd2

class libqtile.widget.Mpd2(*args, **kwargs)[source]

Mpd2 Object.

Parameters:

status_format:

format string to display status

For a full list of values, see:: MPDClient.status() and MPDClient.currentsong()

https://musicpd.org/doc/protocol/command_reference.html#command_status https://musicpd.org/doc/protocol/tags.html

Default:

'{play_status} {artist}/{title} \
    [{repeat}{random}{single}{consume}{updating_db}]'

``play_status`` is a string from ``play_states`` dict

Note that the ``time`` property of the song renamed to ``fulltime``
to prevent conflicts with status information during formating.

idle_format:

format string to display status when no song is in queue.

Default:

'{play_status} {idle_message} \
    [{repeat}{random}{single}{consume}{updating_db}]'

Note that the ``artist`` key fallbacks to similar keys in specific order.
(``artist`` -> ``albumartist`` -> ``performer`` ->
 -> ``composer`` -> ``conductor`` -> ``ensemble``)

idle_message:

text to display instead of song information when MPD is idle. (i.e. no song in queue)

Default:: "MPD IDLE"

undefined_value:

text to display when status key is undefined

Default:: "Undefined"

prepare_status:

dict of functions to replace values in status with custom characters.

f(status, key, space_element) => str

New functionality allows use of a dictionary of plain strings.

Default:

status_dict = {
    'repeat': 'r',
    'random': 'z',
    'single': '1',
    'consume': 'c',
    'updating_db': 'U'
}

format_fns:

A dict of functions to format the various elements.

'Tag': f(str) => str

Default:: { 'all': lambda s: cgi.escape(s) }

N.B. if 'all' is present, it is processed on every element of song_info: before any other formatting is done.

mouse_buttons:

A dict of mouse button numbers to actions

Widget requirements: python-mpd2_.

.. _python-mpd2: https://pypi.org/project/python-mpd2/

Supported bar orientations: horizontal and vertical

example	config
	default
	`status_format='{play_status} {artist}/{title}'`
	`idle_format='{play_status} {idle_message}', idle_message='MPD not playing'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`color_progress`	`None`	Text color to indicate track progress.
`command`	`<function default_cmd at 0x7ea819888f40>`	command to be executed by mapped mouse button.
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format_fns`	`{'all': <function escape at 0x7ea81cf56ac0>}`	Dictionary of format methods
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`host`	`'localhost'`	Host of mpd server
`idle_format`	`'{play_status} {idle_message}[{repeat}{random}{single}{consume}{updating_db}]'`	format for status when mpd has no playlist.
`idle_message`	`'MPD IDLE'`	text to display when mpd is idle.
`idletimeout`	`5`	MPDClient idle command timeout
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_buttons`	`{1: 'toggle', 3: 'stop', 4: 'previous', 5: 'next'}`	b_num -> action.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`no_connection`	`'No connection'`	Text when mpd is disconnected
`padding`	`None`	Padding. Calculated if None.
`password`	`None`	Password for auth on mpd server
`play_states`	`{'pause': '⏸', 'play': '▶', 'stop': '■'}`	Play state mapping
`port`	`6600`	Port of mpd server
`prepare_status`	`{'consume': 'c', 'random': 'z', 'repeat': 'r', 'single': '1', 'updating_db': 'U'}`	characters to show the status of MPD
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`space`	`'-'`	Space keeper
`status_format`	`'{play_status} {artist}/{title} [{repeat}{random}{single}{consume}{updating_db}]'`	format for displayed song info.
`timeout`	`30`	MPDClient timeout
`undefined_value`	`'Undefined'`	text to display when status key is undefined.
`update_interval`	`1`	Interval of update widget

Available commands

Click to view the available commands for Mpd2

Mpris2

class libqtile.widget.Mpris2(*args, **kwargs)[source]

An MPRIS 2 widget

A widget which displays the current track/artist of your favorite MPRIS player. This widget scrolls the text if neccessary and information that is displayed is configurable.

The widget relies on players broadcasting signals when the metadata or playback status changes. If you are getting inconsistent results then you can enable background polling of the player by setting the poll_interval parameter. This is disabled by default.

Basic mouse controls are also available: button 1 = play/pause, scroll up = next track, scroll down = previous track.

Widget requirements: dbus-fast.

Supported bar orientations: horizontal and vertical

example	config
	default
	`scroll_chars=45`
	`display_metadata=['xesam:url']`
	`stop_pause_text='Player paused'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`display_metadata`	`['xesam:title', 'xesam:album', 'xesam:artist']`	(Deprecated) Which metadata identifiers to display.
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{xesam:title} - {xesam:album} - {xesam:artist}'`	Format string for displaying metadata. See http://www.freedesktop.org/wiki/Specifications/mpris-spec/metadata/#index5h3 for available values. The special filed '{qtile:player}' can be used to display the player name.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`name`	`'audacious'`	Name of the MPRIS widget.
`no_metadata_text`	`'No metadata for current track'`	Text to show when track has no metadata
`objname`	`None`	DBUS MPRIS 2 compatible player identifier- Find it out with dbus-monitor - Also see: http://specifications.freedesktop.org/mpris-spec/latest/#Bus-Name-Policy. `None` will listen for notifications from all MPRIS2 compatible players.
`padding`	`None`	Padding. Calculated if None.
`paused_text`	`'Paused: {track}'`	Text to show when paused
`playing_text`	`'{track}'`	Text to show when playing
`poll_interval`	`0`	Periodic background polling interval of player (0 to disable polling).
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`True`	Whether text should scroll.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`separator`	`', '`	Separator for metadata fields that are a list.
`stop_pause_text`	`None`	(Deprecated) Optional text to display when in the stopped/paused state
`stopped_text`	`''`	Text to show when stopped

Available commands

Click to view the available commands for Mpris2

Net

class libqtile.widget.Net(*args, **kwargs)[source]

Displays interface down and up speed

The following fields are available in the format string:

interface: name of the interface
down: download speed
down_suffix: suffix for the download speed
down_cumulative: cumulative download traffic
down_cumulative_suffix: suffix for the cumulative download traffic
up: upload speed
up_suffix: suffix for the upload speed
up_cumulative: cumulative upload traffic
up_cumulative_suffix: suffix for the cumulative upload traffic
total: total speed
total_suffix: suffix for the total speed
total_cumulative: cumulative total traffic
total_cumulative_suffix: suffix for the cumulative total traffic

Widget requirements: psutil.

Supported bar orientations: horizontal and vertical

example	config
	default
	`format='{interface}: U {up} D {down} T {total}'`
	`format='{interface}: U {up}{up_suffix} D {down}{down_suffix} T {total}{total_suffix}'`
	`format='{down:.0f}{down_suffix} ↓↑ {up:.0f}{up_suffix}'`
	`interface='wlp58s0'`
	`prefix='M'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`cumulative_prefix`	`None`	Use a specific prefix for the unit of the cumulative traffic.
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{interface}: {down:6.2f}{down_suffix:<2}↓↑{up:6.2f}{up_suffix:<2}'`	Display format of down/upload/total speed of given interfaces
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`interface`	`None`	List of interfaces or single NIC as string to monitor, None to display all active NICs combined
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`prefix`	`None`	Use a specific prefix for the unit of the speed.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`1`	The update interval.
`use_bits`	`False`	Use bits instead of bytes per second?

Available commands

Click to view the available commands for Net

NetGraph

class libqtile.widget.NetGraph(*args, **kwargs)[source]

Display a network usage graph.

Widget requirements: psutil.

Supported bar orientations: horizontal only

example	config
	default
	`type='box'`
	`type='line'`
	`type='line', line_width=1`
	`start_pos='top'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`bandwidth_type`	`'down'`	down(load)/up(load)
`border_color`	`'215578'`	Widget border color
`border_width`	`2`	Widget border width
`fill_color`	`'1667EB.3'`	Fill color for linefill graph
`frequency`	`1`	Update frequency in seconds
`graph_color`	`'18BAEB'`	Graph color
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`interface`	`'auto'`	Interface to display info for ('auto' for detection)
`line_width`	`3`	Line width
`margin`	`3`	Margin inside the box
`margin_x`	`None`	X Margin. Overrides 'margin' if set
`margin_y`	`None`	Y Margin. Overrides 'margin' if set
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`samples`	`100`	Count of graph samples.
`start_pos`	`'bottom'`	Drawer starting position ('bottom'/'top')
`type`	`'linefill'`	'box', 'line', 'linefill'

Available commands

Click to view the available commands for NetGraph

NetUP

class libqtile.widget.NetUP(*args, **kwargs)[source]

A widget to display whether the network connection is up or down by probing a host via ping or tcp connection.

By default host parameter is set to None.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`display_fmt`	`'NET {0}'`	Display format.
`down_foreground`	`'FF0000'`	Font color when host is down.
`down_string`	`'down'`	String to display when host is down.
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`host`	`None`	Host to probe.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`method`	`'ping'`	tcp or ping.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`port`	`443`	TCP port.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`up_foreground`	`'FFFFFF'`	Font color when host is up.
`up_string`	`'up'`	String to display when host is up.
`update_interval`	`30`	Update interval in seconds.

Available commands

Click to view the available commands for NetUP

Notify

class libqtile.widget.Notify(*args, **kwargs)[source]

A notify widget

This widget can handle actions provided by notification clients. However, only the default action is supported, so if a client provides multiple actions then only the default (first) action can be invoked. Some programs will provide their own notification windows if the notification server does not support actions, so if you want your notifications to handle more than one action then specify False for the action option to disable all action handling. Unfortunately we cannot specify the capability for exactly one action.

Supported bar orientations: horizontal and vertical

example	config
	default

Configuration options

key	default	description
`action`	`True`	Enable handling of default action upon right click
`audiofile`	`None`	Audiofile played during notifications
`background`	`None`	Widget background color
`background_low`	`'444444'`	Background low priority colour
`background_urgent`	`'440000'`	Background urgent priority colour
`default_timeout`	`10`	Default timeout (seconds) for normal notifications
`default_timeout_low`	`5`	Default timeout (seconds) for low urgency notifications.
`default_timeout_urgent`	`None`	Default timeout (seconds) for urgent notifications
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`foreground_low`	`'dddddd'`	Foreground low priority colour
`foreground_urgent`	`'ff0000'`	Foreground urgent priority colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse_text`	`None`	Function to parse and modify notifications. e.g. function in config that removes line returns:def my_func(text) return text.replace('n', '')then set option parse_text=my_func
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step

Available commands

Click to view the available commands for Notify

NvidiaSensors

class libqtile.widget.NvidiaSensors(*args, **kwargs)[source]

Displays temperature, fan speed and performance level Nvidia GPU.

Supported bar orientations: horizontal and vertical

example	config
	default
	`threshold=60, foreground_alert='ff6000'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`foreground_alert`	`'ff0000'`	Foreground colour alert
`format`	`'{temp}°C'`	Display string format. Three options available: `{temp}` - temperature, `{fan_speed}` and `{perf}` - performance level
`gpu_bus_id`	`''`	GPU's Bus ID, ex: `01:00.0`. If leave empty will display all available GPU's
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`threshold`	`70`	If the current temperature value is above, then change to foreground_alert colour
`update_interval`	`2`	Update interval in seconds.

Available commands

Click to view the available commands for NvidiaSensors

OpenWeather

class libqtile.widget.OpenWeather(*args, **kwargs)[source]

A weather widget, data provided by the OpenWeather API.

Some format options:

location_city
location_cityid
location_country
location_lat
location_long
weather
weather_details
units_temperature
units_wind_speed
isotime
humidity
pressure
sunrise
sunset
temp
visibility
wind_speed
wind_deg
wind_direction
main_feels_like
main_temp_min
main_temp_max
clouds_all
icon

Icon support is available but you will need a suitable font installed. A default icon mapping is provided (OpenWeather.symbols) but changes can be made by setting weather_symbols. Available icon codes can be viewed here: https://openweathermap.org/weather-conditions#Icon-list

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`app_key`	`'7834197c2338888258f8cb94ae14ef49'`	Open Weather access key. A default is provided, butn for prolonged use obtaining your own is suggested:n https://home.openweathermap.org/users/sign_up
`background`	`None`	Widget background color
`cityid`	`None`	City ID. Can be looked up on e.g.:n https://openweathermap.org/findn Takes precedence over location and coordinates.n Note that this is not equal to a WOEID.
`coordinates`	`None`	Dictionary containing latitude and longituden Example: coordinates={"longitude": "77.22",n "latitude": "28.67"}
`data`	`None`	Post Data
`dateformat`	`'%Y-%m-%d '`	Format for dates, defaults to ISO.n For details see: https://docs.python.org/3/library/time.html#time.strftime
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{location_city}: {main_temp} °{units_temperature} {humidity}% {weather_details}'`	Display format
`headers`	`{}`	Extra Headers
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`json`	`True`	Is Json?
`language`	`'en'`	Language of response. List of languages supported cann be seen at: https://openweathermap.org/current undern Multilingual support
`location`	`None`	Name of the city. Country name can be appendedn like cambridge,NZ. Takes precedence over zip-code.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`metric`	`True`	True to use metric/C, False to use imperial/F
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse`	`None`	Parse Function
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`timeformat`	`'%H:%M'`	Format for times, defaults to ISO.n For details see: https://docs.python.org/3/library/time.html#time.strftime
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.
`url`	`None`	Url
`user_agent`	`'Qtile'`	Set the user agent
`weather_symbols`	`{}`	Dictionary of weather symbols. Can be used to override default symbols.
`xml`	`False`	Is XML?
`zip`	`None`	Zip code (USA) or "zip code,country code" forn other countries. E.g. 12345,NZ. Takes precedence overn coordinates.

Available commands

Click to view the available commands for OpenWeather

Plasma

class libqtile.widget.Plasma(*args, **kwargs)[source]

A simple widget to indicate in which direction new windows will be added in the Plasma layout.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{mode:>2}'`	Format appearance of text
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`horizontal`	`'H'`	Text to display if horizontal mode
`horizontal_split`	`None`	Text to display for horizontal split mode
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`split`	`'S'`	Text to append to mode if `horizontal/vertical_split` not set
`vertical`	`'V'`	Text to display if horizontal mode
`vertical_split`	`None`	Text to display for horizontal split mode

Available commands

Click to view the available commands for Plasma

Pomodoro

class libqtile.widget.Pomodoro(*args, **kwargs)[source]

Pomodoro technique widget

Supported bar orientations: horizontal and vertical

example	config
	default
	default
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`color_active`	`'00ff00'`	Colour then pomodoro is running
`color_break`	`'ffff00'`	Colour then it is break time
`color_inactive`	`'ff0000'`	Colour then pomodoro is inactive
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`length_long_break`	`15`	Length of a long break in minutes
`length_pomodori`	`25`	Length of one pomodori in minutes
`length_short_break`	`5`	Length of a short break in minutes
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`notification_on`	`True`	Turn notifications on
`num_pomodori`	`4`	Number of pomodori to do in a cycle
`padding`	`None`	Padding. Calculated if None.
`prefix_active`	`''`	Prefix then app is active
`prefix_break`	`'B '`	Prefix during short break
`prefix_inactive`	`'POMODORO'`	Prefix when app is inactive
`prefix_long_break`	`'LB '`	Prefix during long break
`prefix_paused`	`'PAUSE'`	Prefix during pause
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`1`	Update interval in seconds, if none, the widget updates whenever the event loop is idle.

Available commands

Click to view the available commands for Pomodoro

Prompt

class libqtile.widget.Prompt(*args, **kwargs)[source]

A widget that prompts for user input

Input should be started using the .start_input() method on this class.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`bell_style`	`'audible'`	Alert at the begin/end of the command history. Possible values: 'audible' (X11 only), 'visual' and None.
`cursor`	`True`	Show a cursor
`cursor_color`	`'bef098'`	Color for the cursor and text over it.
`cursorblink`	`0.5`	Cursor blink rate. 0 to disable.
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`ignore_dups_history`	`False`	Don't store duplicates in history
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`max_history`	`100`	Commands to keep in history. 0 for no limit.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`prompt`	`'{prompt}: '`	Text displayed at the prompt
`record_history`	`True`	Keep a record of executed commands
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`visual_bell_color`	`'ff0000'`	Color for the visual bell (changes prompt background).
`visual_bell_time`	`0.2`	Visual bell duration (in seconds).

Available commands

Click to view the available commands for Prompt

PulseVolume

class libqtile.widget.PulseVolume(*args, **kwargs)[source]

Volume widget for systems using PulseAudio.

The widget connects to the PulseAudio server by using the libpulse library and so should be updated virtually instantly rather than needing to poll the volume status regularly (NB this means that the update_interval parameter serves no purpose for this widget).

The widget relies on the pulsectl_asyncio library to access the libpulse bindings. If you are using python 3.11 you must use pulsectl_asyncio >= 1.0.0.

Supported bar orientations: horizontal only

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`emoji`	`False`	Use emoji to display volume states, only if `theme_path` is not set.The specified font needs to contain the correct unicode characters.
`emoji_list`	`['🔇', '🔈', '🔉', '🔊']`	List of emojis/font-symbols to display volume states, only if `emoji` is set. List contains 4 symbols, from lowest volume to highest.
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`limit_max_volume`	`False`	Limit maximum volume to 100%
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`mute_foreground`	`None`	Foreground color for mute volume.
`mute_format`	`'M'`	Format to display when volume is muted.
`padding`	`3`	Padding left and right. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`step`	`2`	Volume change for up an down commands in percentage.Only used if `volume_up_command` and `volume_down_command` are not set.
`theme_path`	`None`	Path of the icons
`unmute_format`	`'{volume}%'`	Format of text to display when volume is not muted.

Available commands

Click to view the available commands for PulseVolume

QuickExit

class libqtile.widget.QuickExit(*args, **kwargs)[source]

A button to shut down Qtile. When clicked, a countdown starts. Clicking the button again stops the countdown and prevents Qtile from shutting down.

Supported bar orientations: horizontal and vertical

example	config
	default
	default
	`default_text='[X]', countdown_format='[{}]'`
	`default_text='[X]', countdown_format='[{}]'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`countdown_format`	`'[ {} seconds ]'`	The text displayed when counting down.
`countdown_start`	`5`	The number to count down from.
`default_text`	`'[ shutdown ]'`	The text displayed on the button.
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`timer_interval`	`1`	The countdown interval.

Available commands

Click to view the available commands for QuickExit

Redshift

class libqtile.widget.Redshift(*args, **kwargs)[source]

Redshift widget provides the following functionality:

Call redshift with a specific brightness, temperature and gamma config without using your location.
Increase/Decrease the brightness/temperature

The redshift command can be called by just left-clicking the widget and disabling it the same way.

If the widget is enabled, scrolling through the widget will show the settings: - brightness (limited to 2 dp) - gamma (can't be increased/decreased) - temperature (limited to 2 dp) - finally back to the default enabled/disabled text

When at the temperature/brightness settings, the left-click/right-click mouse buttons can be used to increase/decrease respectively.

Widget requirements: redshift

Supported bar orientations: horizontal and vertical

Only available on the following backends: x11

example	config
	default
	default
	default
	default
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`brightness`	`1.0`	Redshift brightness. Brightness has a lower bound of 0.1 and an upper bound of 1.0
`brightness_fmt`	`'Brightness: {brightness}'`	Text to display when showing brightness text. Available fields: 'brightness' brightness to set when redshift is enabled.
`brightness_step`	`0.1`	The amount to increase/decrease the brightness by.
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`disabled_txt`	`'\U000f1803'`	Text to show when redshift is disabled. NOTE: by default, a nerd icon is used. Available fields: 'brightness' brightness to set when redshift is enabled, 'is_enabled' boolean to state whether the widget is enabled or not, 'gamma_blue' gamma blue value to set when redshift is enabled, 'gamma_green' gamma green value to set when redshift is enabled, 'gamma_red' gamma red value to set when redshift is enabled, 'temperature' temperature to set when redshift is enabled,
`enabled_txt`	`'\U000f06e8'`	Text to show when redshift is disabled. NOTE: by default, a nerd icon is used. Available fields: see disabled_txt's available fields for all of them
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`20`	Font size
`foreground`	`'ffffff'`	Font colour for information text
`gamma_blue`	`1.0`	Redshift gamma blue. gamma_blue has a lower bound of 0.1 and an upper bound of 10.0 .
`gamma_fmt`	`'Gamma: {gamma_red}:{gamma_green}:{gamma_blue}'`	Text to display when showing gamma text. Available fields: 'gamma_red' gamma red value to set when redshift is enabled, 'gamma_blue' gamma blue value to set when redshift is enabled, 'gamma_green' gamma green value to set when redshift is enabled.
`gamma_green`	`1.0`	Redshift gamma green. gamma_green has a lower bound of 0.1 and an upper bound of 10.0 .
`gamma_red`	`1.0`	Redshift gamma red setting. gamma_red has a lower bound of 0.1 and an upper bound of 10.0 .
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`redshift_path`	`None`	Path to redshift executable
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`temperature`	`1700`	Redshift temperature to set when enabled. Temperature has a lower bound of 1000 and an upper bound of 25000.
`temperature_fmt`	`'Temperature: {temperature}'`	Text to display when showing temperature text. Available fields: 'temperature' temperature to set when redshift is enabled.
`temperature_step`	`100`	The amount to increase/decrease the temperature by.

Available commands

Click to view the available commands for Redshift

ScreenSplit

class libqtile.widget.ScreenSplit(*args, **kwargs)[source]

A simple widget to show the name of the current split and layout for the ScreenSplit layout.

Supported bar orientations: horizontal and vertical

example	config
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Text font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font pixel size. Calculated if None.
`foreground`	`'#ffffff'`	Foreground colour.
`format`	`'{split_name} ({layout})'`	Format string.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding left and right. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step

Available commands

Click to view the available commands for ScreenSplit

Sep

class libqtile.widget.Sep(*args, **kwargs)[source]

A visible widget separator

Supported bar orientations: horizontal and vertical

example	config
	default
	`padding=10, linewidth=5, size_percent=50`

Configuration options

key	default	description
`background`	`None`	Widget background color
`foreground`	`'888888'`	Separator line colour.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`linewidth`	`1`	Width of separator line.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`2`	Padding on either side of separator.
`size_percent`	`80`	Size as a percentage of bar size (0-100).

Available commands

Click to view the available commands for Sep

She

class libqtile.widget.She(*args, **kwargs)[source]

Widget to display the Super Hybrid Engine status

Can display either the mode or CPU speed on eeepc computers.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`device`	`'/sys/devices/platform/eeepc/cpufv'`	sys path to cpufv
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'speed'`	Type of info to display "speed" or "name"
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`0.5`	Update Time in seconds.

Available commands

Click to view the available commands for She

Spacer

class libqtile.widget.Spacer(*args, **kwargs)[source]

Just an empty space on the bar

Often used with length equal to bar.STRETCH to push bar widgets to the right or bottom edge of the screen.

Parameters:

length: Length of the widget. Can be either bar.STRETCH or a length in pixels.
width: DEPRECATED, same as length.

Supported bar orientations: horizontal and vertical

example	config
	default
	`length=50`

Configuration options

key	default	description
`background`	`None`	Widget background color
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.

Available commands

Click to view the available commands for Spacer

StatusNotifier

class libqtile.widget.StatusNotifier(*args, **kwargs)[source]

A 'system tray' widget using the freedesktop StatusNotifierItem specification.

As per the specification, app icons are first retrieved from the user's current theme. If this is not available then the app may provide its own icon. In order to use this functionality, users are recommended to install the pyxdg module to support retrieving icons from the selected theme. If the icon specified by StatusNotifierItem can not be found in the user's current theme and no other icons are provided by the app, a fallback icon is used.

Left-clicking an icon will trigger an activate event.

Note

Context menus are not currently supported by the official widget. However, a modded version of the widget which provides basic menu support is available from elParaguayo's qtile-extras repo.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`icon_size`	`16`	Icon width
`icon_theme`	`None`	Name of theme to use for app icons
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`3`	Padding between icons

Available commands

Click to view the available commands for StatusNotifier

StockTicker

class libqtile.widget.StockTicker(*args, **kwargs)[source]

A stock ticker widget, based on the alphavantage API. Users must acquire an API key from https://www.alphavantage.co/support/#api-key

The widget defaults to the TIME_SERIES_INTRADAY API function (i.e. stock symbols), but arbitrary Alpha Vantage API queries can be made by passing extra arguments to the constructor.

# Display AMZN
widget.StockTicker(apikey=..., symbol="AMZN")

# Display BTC
widget.StockTicker(
    apikey=..., function="DIGITAL_CURRENCY_INTRADAY", symbol="BTC", market="USD"
)

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`data`	`None`	Post Data
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`func`	`'TIME_SERIES_INTRADAY'`	The default API function to query
`function`	`'TIME_SERIES_INTRADAY'`	DEPRECATED: Use func.
`headers`	`{}`	Extra Headers
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`interval`	`'1min'`	The default latency to query
`json`	`True`	Is Json?
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse`	`None`	Parse Function
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.
`url`	`None`	Url
`user_agent`	`'Qtile'`	Set the user agent
`xml`	`False`	Is XML?

Available commands

Click to view the available commands for StockTicker

SwapGraph

class libqtile.widget.SwapGraph(*args, **kwargs)[source]

Display a swap info graph.

Widget requirements: psutil.

Supported bar orientations: horizontal only

example	config
	default
	`type='box'`
	`type='line'`
	`type='line', line_width=1`
	`start_pos='top'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`border_color`	`'215578'`	Widget border color
`border_width`	`2`	Widget border width
`fill_color`	`'1667EB.3'`	Fill color for linefill graph
`frequency`	`1`	Update frequency in seconds
`graph_color`	`'18BAEB'`	Graph color
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`line_width`	`3`	Line width
`margin`	`3`	Margin inside the box
`margin_x`	`None`	X Margin. Overrides 'margin' if set
`margin_y`	`None`	Y Margin. Overrides 'margin' if set
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`samples`	`100`	Count of graph samples.
`start_pos`	`'bottom'`	Drawer starting position ('bottom'/'top')
`type`	`'linefill'`	'box', 'line', 'linefill'

Available commands

Click to view the available commands for SwapGraph

SwayNC

class libqtile.widget.SwayNC(*args, **kwargs)[source]

A simple widget for the Sway Notification Center.

The widget can display the number of notifications as well as the do not disturb status.

Left-clicking on the widget will toggle the panel. Right-clicking will toggle the do not disturb status.

Supported bar orientations: horizontal and vertical

Only available on the following backends: wayland

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`dnd_status_text`	`('DND ', '')`	Text to show do-not-disturb status. Tuple of text ('on', 'off').
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{dnd}{num}'`	Text to display.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`swaync_client`	`None`	Command to execute.

Available commands

Click to view the available commands for SwayNC

Systray

class libqtile.widget.Systray(*args, **kwargs)[source]

A widget that manages system tray.

Only one Systray widget is allowed. Adding additional Systray widgets will result in a ConfigError.

Note

Icons will not render correctly where the bar/widget is drawn with a semi-transparent background. Instead, icons will be drawn with a transparent background.

If using this widget it is therefore recommended to use a fully opaque background colour or a fully transparent one.

Supported bar orientations: horizontal and vertical

Only available on the following backends: x11

Configuration options

key	default	description
`background`	`None`	Widget background color
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`icon_size`	`20`	Icon width
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`5`	Padding between icons

Available commands

Click to view the available commands for Systray

TaskList

class libqtile.widget.TaskList(*args, **kwargs)[source]

Displays the icon and name of each window in the current group

Contrary to WindowTabs this is an interactive widget. The window that currently has focus is highlighted.

Optional requirements: pyxdg is needed to use theme icons and to display icons on Wayland.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`border`	`'215578'`	Border colour
`borderwidth`	`2`	Current group border width
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`highlight_method`	`'border'`	Method of highlighting (one of 'border' or 'block') Uses *_border color settings
`icon_size`	`None`	Icon size. (Calculated if set to None. Icons are hidden if set to 0.)
`margin`	`3`	Margin inside the box
`margin_x`	`None`	X Margin. Overrides 'margin' if set
`margin_y`	`None`	Y Margin. Overrides 'margin' if set
`markup_floating`	`None`	Text markup of the floating window state. Supports pangomarkup with markup=True.e.g., "{}" or "<span underline="low">{}</span>"
`markup_focused`	`None`	Text markup of the focused window state. Supports pangomarkup with markup=True.e.g., "{}" or "<span underline="low">{}</span>"
`markup_focused_floating`	`None`	Text markup of the focused and floating window state. Supports pangomarkup with markup=True.e.g., "{}" or "<span underline="low">{}</span>"
`markup_maximized`	`None`	Text markup of the maximized window state. Supports pangomarkup with markup=True.e.g., "{}" or "<span underline="low">{}</span>"
`markup_minimized`	`None`	Text markup of the minimized window state. Supports pangomarkup with markup=True.e.g., "{}" or "<span underline="low">{}</span>"
`markup_normal`	`None`	Text markup of the normal window state. Supports pangomarkup with markup=True.e.g., "{}" or "<span underline="low">{}</span>"
`max_title_width`	`None`	Max size in pixels of task title.(if set to None, as much as available.)
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`3`	Padding inside the box
`padding_x`	`None`	X Padding. Overrides 'padding' if set
`padding_y`	`None`	Y Padding. Overrides 'padding' if set
`parse_text`	`None`	Function to parse and modify window names. e.g. function in config that removes excess strings from window name: def my_func(text) for string in [" - Chromium", " - Firefox"]: text = text.replace(string, "") return textthen set option parse_text=my_func
`rounded`	`True`	To round or not to round borders
`spacing`	`None`	Spacing between tasks. If set to None, defaults to margin_x in horizontal bars and margin_y in vertical bars.
`stretch`	`True`	Widget fills available space in bar. Set to False to limit widget width to size of its contents.
`theme_mode`	`None`	When to use theme icons. None = never, preferred = use if available, fallback = use if app does not provide icon directly. preferred and fallback have identical behaviour on Wayland.
`theme_path`	`None`	Path to icon theme to be used by pyxdg for icons. `None` will use default icon theme.
`title_width_method`	`None`	Method to compute the width of task title. (None, 'uniform'.)Defaults to None, the normal behaviour.
`txt_floating`	`'V '`	Text representation of the floating window state. e.g., "V " or "🗗 "
`txt_maximized`	`'[] '`	Text representation of the maximized window state. e.g., "[] " or "🗖 "
`txt_minimized`	`'_ '`	Text representation of the minimized window state. e.g., "_ " or "🗕 "
`unfocused_border`	`None`	Border color for unfocused windows. Affects only hightlight_method 'border' and 'block'. Defaults to None, which means no special color.
`urgent_alert_method`	`'border'`	Method for alerting you of WM urgent hints (one of 'border' or 'text')
`urgent_border`	`'FF0000'`	Urgent border color
`window_name_location`	`False`	Whether to show the location of the window in the title.
`window_name_location_offset`	`0`	The offset given to the window location

Available commands

Click to view the available commands for TaskList

TextBox

class libqtile.widget.TextBox(*args, **kwargs)[source]

A flexible textbox that can be updated from bound keys, scripts, and qshell.

Supported bar orientations: horizontal and vertical

example	config
	default
	default
	default
	default
	default
	default
	default
	default
	default
	default
	`foreground='2980b9'`
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Text font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font pixel size. Calculated if None.
`foreground`	`'#ffffff'`	Foreground colour.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding left and right. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step

Available commands

Click to view the available commands for TextBox

ThermalSensor

class libqtile.widget.ThermalSensor(*args, **kwargs)[source]

Widget to display temperature sensor information

For using the thermal sensor widget you need to have lm-sensors installed. You can get a list of the tag_sensors executing "sensors" in your terminal. Then you can choose which you want, otherwise it will display the first available.

Widget requirements: psutil.

Supported bar orientations: horizontal and vertical

example	config
	default
	`tag_sensor='NVME'`
	`format='{tag}: {temp:.0f}{unit}'`
	`threshold=30.0`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`foreground_alert`	`'ff0000'`	Foreground colour alert
`format`	`'{temp:.1f}{unit}'`	Display string format. Three options available: `{temp}` - temperature, `{tag}` - tag of the temperature sensor, and `{unit}` - °C or °F
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`metric`	`True`	True to use metric/C, False to use imperial/F
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`tag_sensor`	`None`	Tag of the temperature sensor. For example: "temp1" or "Core 0"
`threshold`	`70`	If the current temperature value is above, then change to foreground_alert colour
`update_interval`	`2`	Update interval in seconds

Available commands

Click to view the available commands for ThermalSensor

ThermalZone

class libqtile.widget.ThermalZone(*args, **kwargs)[source]

Thermal zone widget.

This widget was made to read thermal zone files and transform values to human readable format. You can set zone parameter to any standard thermal zone file from /sys/class/thermal directory.

Supported bar orientations: horizontal only

example	config
	default
	`high=45`
	`high=40, crit=45`

Configuration options

key	default	description
`background`	`None`	Widget background color
`crit`	`70`	Critical temperature level
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fgcolor_crit`	`'ff0000'`	Font color on critical values
`fgcolor_high`	`'ffaa00'`	Font color on high values
`fgcolor_normal`	`'ffffff'`	Font color on normal values
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{temp}°C'`	Display format
`format_crit`	`'{temp}°C CRIT!'`	Critical display format
`hidden`	`False`	Set True to only show if critical value reached
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`high`	`50`	High themperature level
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`2.0`	Update interval
`zone`	`'/sys/class/thermal/thermal_zone0/temp'`	Thermal zone

Available commands

Click to view the available commands for ThermalZone

TunedManager

class libqtile.widget.TunedManager(*args, **kwargs)[source]

A widget to interact with the Tuned power management daemon. It always displays the name of the currently active profile.

The user can define a list of profiles to be used, 3 default profiles exist. These 3 are the default profiles on RHEL and Fedora Linux.

A left click on the widget will go to the next layout in the list, a right click will go to the previous one. If the end of the list is reached, it cycles back to the beginning. Scrolling can also be used to cycle through the list, though keep in mind that switching the profile takes a while and so scrolling through the list quickly is not feasible.

Supported bar orientations: horizontal only

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`modes`	`['powersave', 'balanced-battery', 'throughput-performance']`	The modes to cycle through
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`600`	Update interval in seconds, if none, the widget updates only once.

Available commands

Click to view the available commands for TunedManager

VerticalClock

class libqtile.widget.VerticalClock(*args, **kwargs)[source]

A simple but flexible text-based clock for vertical bars.

Unlike the Clock widget, VerticalClock will display text horizontally in the bar.

Supported bar orientations: vertical only

example	config
	default
	`format=['%H', '%M', '', '%d', '%m', '%y'], fontsize=[12, 12, 10, 10, 10, 10]`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. A single value will be applied to all fields. Alternatively, users can provide a list of sizes with each size being applied to the corresponding text format.
`foreground`	`'fff'`	Text colour. A single string will be applied to all fields. Alternatively, users can provide a list of strings with each colour being applied to the corresponding text format.
`format`	`['%H', '%M']`	A list of Python datetime format string. Each string is printed as a separate line.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`timezone`	`None`	The timezone to use for this clock, either as string if pytz or dateutil is installed (e.g. "US/Central" or anything in /usr/share/zoneinfo), or as tzinfo (e.g. datetime.timezone.utc). None means the system local timezone and is the default.
`update_interval`	`1.0`	Update interval for the clock

Available commands

Click to view the available commands for VerticalClock

Volume

class libqtile.widget.Volume(*args, **kwargs)[source]

Widget that display and change volume

By default, this widget uses amixer to get and set the volume so users will need to make sure this is installed. Alternatively, users may set the relevant parameters for the widget to use a different application.

If theme_path is set it draw widget as icons.

Supported bar orientations: horizontal only

example	config
	`theme_path='/home/docs/checkouts/readthedocs.org/user_builds/qtile/checkouts/stable/test/data/ss_temp'`
	`emoji=True`
	`fmt='Vol: {}'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`cardid`	`None`	Card Id
`channel`	`'Master'`	Channel
`check_mute_command`	`None`	Command to check mute status
`check_mute_string`	`'[off]'`	String expected from check_mute_command when volume is muted.When the output of the command matches this string, theaudio source is treated as muted.
`device`	`'default'`	Device Name
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`emoji`	`False`	Use emoji to display volume states, only if `theme_path` is not set.The specified font needs to contain the correct unicode characters.
`emoji_list`	`['🔇', '🔈', '🔉', '🔊']`	List of emojis/font-symbols to display volume states, only if `emoji` is set. List contains 4 symbols, from lowest volume to highest.
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`get_volume_command`	`None`	Command to get the current volume. The expected output should include 1-3 numbers and a `%` sign.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`mute_command`	`None`	Mute command
`mute_foreground`	`None`	Foreground color for mute volume.
`mute_format`	`'M'`	Format to display when volume is muted.
`padding`	`3`	Padding left and right. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`step`	`2`	Volume change for up an down commands in percentage.Only used if `volume_up_command` and `volume_down_command` are not set.
`theme_path`	`None`	Path of the icons
`unmute_format`	`'{volume}%'`	Format of text to display when volume is not muted.
`update_interval`	`0.2`	Update time in seconds.
`volume_app`	`None`	App to control volume
`volume_down_command`	`None`	Volume down command
`volume_up_command`	`None`	Volume up command

Available commands

Click to view the available commands for Volume

Wallpaper

class libqtile.widget.Wallpaper(*args, **kwargs)[source]

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`directory`	`'~/Pictures/wallpapers/'`	Wallpaper Directory
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`label`	`None`	Use a fixed label instead of image name.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`option`	`'fill'`	How to fit the wallpaper when wallpaper_command isNone. None, 'fill' or 'stretch'.
`padding`	`None`	Padding. Calculated if None.
`random_selection`	`False`	If set, use random initial wallpaper and randomly cycle through the wallpapers.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`wallpaper`	`None`	Wallpaper
`wallpaper_command`	`['feh', '--bg-fill']`	Wallpaper command. If None, thewallpaper will be painted without the use of a helper.

Available commands

Click to view the available commands for Wallpaper

WidgetBox

class libqtile.widget.WidgetBox(*args, **kwargs)[source]

A widget to declutter your bar.

WidgetBox is a widget that hides widgets by default but shows them when the box is opened.

Widgets that are hidden will still update etc. as if they were on the main bar.

Button clicks are passed to widgets when they are visible so callbacks will work.

Widgets in the box also remain accessible via command interfaces.

Widgets can only be added to the box via the configuration file. The widget is configured by adding widgets to the "widgets" parameter as follows:

widget.WidgetBox(widgets=[
    widget.TextBox(text="This widget is in the box"),
    widget.Memory()
    ]
),

Supported bar orientations: horizontal only

example	config
	`widgets=[]`
	`widgets=[]`

Configuration options

key	default	description
`background`	`None`	Widget background color
`close_button_location`	`'left'`	Location of close button when box open ('left' or 'right')
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`start_opened`	`False`	Spawn the box opened
`text_closed`	`'[<]'`	Text when box is closed
`text_open`	`'[>]'`	Text when box is open
`widgets`	`[]`	A list of widgets to include in the box

Available commands

Click to view the available commands for WidgetBox

WindowCount

class libqtile.widget.WindowCount(*args, **kwargs)[source]

A simple widget to display the number of windows in the current group of the screen on which the widget is.

Supported bar orientations: horizontal and vertical

example	config
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Text font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font pixel size. Calculated if None.
`foreground`	`'#ffffff'`	Foreground colour.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding left and right. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`show_zero`	`False`	Show window count when no windows
`text_format`	`'{num}'`	Format for message

Available commands

Click to view the available commands for WindowCount

WindowName

class libqtile.widget.WindowName(*args, **kwargs)[source]

Displays the name of the window that currently has focus

Supported bar orientations: horizontal and vertical

example	config
	default
	default
	default
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`empty_group_string`	`' '`	string to display when no windows are focused on current group
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`for_current_screen`	`False`	instead of this bars screen use currently active screen
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{state}{name}'`	format of the text
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse_text`	`None`	Function to parse and modify window names. e.g. function in config that removes excess strings from window name: def my_func(text) for string in [" - Chromium", " - Firefox"]: text = text.replace(string, "") return textthen set option parse_text=my_func
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step

Available commands

Click to view the available commands for WindowName

WindowTabs

class libqtile.widget.WindowTabs(*args, **kwargs)[source]

Displays the name of each window in the current group. Contrary to TaskList this is not an interactive widget. The window that currently has focus is highlighted.

Supported bar orientations: horizontal and vertical

example	config
	default

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse_text`	`<function WindowTabs.<lambda> at 0x7ea819752ac0>`	Function to modify window names. It must accept a string argument (original window name) and return a string with the modified name.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`selected`	`('<b>', '</b>')`	Selected task indicator
`separator`	`' \| '`	Task separator text.

Available commands

Click to view the available commands for WindowTabs

Wlan

class libqtile.widget.Wlan(*args, **kwargs)[source]

Displays Wifi SSID and quality.

Widget requirements: iwlib.

Supported bar orientations: horizontal only

example	config
	default
	`format='{essid} {percent:2.0%}'`

Configuration options

key	default	description
`background`	`None`	Widget background color
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`disconnected_message`	`'Disconnected'`	String to show when the wlan is diconnected.
`ethernet_interface`	`'eth0'`	The ethernet interface to monitor, NOTE: If you do not have a wlan device in your system, ethernet functionality will not work, use the Net widget instead
`ethernet_message_format`	`'eth'`	String to show when ethernet is being used. For IP of ethernet interface use {ipaddr}.
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{essid} {quality}/70'`	Display format. For percents you can use "{essid} {percent:2.0%}". For IP of wlan interface use {ipaddr}.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`interface`	`'wlan0'`	The interface to monitor
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`update_interval`	`1`	The update interval.
`use_ethernet`	`False`	Activate or deactivate checking for ethernet when no wlan connection is detected

Available commands

Click to view the available commands for Wlan

WlanIw

class libqtile.widget.WlanIw(*args, **kwargs)[source]

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`cmd`	`None`	command line as a string or list of arguments to execute
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`disconnected_message`	`'Disconnected'`	String to show when the wlan is diconnected.
`ethernet_interface`	`'eth0'`	The ethernet interface to monitor, NOTE: If you do not have a wlan device in your system, ethernet functionality will not work, use the Net widget instead
`ethernet_message_format`	`'eth'`	String to show when ethernet is being used. For IP of ethernet interface use {ipaddr}.
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'{essid} {quality}/70'`	Display format. For percents you can use "{essid} {percent:2.0%}". For IP of wlan interface use {ipaddr}.
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`interface`	`'wlan0'`	The interface to monitor
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse`	`None`	Function to parse output of command
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`shell`	`False`	run command through shell to enable piping and shell expansion
`update_interval`	`1`	The update interval.
`use_ethernet`	`False`	Activate or deactivate checking for ethernet when no wlan connection is detected

Available commands

Click to view the available commands for WlanIw

Wttr

class libqtile.widget.Wttr(*args, **kwargs)[source]

Display weather widget provided by wttr.in.

To specify your own custom output format, use the special %-notation (example: 'My_city: %t(%f), wind: %w'):

%c Weather condition,

%C Weather condition textual name,

%h Humidity,

%t Temperature (Actual),

%f Temperature (Feels Like),

%w Wind,

%l Location,

%m Moonphase 🌑🌒🌓🌔🌕🌖🌗🌘,

%M Moonday,

%p precipitation (mm),

%P pressure (hPa),

%D Dawn !,

%S Sunrise !,

%z Zenith !,

%s Sunset !,

%d Dusk !. (!times are shown in the local timezone)

Add the character ~ at the beginning to get weather for some special location: ~Vostok Station or ~Eiffel Tower.

Also can use IP-addresses (direct) or domain names (prefixed with @) to specify a location: @github.com, 123.456.678.123

Specify multiple locations as dictionary

location={
    'Minsk': 'Minsk',
    '64.127146,-21.873472': 'Reykjavik',
}

Cities will change randomly every update.

Supported bar orientations: horizontal and vertical

Configuration options

key	default	description
`background`	`None`	Widget background color
`data`	`None`	Post Data
`direction`	`'default'`	Override the text direction in vertical bar, has no effect on text in horizontal bar.default: text displayed based on vertical bar position (left/right)ttb: text read from top to bottom, btt: text read from bottom to top.'default', 'ttb', 'btt'
`fmt`	`'{}'`	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns `foo`, using `fmt='<i>{}</i>'` would give you `<i>foo</i>`. To control what the widget outputs in the first place, use the `format` paramater of the widget (if it has one).
`font`	`'sans'`	Default font
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`format`	`'3'`	Display text format. Choose presets in range 1-4 (Ex. `"1"`) or build your own custom output format, use the special %-notation. See https://github.com/chubin/wttr.in#one-line-output
`headers`	`{}`	Extra Headers
`hide_crash`	`False`	Don't display error in bar if widget crashes on startup.
`json`	`False`	Is Json?
`lang`	`'en'`	Display text language. List of supported languages https://wttr.in/:translation
`location`	`{}`	Dictionary. Key is a city or place name, or GPS coordinates. Value is a display name. If the dictionary is empty, the location will be determined based on your IP address.
`markup`	`True`	Whether or not to use pango markup
`max_chars`	`0`	Maximum number of characters to display in widget.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts functions and `lazy` calls.
`padding`	`None`	Padding. Calculated if None.
`parse`	`None`	Parse Function
`rotate`	`True`	Rotate text in vertical bar.
`scroll`	`False`	Whether text should be scrolled. When True, you must set the widget's `width`.
`scroll_clear`	`False`	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
`scroll_delay`	`2`	Number of seconds to pause before starting scrolling and restarting/clearing text at end
`scroll_fixed_width`	`False`	When `scroll=True` the `width` parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting `scroll_fixed_width=True` will force the widget to have a fixed width, regardless of the size of the text.
`scroll_hide`	`False`	Whether the widget should hide when scrolling has finished
`scroll_interval`	`0.1`	Time in seconds before next scrolling step
`scroll_repeat`	`True`	Whether text should restart scrolling once the text has ended
`scroll_step`	`1`	Number of pixels to scroll with each step
`units`	`'m'`	`'m'` - metric, `'M'` - show wind speed in m/s, `'u'` - United States units
`update_interval`	`600`	Update interval in seconds. Recommendation: if you want to display multiple locations alternately, maybe set a smaller interval, ex. `30`.
`url`	`None`	Url
`user_agent`	`'Qtile'`	Set the user agent
`xml`	`False`	Is XML?

Available commands

Click to view the available commands for Wttr