Built-in Widgets

AGroupBox

class libqtile.widget.AGroupBox(**config)[source]

A widget that graphically displays the current group

Supported bar orientations: horizontal only

key default description
background None Widget background color
border '000000' group box border color
borderwidth 3 Current group border width
center_aligned False center-aligned group box
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.

Backlight

class libqtile.widget.Backlight(**config)[source]

A simple widget to show the current brightness of a monitor

Supported bar orientations: horizontal only

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
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 False 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
padding None Padding. Calculated if None.
step 10 Percent of backlight every scroll changed
update_interval 0.2 The delay in seconds between updates

BitcoinTicker

class libqtile.widget.BitcoinTicker(**config)[source]

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

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

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

Supported bar orientations: horizontal only

key default description
background None Widget background color
currency '' The currency the value that bitcoin is displayed in
data None Post Data
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
parse None Parse Function
update_interval 600 Update interval in seconds, if none, the widget updates whenever the event loop is idle.
url None Url
user_agent 'Qtile' Set the user agent
xml False Is XML?

CPUGraph

class libqtile.widget.CPUGraph(**config)[source]

Display CPU usage graph

Supported bar orientations: horizontal only

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
samples 100 Count of graph samples.
start_pos 'bottom' Drawer starting position (‘bottom’/’top’)
type 'linefill' ‘box’, ‘line’, ‘linefill’

Canto

class libqtile.widget.Canto(**config)[source]

Display RSS feeds updates using the canto console reader

Supported bar orientations: horizontal only

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
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 False Whether or not to use pango markup
one_format '{name}: {number}' One feed display format
padding None Padding. Calculated if None.
update_interval 600 Update interval in seconds, if none, the widget updates whenever the event loop is idle.

CapsNumLockIndicator

class libqtile.widget.CapsNumLockIndicator(**config)[source]

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

Supported bar orientations: horizontal only

key default description
background None Widget background color
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
update_interval 0.5 Update Time in seconds.

CheckUpdates

class libqtile.widget.CheckUpdates(**config)[source]

Shows number of pending updates in different unix systems

Supported bar orientations: horizontal only

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)
display_format 'Updates: {updates}' Display format if updates available
distro 'Arch' Name of your distribution
execute None Command to execute on click
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
restart_indicator '' Indicator to represent reboot is required. (Ubuntu only)
update_interval 60 Update interval in seconds.

Clipboard

class libqtile.widget.Clipboard(width=CALCULATED, **config)[source]

Display current clipboard contents

Supported bar orientations: horizontal only

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
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 False Whether or not to use pango markup
max_width 10 maximum number of characters to display (None for all, useful when width is bar.STRETCH)
padding None Padding. Calculated if None.
selection 'CLIPBOARD' the selection to display(CLIPBOARD or PRIMARY)
timeout 10 Default timeout (seconds) for display text, None to keep forever

Clock

class libqtile.widget.Clock(**config)[source]

A simple but flexible text-based clock

Supported bar orientations: horizontal only

key default description
background None Widget background color
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
timezone None The timezone to use for this clock, e.g. “US/Central” (or anything in /usr/share/zoneinfo). None means the default timezone.
update_interval 1.0 Update interval for the clock

Cmus

class libqtile.widget.Cmus(**config)[source]

A simple Cmus 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.

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

Supported bar orientations: horizontal only

key default description
background None Widget background color
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 False Whether or not to use pango markup
max_chars 0 Maximum number of characters to display in widget.
noplay_color 'cecece' Text colour when not playing.
padding None Padding. Calculated if None.
play_color '00ff00' Text colour when playing.
update_interval 0.5 Update Time in seconds.

Countdown

class libqtile.widget.Countdown(**config)[source]

A simple countdown timer text widget

Supported bar orientations: horizontal only

key default description
background None Widget background color
date datetime.datetime(2018, 12, 24, 3, 12, 39, 747037) The datetime for the endo of the countdown
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
update_interval 1.0 Update interval in seconds for the clock

CurrentLayout

class libqtile.widget.CurrentLayout(width=CALCULATED, **config)[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 only

key default description
background None Widget background color
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.

CurrentLayoutIcon

class libqtile.widget.CurrentLayoutIcon(**config)[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 order of icon search is:

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

Supported bar orientations: horizontal only

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.
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
scale 1 Scale factor relative to the bar height. Defaults to 1

CurrentScreen

class libqtile.widget.CurrentScreen(width=CALCULATED, **config)[source]

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

Supported bar orientations: horizontal only

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
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.

DF

class libqtile.widget.DF(**config)[source]

Disk Free Widget

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

Supported bar orientations: horizontal only

key default description
background None Widget background color
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 False Whether or not to use pango markup
measure 'G' Measurement (G, M, B)
padding None Padding. Calculated if None.
partition '/' the partition to check space
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.

DebugInfo

class libqtile.widget.DebugInfo(**config)[source]

Displays debugging infos about selected window

Supported bar orientations: horizontal only

key default description
background None Widget background color
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.

GenPollText

class libqtile.widget.GenPollText(**config)[source]

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

Supported bar orientations: horizontal only

key default description
background None Widget background color
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
update_interval 600 Update interval in seconds, if none, the widget updates whenever the event loop is idle.

GenPollUrl

class libqtile.widget.GenPollUrl(**config)[source]

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

Supported bar orientations: horizontal only

key default description
background None Widget background color
data None Post Data
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
parse None Parse Function
update_interval 600 Update interval in seconds, if none, the widget updates whenever the event loop is idle.
url None Url
user_agent 'Qtile' Set the user agent
xml False Is XML?

GmailChecker

class libqtile.widget.GmailChecker(**config)[source]

A simple gmail checker

Supported bar orientations: horizontal only

key default description
background None Widget background color
email_path 'INBOX' email_path
fmt 'inbox[%s],unseen[%s]' fmt
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
password None password
status_only_unseen False Only show unseen messages
update_interval 30 Update time in seconds.
username None username

GroupBox

class libqtile.widget.GroupBox(**config)[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

key default description
active 'FFFFFF' Active group font colour
background None Widget background color
borderwidth 3 Current group border width
center_aligned False center-aligned group box
disable_drag False Disable dragging and dropping of group names on widget
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
markup False Whether or not to use pango markup
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.
rounded True To round or not to round box borders
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.
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.

HDDBusyGraph

class libqtile.widget.HDDBusyGraph(**config)[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

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
samples 100 Count of graph samples.
start_pos 'bottom' Drawer starting position (‘bottom’/’top’)
type 'linefill' ‘box’, ‘line’, ‘linefill’

HDDGraph

class libqtile.widget.HDDGraph(**config)[source]

Display HDD free or used space graph

Supported bar orientations: horizontal only

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

IdleRPG

class libqtile.widget.IdleRPG(**config)[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")

Supported bar orientations: horizontal only

key default description
background None Widget background color
data None Post Data
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 False Not json :)
markup False Whether or not to use pango markup
padding None Padding. Calculated if None.
parse None Parse Function
update_interval 600 Update interval in seconds, if none, the widget updates whenever the event loop is idle.
url None Url
user_agent 'Qtile' Set the user agent
xml True Is XML :)

Image

libqtile.widget.Image

alias of libqtile.widget.import_error.make_error.<locals>.ImportErrorWidget

ImapWidget

class libqtile.widget.ImapWidget(**config)[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.

Supported bar orientations: horizontal only

key default description
background None Widget background color
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 False Whether or not to use pango markup
mbox '"INBOX"' mailbox to fetch
padding None Padding. Calculated if None.
server None email server name
update_interval 600 Update interval in seconds, if none, the widget updates whenever the event loop is idle.
user None email username

KeyboardKbdd

class libqtile.widget.KeyboardKbdd(**config)[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

Supported bar orientations: horizontal only

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’]
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
update_interval 1 Update interval in seconds.

KeyboardLayout

class libqtile.widget.KeyboardLayout(**config)[source]

Widget for changing and displaying the current keyboard layout

It requires setxkbmap to be available in the system.

Supported bar orientations: horizontal only

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’].
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
update_interval 1 Update time in seconds.

KhalCalendar

class libqtile.widget.KhalCalendar(**config)[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.

Supported bar orientations: horizontal only

key default description
background None Widget background color
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
reminder_color 'FF0000' color of calendar entries during reminder time
remindertime 10 reminder time in minutes
update_interval 600 Update interval in seconds, if none, the widget updates whenever the event loop is idle.

LaunchBar

class libqtile.widget.LaunchBar(progs=None, width=CALCULATED, **config)[source]

A widget that display icons to launch the associated command

Parameters:
progs :

a list of tuples (software_name, command_to_execute, comment), for example:

('thunderbird', 'thunderbird -safe-mode', 'launch thunderbird in safe mode')
('logout', 'qshell:self.qtile.cmd_shutdown()', 'logout from qtile')

Supported bar orientations: horizontal only

key default description
background None Widget background color
default_icon '/usr/share/icons/oxygen/256x256/mimetypes/application-x-executable.png' Default icon not found
padding 2 Padding between icons

Maildir

class libqtile.widget.Maildir(**config)[source]

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

Supported bar orientations: horizontal only

key default description
background None Widget background color
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
maildirPath '~/Mail' path to the Maildir folder
markup False Whether or not to use pango markup
padding None Padding. Calculated if None.
separator ' ' the string to put between the subfolder strings.
subFolders [] The subfolders to scan (e.g. [{“path”: “INBOX”, “label”: “Home mail”}, {“path”: “spam”, “label”: “Home junk”}]
update_interval 600 Update interval in seconds, if none, the widget updates whenever the event loop is idle.

Memory

class libqtile.widget.Memory(**config)[source]

Displays memory usage

Supported bar orientations: horizontal only

key default description
background None Widget background color
fmt '{MemUsed}M/{MemTotal}M' see /proc/meminfo for field names
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
update_interval 600 Update interval in seconds, if none, the widget updates whenever the event loop is idle.

MemoryGraph

class libqtile.widget.MemoryGraph(**config)[source]

Displays a memory usage graph

Supported bar orientations: horizontal only

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
samples 100 Count of graph samples.
start_pos 'bottom' Drawer starting position (‘bottom’/’top’)
type 'linefill' ‘box’, ‘line’, ‘linefill’

Moc

class libqtile.widget.Moc(**config)[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 only

key default description
background None Widget background color
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 False Whether or not to use pango markup
max_chars 0 Maximum number of characters to display in widget.
noplay_color 'cecece' Text colour when not playing.
padding None Padding. Calculated if None.
play_color '00ff00' Text colour when playing.
update_interval 0.5 Update Time in seconds.

Mpd

class libqtile.widget.Mpd(**config)[source]

A widget for the Music Player Daemon (MPD)

Supported bar orientations: horizontal only

key default description
background None Widget background color
do_color_progress True Whether to indicate progress in song by altering message color
fmt_playing '%a - %t [%v%%]' Format string to display when playing/paused
fmt_stopped 'Stopped [%v%%]' Format strings to display when stopped
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_progress 'ffffff' Foreground progress colour
host 'localhost' Host to connect to, can be either an IP address or a UNIX socket path
markup False Whether or not to use pango markup
msg_nc 'Mpd off' Which message to show when we’re not connected
padding None Padding. Calculated if None.
password None Password to use
port 6600 Port to connect to
reconnect False Attempt to reconnect if initial connection failed
reconnect_interval 1 Time to delay between connection attempts.
update_interval 0.5 Update Time in seconds.

Mpd2

class libqtile.widget.Mpd2(status_format='{play_status} {artist}/{title} [{repeat}{random}{single}{consume}{updating_db}]', prepare_status={'consume': <function option.<locals>._convert at 0x7f6bed4f2400>, 'random': <function option.<locals>._convert at 0x7f6bed4f22f0>, 'repeat': <function option.<locals>._convert at 0x7f6bed4f2268>, 'single': <function option.<locals>._convert at 0x7f6bed4f2378>, 'updating_db': <function option.<locals>._convert at 0x7f6bed4f2488>}, **config)[source]

A widget for Music Player Daemon (MPD) based on python-mpd2

This widget exists since python-mpd library is no more supported.

Parameters:
status_format :

format string to display status

Full list of values see in status and currentsong commands

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 string from play_states dict

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

prepare_status :

dict of functions for replace values in status with custom

f(status, key, space_element) => str

Supported bar orientations: horizontal only

key default description
background None Widget background color
command None Executable command by “command” shortcut
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
host 'localhost' Host of mpd server
idletimeout 5 MPDClient idle command timeout
keys {'command': None, 'next': 5, 'previous': 4, 'stop': 3, 'toggle': 1} Shortcut keys
markup False Whether or not to use pango markup
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
space '-' Space keeper
timeout 30 MPDClient timeout
update_interval 1 Interval of update widget

Mpris

class libqtile.widget.Mpris(**config)[source]

MPRIS player widget

A widget which displays the current track/artist of your favorite MPRIS player. It should work with all players which implement a reasonably correct version of MPRIS, though I have only tested it with clementine.

Supported bar orientations: horizontal only

key default description
background None Widget background color
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 False Whether or not to use pango markup
name 'clementine' Name of the widget
objname 'org.mpris.clementine' DBUS object to connect to
padding None Padding. Calculated if None.
stop_pause_text 'Stopped' Optional text to display when in the stopped/paused state

Mpris2

class libqtile.widget.Mpris2(**config)[source]

An MPRIS 2 widget

A widget which displays the current track/artist of your favorite MPRIS player. It should work with all MPRIS 2 compatible players which implement a reasonably correct version of MPRIS, though I have only tested it with audacious. This widget scrolls the text if neccessary and information that is displayed is configurable.

Supported bar orientations: horizontal only

key default description
background None Widget background color
display_metadata ['xesam:title', 'xesam:album', 'xesam:artist'] Which metadata identifiers to display. See http://www.freedesktop.org/wiki/Specifications/mpris-spec/metadata/#index5h3 for available values
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 False Whether or not to use pango markup
name 'audacious' Name of the MPRIS widget.
objname 'org.mpris.MediaPlayer2.audacious' DBUS MPRIS 2 compatible player identifier- Find it out with dbus-monitor - Also see: http://specifications.freedesktop.org/mpris-spec/latest/#Bus-Name-Policy
padding None Padding. Calculated if None.
scroll_chars 30 How many chars at once to display.
scroll_interval 0.5 Scroll delay interval.
scroll_wait_intervals 8 Wait x scroll_interval beforescrolling/removing text
stop_pause_text None Optional text to display when in the stopped/paused state

Net

class libqtile.widget.Net(**config)[source]

Displays interface down and up speed

Supported bar orientations: horizontal only

key default description
background None Widget background color
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
interface 'wlan0' The interface to monitor
markup False Whether or not to use pango markup
padding None Padding. Calculated if None.
update_interval 1 The update interval.

NetGraph

class libqtile.widget.NetGraph(**config)[source]

Display a network usage graph

Supported bar orientations: horizontal only

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
samples 100 Count of graph samples.
start_pos 'bottom' Drawer starting position (‘bottom’/’top’)
type 'linefill' ‘box’, ‘line’, ‘linefill’

Notify

class libqtile.widget.Notify(width=CALCULATED, **config)[source]

A notify widget

Supported bar orientations: horizontal only

key default description
audiofile None Audiofile played during notifications
background None Widget background color
default_timeout None Default timeout (seconds) for notifications
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.

Pacman

class libqtile.widget.Pacman(**config)[source]

Shows number of available updates

Needs the pacman package manager installed. So will only work in Arch Linux installation.

Supported bar orientations: horizontal only

key default description
background None Widget background color
execute None Command to execute on click
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
unavailable 'ffffff' Unavailable Color - no updates.
update_interval 60 The update interval.

Pomodoro

class libqtile.widget.Pomodoro(**config)[source]

Pomodoro technique widget

Supported bar orientations: horizontal only

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 '%s' fmt
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 False Whether or not to use pango markup
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
update_interval 1 Update interval in seconds, if none, the widget updates whenever the event loop is idle.

Prompt

class libqtile.widget.Prompt(name='prompt', **config)[source]

A widget that prompts for user input

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

Supported bar orientations: horizontal only

key default description
background None Widget background color
bell_style 'audible' Alert at the begin/end of the command history. Possible values: ‘audible’, ‘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.
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 False Whether or not to use pango markup
max_history 100 Commands to keep in history. 0 for no limit.
padding None Padding. Calculated if None.
prompt '{prompt}: ' Text displayed at the prompt
record_history True Keep a record of executed commands
visual_bell_color 'ff0000' Color for the visual bell (changes prompt background).
visual_bell_time 0.2 Visual bell duration (in seconds).

Sep

class libqtile.widget.Sep(height_percent=None, **config)[source]

A visible widget separator

Supported bar orientations: horizontal and vertical

key default description
background None Widget background color
foreground '888888' Separator line colour.
linewidth 1 Width of separator line.
padding 2 Padding on either side of separator.
size_percent 80 Size as a percentage of bar size (0-100).

She

class libqtile.widget.She(**config)[source]

Widget to display the Super Hybrid Engine status

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

Supported bar orientations: horizontal only

key default description
background None Widget background color
device '/sys/devices/platform/eeepc/cpufv' sys path to cpufv
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
update_interval 0.5 Update Time in seconds.

Spacer

class libqtile.widget.Spacer(length=STRETCH, width=None)[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

key default description
background None Widget background color

StockTicker

class libqtile.widget.StockTicker(**config)[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 only

key default description
background None Widget background color
data None Post Data
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
function 'TIME_SERIES_INTRADAY' The default API function to query
headers {} Extra Headers
interval '1min' The default latency to query
json True Is Json?
markup False Whether or not to use pango markup
padding None Padding. Calculated if None.
parse None Parse Function
update_interval 600 Update interval in seconds, if none, the widget updates whenever the event loop is idle.
url None Url
user_agent 'Qtile' Set the user agent
xml False Is XML?

SwapGraph

class libqtile.widget.SwapGraph(**config)[source]

Display a swap info graph

Supported bar orientations: horizontal only

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
samples 100 Count of graph samples.
start_pos 'bottom' Drawer starting position (‘bottom’/’top’)
type 'linefill' ‘box’, ‘line’, ‘linefill’

Systray

class libqtile.widget.Systray(**config)[source]

A widget that manages system tray

Supported bar orientations: horizontal only

key default description
background None Widget background color
icon_size 20 Icon width
padding 5 Padding between icons

TaskList

class libqtile.widget.TaskList(**config)[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.

Supported bar orientations: horizontal only

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.)
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_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.)
rounded True To round or not to round borders
spacing None Spacing between tasks.(if set to None, will be equal to margin_x)
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

TextBox

class libqtile.widget.TextBox(text=' ', width=CALCULATED, **config)[source]

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

Supported bar orientations: horizontal only

key default description
background None Widget background color
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 False Whether or not to use pango markup
padding None Padding left and right. Calculated if None.

ThermalSensor

class libqtile.widget.ThermalSensor(**config)[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.

Supported bar orientations: horizontal only

key default description
background None Widget background color
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
markup False Whether or not to use pango markup
metric True True to use metric/C, False to use imperial/F
padding None Padding. Calculated if None.
show_tag False Show tag sensor
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

Volume

class libqtile.widget.Volume(**config)[source]

Widget that display and change volume

If theme_path is set it draw widget as icons.

Supported bar orientations: horizontal only

key default description
background None Widget background color
cardid None Card Id
channel 'Master' Channel
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.
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
markup False Whether or not to use pango markup
mute_command None Mute command
padding 3 Padding left and right. Calculated if None.
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

Wallpaper

class libqtile.widget.Wallpaper(**config)[source]

Supported bar orientations: horizontal only

key default description
background None Widget background color
directory '~/Pictures/wallpapers/' Wallpaper Directory
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 False Whether or not to use pango markup
one_screen False Treat the whole X display as one screen when setting wallpapers (does not work if wallpaper_command is set).
padding None Padding. Calculated if None.
random_selection False If set, use random initial wallpaper and randomly cycle through the wallpapers.
wallpaper None Wallpaper
wallpaper_command None Wallpaper command

WindowName

class libqtile.widget.WindowName(width=STRETCH, **config)[source]

Displays the name of the window that currently has focus

Supported bar orientations: horizontal only

key default description
background None Widget background color
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
markup False Whether or not to use pango markup
padding None Padding. Calculated if None.
show_state True show window status before window name

WindowTabs

class libqtile.widget.WindowTabs(**config)[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 only

key default description
background None Widget background color
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
selected ('<', '>') Selected task indicator
separator ' | ' Task separator text.

Wlan

class libqtile.widget.Wlan(**config)[source]

Displays Wifi ssid and quality

Supported bar orientations: horizontal only

key default description
background None Widget background color
disconnected_message 'Disconnected' String to show when the wlan is diconnected.
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 False Whether or not to use pango markup
padding None Padding. Calculated if None.
update_interval 1 The update interval.

YahooWeather

class libqtile.widget.YahooWeather(**config)[source]

A weather widget, data provided by the Yahoo! Weather API.

Format options:

  • astronomy_sunrise
  • astronomy_sunset
  • atmosphere_humidity
  • atmosphere_visibility
  • atmosphere_pressure
  • atmosphere_rising
  • condition_text
  • condition_code
  • condition_temp
  • condition_date
  • location_city
  • location_region
  • location_country
  • units_temperature
  • units_distance
  • units_pressure
  • units_speed
  • wind_chill

Supported bar orientations: horizontal only

key default description
background None Widget background color
data None Post Data
down 'v' symbol for falling atmospheric pressure
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}: {condition_temp} °{units_temperature}' Display format
headers {} Extra Headers
json True Is Json?
location None Location to fetch weather for. Ignored if woeid is set.
markup False Whether or not to use pango markup
metric True True to use metric/C, False to use imperial/F
padding None Padding. Calculated if None.
parse None Parse Function
steady 's' symbol for steady atmospheric pressure
up '^' symbol for rising atmospheric pressure
update_interval 600 Update interval in seconds, if none, the widget updates whenever the event loop is idle.
url None Url
user_agent 'Qtile' Set the user agent
woeid None Where On Earth ID. Auto-calculated if location is set.
xml False Is XML?