Built-in Widgets

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

A widget that graphically displays the current group.

key default description
border '000000' group box border color
class libqtile.widget.Backlight(**config)[source]

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

key default description
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
max_brightness_file 'max_brightness' Name of file with the maximum brightness in /sys/class/backlight/backlight_name
update_interval 0.2 The delay in seconds between updates
class libqtile.widget.Battery(**config)[source]

A simple but flexible text-based battery widget.

key default description
low_foreground 'FF0000' font color when battery is low
format '{char} {percent:2.0%} {hour:d}:{min:02d}' Display format
charge_char '^' Character to indicate the battery is charging
discharge_char 'V' Character to indicate the battery is discharging
low_percentage 0.1 0 < x < 1 at which to indicate battery is low with low_foreground
hide_threshold None Hide the text when there is enough energy
class libqtile.widget.BatteryIcon(**config)[source]

Battery life indicator widget

key default description
theme_path '/home/docs/checkouts/readthedocs.org/user_builds/qtile/checkouts/latest/libqtile/resources/battery-icons' Path of the icons
custom_icons {} dict containing key->filename icon map
class libqtile.widget.BitcoinTicker(**config)[source]

A bitcoin ticker widget, data provided by the btc-e.com API. Defaults to displaying currency in whatever the current locale is.

key default description
currency '' The currency the value of bitcoin is displayed in
format 'BTC Buy: {buy}, Sell: {sell}' Display format, allows buy, sell, high, low, avg, vol, vol_cur, last, variables.
class libqtile.widget.CPUGraph(**config)[source]

Display CPU usage graph.

key default description
core 'all' Which core to show (all/0/1/2/...)
class libqtile.widget.Canto(**config)[source]

Display RSS feeds updates using the canto console reader.

key default description
fetch False Whether to fetch new items on update
feeds [] List of feeds to display, empty for all
one_format '{name}: {number}' One feed display format
all_format '{number}' All feeds display format
class libqtile.widget.Clipboard(width=CALCULATED, **config)[source]

Display current clipboard contents.

key default description
selection 'CLIPBOARD' the selection to display(CLIPBOARD or PRIMARY)
max_width 10 maximum number of characters to display (None for all, useful when width is bar.STRETCH)
timeout 10 Default timeout (seconds) for display text, None to keep forever
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
class libqtile.widget.Clock(fmt=None, **config)[source]

A simple but flexible text-based clock.

key default description
format '%H:%M' A Python datetime format string
update_interval 1.0 Update interval for the clock
timezone None The timezone to use for this clock, e.g. “US/Central” (or anything in /usr/share/zoneinfo). None means the default timezone.
class libqtile.widget.Countdown(**config)[source]

A simple countdown timer text widget.

key default description
format '{D}d {H}h {M}m {S}s' Format of the displayed text. Available variables:{D} == days, {H} == hours, {M} == minutes, {S} seconds.
update_interval 1.0 Update interval in seconds for the clock
date datetime.datetime(2015, 6, 29, 13, 50, 0, 892145) The datetime for the endo of the countdown
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.

key default description
font 'Arial' Default font
fontsize None Font size. Calculated if None.
padding None Padding. Calculated if None.
foreground 'ffffff' Foreground colour
fontshadow None font shadow color, default is None(no shadow)
markup False Whether or not to use pango markup
class libqtile.widget.DF(**config)[source]

Disk Free Widget

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

key default description
partition '/' the partition to check space
warn_color 'ff0000' Warning color
warn_space 2 Warning space in scale defined by the measure option.
visible_on_warn True Only display if warning
measure 'G' Measurement (G, M, B)
format '{p} ({uf}{m})' String format (p: partition, s: size, f: free space, uf: user free space, m: measure)
update_interval 60 The update inteval.
class libqtile.widget.DebugInfo(**config)[source]

Displays debugging infos about selected window

key default description
font 'Arial' Default font
fontsize None Font size. Calculated if None.
padding None Padding. Calculated if None.
foreground 'ffffff' Foreground colour
fontshadow None font shadow color, default is None(no shadow)
markup False Whether or not to use pango markup
class libqtile.widget.GenPollText(**config)[source]

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

key default description
poll None Poll Function
class libqtile.widget.GenPollUrl(**config)[source]

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

key default description
url None Url
data None Post Data
parse None Parse Function
json True Is Json?
user_agent 'Qtile' Set the user agent
headers {} Extra Headers
class libqtile.widget.GmailChecker(settings=None, **config)[source]

A simple gmail checker.

key default description
update_interval 30 Update time in seconds.
username None username
password None password
email_path 'INBOX' email_path
fmt 'inbox[%s],unseen[%s]' fmt
status_only_unseen False Only show unseen messages
class libqtile.widget.GroupBox(**config)[source]

A widget that graphically displays the current group.

key default description
active 'FFFFFF' Active group font colour
inactive '404040' Inactive group font colour
urgent_text 'FF0000' Urgent group font color
highlight_method 'border' Method of highlighting (one of ‘border’ or ‘block’) Uses *_border color settings
rounded True To round or not to round borders
this_current_screen_border '215578' Border colour for group on this screen when focused.
urgent_alert_method 'border' Method for alerting you of WM urgent hints (one of ‘border’, ‘text’ or ‘block’)
disable_drag False Disable dragging and dropping of group names on widget
this_screen_border '215578' Border colour for group on this screen.
other_screen_border '404040' Border colour for group on other screen.
urgent_border 'FF0000' Urgent border color
invert_mouse_wheel False Whether to invert mouse wheel group movement
class libqtile.widget.HDDBusyGraph(**config)[source]

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

key default description
device 'sda' Block device to display info for
class libqtile.widget.HDDGraph(**config)[source]

Display HDD free or used space graph.

key default description
path '/' Partition mount point.
space_type 'used' free/used
class libqtile.widget.Image(width=CALCULATED, **config)[source]

Display a PNG image on the bar.

key default description
scale True Enable/Disable image scaling
filename None PNG Image filename. Can contain ‘~’
class libqtile.widget.KeyboardLayout(**config)[source]

Widget for changing and displaying the current keyboard layout. It requires setxkbmap to be available in the sytem.

key default description
update_interval 1 Update time in seconds.
configured_keyboards 'us' A list of predefined keyboard layouts represented as strings. For example: [‘us’, ‘us colemak’, ‘es’, ‘fr’].
class libqtile.widget.Maildir(maildirPath=None, subFolders=None, separator=' ', **config)[source]

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

key default description
maildirPath '~/Mail' path to the Maildir folder
subFolders [] The subfolders to scan (e.g. [{“path”: “INBOX”, “label”: “Home mail”}, {“path”: “spam”, “label”: “Home junk”}]
separator ' ' the string to put between the subfolder strings.
class libqtile.widget.MemoryGraph(**config)[source]

Displays a memory usage graph.

key default description
graph_color '18BAEB' Graph color
fill_color '1667EB.3' Fill color for linefill graph
border_color '215578' Widget border color
border_width 2 Widget border width
margin_x 3 Margin X
margin_y 3 Margin Y
samples 100 Count of graph samples.
frequency 1 Update frequency in seconds
type 'linefill' ‘box’, ‘line’, ‘linefill’
line_width 3 Line width
start_pos 'bottom' Drawer starting position (‘bottom’/’top’)
class libqtile.widget.Net(**config)[source]

Displays interface down and up speed.

key default description
interface 'wlan0' The interface to monitor
update_interval 1 The update interval.
class libqtile.widget.NetGraph(**config)[source]

Display a network usage graph.

key default description
interface 'auto' Interface to display info for (‘auto’ for detection)
bandwidth_type 'down' down(load)/up(load)
class libqtile.widget.Notify(width=CALCULATED, **config)[source]

A notify widget

key default description
foreground_urgent 'ff0000' Foreground urgent priority colour
foreground_low 'dddddd' Foreground low priority colour
default_timeout None Default timeout (seconds) for notifications
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.

key default description
unavailable 'ffffff' Unavailable Color - no updates.
execute None Command to execute on click
update_interval 60 The update interval.
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.

key default description
cursorblink 0.5 Cursor blink rate. 0 to disable.
prompt '{prompt}: ' Text displayed at the prompt
class libqtile.widget.Sep(**config)[source]

A visible widget separator.

key default description
padding 2 Padding on either side of separator.
linewidth 1 Width of separator line.
foreground '888888' Separator line colour.
height_percent 80 Height as a percentage of bar height (0-100).
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.

key default description
device '/sys/devices/platform/eeepc/cpufv' sys path to cpufv
format 'speed' Type of info to display “speed” or “name”
update_interval 0.5 Update Time in seconds.
class libqtile.widget.Spacer(width=STRETCH)[source]

Just an empty space on the bar. Often used with width equal to bar.STRETCH to push bar widgets to the right edge of the screen.

key default description
background None Widget background color
__init__(width=STRETCH)[source]
  • width: Width of the widget. Can be either bar.STRETCH or a width in pixels.
class libqtile.widget.SwapGraph(**config)[source]

Display a swap info graph.

key default description
graph_color '18BAEB' Graph color
fill_color '1667EB.3' Fill color for linefill graph
border_color '215578' Widget border color
border_width 2 Widget border width
margin_x 3 Margin X
margin_y 3 Margin Y
samples 100 Count of graph samples.
frequency 1 Update frequency in seconds
type 'linefill' ‘box’, ‘line’, ‘linefill’
line_width 3 Line width
start_pos 'bottom' Drawer starting position (‘bottom’/’top’)
class libqtile.widget.Systray(**config)[source]

A widget that manage system tray

key default description
icon_size 20 Icon width
padding 5 Padding between icons
class libqtile.widget.TaskList(**config)[source]
key default description
font 'Arial' Default font
fontsize None Font size. Calculated if None.
foreground 'ffffff' Foreground colour
fontshadow None font shadow color, default is None(no shadow)
borderwidth 2 Current group border width
border '215578' Border colour
rounded True To round or not to round borders
highlight_method 'border' Method of highlighting (one of ‘border’ or ‘block’) Uses *_border color settings
urgent_border 'FF0000' Urgent border color
urgent_alert_method 'border' Method for alerting you of WM urgent hints (one of ‘border’ or ‘text’)
max_title_width 200 size in pixels of task title
class libqtile.widget.TextBox(text=' ', width=CALCULATED, **config)[source]

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

key default description
font 'Arial' Text font
fontsize None Font pixel size. Calculated if None.
fontshadow None font shadow color, default is None(no shadow)
padding None Padding left and right. Calculated if None.
foreground '#ffffff' Foreground colour.
class libqtile.widget.ThermalSensor(**config)[source]

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.

key default description
metric True True to use metric/C, False to use imperial/F
show_tag False Show tag sensor
update_interval 2 Update interval in seconds
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
foreground_alert 'ff0000' Foreground colour alert
class libqtile.widget.Volume(**config)[source]

Widget that display and change volume if theme_path is set it draw widget as icons

key default description
cardid 0 Card Id
channel 'Master' Channel
padding 3 Padding left and right. Calculated if None.
theme_path None Path of the icons
update_interval 0.2 Update time in seconds.
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.
mute_command None Mute command
volume_up_command None Volume up command
volume_down_command None Volume down command
get_volume_command None Command to get the current volume
class libqtile.widget.WindowName(width=STRETCH, **config)[source]

Displays the name of the window that currently has focus.

key default description
font 'Arial' Default font
fontsize None Font size. Calculated if None.
padding None Padding. Calculated if None.
foreground 'ffffff' Foreground colour
fontshadow None font shadow color, default is None(no shadow)
markup False Whether or not to use pango markup
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.

key default description
separator ' | ' Task separator text.
selected ('<', '>') Selected task indicator
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
key default description
location None Location to fetch weather for. Ignored if woeid is set.
woeid None Where On Earth ID. Auto-calculated if location is set.
format '{location_city}: {condition_temp} \xc2\xb0{units_temperature}' Display format
metric True True to use metric/C, False to use imperial/F
up '^' symbol for rising atmospheric pressure
down 'v' symbol for falling atmospheric pressure
steady 's' symbol for steady atmospheric pressure