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

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

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

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

'acpi_video0'

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

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

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.

mouse_callbacks

{}

Dict of mouse button press callback functions. Accepts functions and lazy calls.

padding

None

Padding. Calculated if None.

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

discharge_char

'V'

Character to indicate the battery is discharging

empty_char

'x'

Character to indicate the battery is empty

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

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.

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 "Full" or "Empty" rather than formated text

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

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/latest/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.

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

hci

None

(deprecated) same as 'device'.

hide_unnamed_devices

False

Devices with no name will be hidden from scan results

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

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.

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

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

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.

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

line_width

3

Line width

margin_x

3

Margin X

margin_y

3

Margin Y

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

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

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.

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

example config
default

Configuration options

key

default

description

background

None

Widget background color

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

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.

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 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 updates -q', 1)

  • 'FreeBSD' runs ("pkg_version -I -l '<'", 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 0x7f2e0a3eef80>

Lambda function to modify line count from custom_command

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

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)

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.

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

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 0x7f2e0a3ef2e0>

preprocessor for chord name it is pure function string -> string

padding

None

Padding. Calculated if None.

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

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

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.

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

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

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.

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.

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

Supported bar orientations: horizontal and vertical

example config
default

Configuration options

key

default

description

background

None

Widget background color

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

'{play_icon}{artist} - {title}'

Format of playback info.

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.

play_color

'00ff00'

Text colour when playing.

play_icon

'♫ '

Icon to display, if chosen.

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 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(2024, 3, 19, 18, 39, 24, 239567)

Configuration options

key

default

description

background

None

Widget background color

date

datetime.datetime(2024, 3, 18, 16, 5, 15, 189158)

The datetime for the end of the countdown

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.

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.

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")

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

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

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

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 name of the current layout of the current group of the screen, the bar containing the widget, is on.

Supported bar orientations: horizontal and vertical

Configuration options

key

default

description

background

None

Widget background color

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

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.

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

CurrentLayoutIcon

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

Display the icon representing 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 only

Configuration options

key

default

description

background

None

Widget background color

custom_icon_paths

[]

List of folders where to search icons beforeusing built-in icons or icons in ~/.icons dir. This can also be used to providemissing icons for custom layouts. Defaults to empty list.

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

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.

scale

1

Scale factor relative to the bar height. Defaults to 1

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 CurrentLayoutIcon

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

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

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.

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

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))

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

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

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

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

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.

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

Supported bar orientations: horizontal and vertical

example config
func= at 0x7f9ab7c639a0>

Configuration options

key

default

description

background

None

Widget background color

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

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.

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

Supported bar orientations: horizontal and vertical

example config
default
url='http://test.qtile.org', json=False, parse= at 0x7f9ab7b23760>

Configuration options

key

default

description

background

None

Widget background color

data

None

Post Data

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

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

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

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

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

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

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_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

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

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

line_width

3

Line width

margin_x

3

Margin X

margin_y

3

Margin Y

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

line_width

3

Line width

margin_x

3

Margin X

margin_y

3

Margin Y

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

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

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

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/latest/test/widgets/docs_screenshots/../../scripts/qtile-logo-blue.svg'
filename='/home/docs/checkouts/readthedocs.org/user_builds/qtile/checkouts/latest/test/widgets/docs_screenshots/../../scripts/qtile-logo-blue.svg', margin=5
filename='/home/docs/checkouts/readthedocs.org/user_builds/qtile/checkouts/latest/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 '~'

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.

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 is 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):

  1. 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/
    
  2. 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.

Widget requirements: keyring.

Supported bar orientations: horizontal and vertical

example config
user='qtile'

Configuration options

key

default

description

background

None

Widget background color

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

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.

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-next.

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']

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

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.

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'].

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

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.

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

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

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

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]

A widget that display icons to launch the associated command.

Text will displayed when no icon is found.

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

Supported bar orientations: horizontal only

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.

icon_size

None

Size of icons. None to fit to bar.

mouse_callbacks

{}

Dict of mouse button press callback functions. Accepts functions and lazy calls.

padding

2

Padding between icons

padding_y

0

Vertical adjustment for 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

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.

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.

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

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_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.

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.

  • 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

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.

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.

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

line_width

3

Line width

margin_x

3

Margin X

margin_y

3

Margin Y

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

example config
default

Configuration options

key

default

description

background

None

Widget background color

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

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.

play_color

'00ff00'

Text colour when playing.

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 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 0x7f2e0a2d16c0>

command to be executed by mapped mouse button.

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 0x7f2e0ce027a0>}

Dictionary of format methods

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

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-next.

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

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

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).

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

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

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

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.

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

interface

'auto'

Interface to display info for ('auto' for detection)

line_width

3

Line width

margin_x

3

Margin X

margin_y

3

Margin Y

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

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

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

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

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

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

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.

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

example config
location='London'
location='London', format='{location_city}: {sunrise} {sunset}'
location='London', format='{location_city}: {wind_speed} {wind_deg} {wind_direction}'
location='London', format='{location_city}: {icon}'

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

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

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

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

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

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

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

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.

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

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

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

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

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.

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_command

None

Mute command

padding

3

Padding left and right. Calculated if None.

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

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 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.

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

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.

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

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

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.

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.

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.

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

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"

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.

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

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

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

example config
symbol='QTIL'

Configuration options

key

default

description

background

None

Widget background color

data

None

Post Data

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

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

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

line_width

3

Line width

margin_x

3

Margin X

margin_y

3

Margin Y

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

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

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 only

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

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, will be equal to margin_x)

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
foreground='2980b9'

Configuration options

key

default

description

background

None

Widget background color

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.

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.

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

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

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.

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

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

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.

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

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/latest/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

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.

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

padding

3

Padding left and right. Calculated if None.

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

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

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

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.

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')

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

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.

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

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.

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.

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

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

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

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

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

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 0x7f2e0a2003a0>

Function to modify window names. It must accept a string argument (original window name) and return a string with the modified name.

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

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

'eth'

String to show when ethernet is being used

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%}"

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.

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

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

example config
location={'London': 'Home'}

Configuration options

key

default

description

background

None

Widget background color

data

None

Post Data

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

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

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