Using py3status, you can take control of your i3bar easily by:
No extra configuration file needed, just install & enjoy!
"},{"location":"#about","title":"About","text":"You will love py3status if you're using i3wm (or sway) and are frustrated by the i3status limitations on your i3bar such as:
We apply the zen to improve this project and encourage everyone to read it!
"},{"location":"#need-help","title":"Need help?","text":"Get help, share ideas or feedback, join community, report bugs, or others, see:
"},{"location":"#github","title":"GitHub","text":"Join us on #py3status at oftc.net
"},{"location":"getting-started/","title":"Getting Started","text":"Install py3status then in your i3 config file, simply switch from i3status to py3status in your status_command option:
status_command py3status\nUsually you have your own i3status configuration, just point to it:
status_command py3status -c ~/.config/i3status/config\nYou can get a list with short descriptions of all available modules by using the CLI:
$ py3-cmd list --all\nTo get more details about all available modules and their configuration, use:
$ py3-cmd list --all --full\nAll modules shipped with py3status are present as the Python source files in the py3status/modules directory.
Check out the py3status user configuration guide to learn how to add, order and configure modules!
"},{"location":"getting-started/#py3status-options","title":"Py3status options","text":"You can see the help of py3status by issuing py3status --help:
$ py3status --help\n\nusage: py3status [-h] [-b] [-c FILE] [-d] [-g] [-i PATH] [-l FILE] [-s]\n [-t INT] [-m] [-u PATH] [-v] [--wm WINDOW_MANAGER]\n\nThe agile, python-powered, i3status wrapper\n\noptional arguments:\n -h, --help show this help message and exit\n -b, --dbus-notify send notifications via dbus instead of i3-nagbar\n (default: False)\n -c, --config FILE load config (default: /home/alexys/.i3/i3status.conf)\n -d, --debug enable debug logging in syslog and --log-file\n (default: False)\n -i, --include PATH append additional user-defined module paths (default:\n None)\n -l, --log-file FILE enable logging to FILE (default: None)\n -s, --standalone run py3status without i3status (default: False)\n -t, --timeout INT default module cache timeout in seconds (default: 60)\n -m, --disable-click-events\n disable all click events (default: False)\n -u, --i3status PATH specify i3status path (default: /usr/bin/i3status)\n -v, --version show py3status version and exit (default: False)\n --wm WINDOW_MANAGER specify window manager i3 or sway (default: i3)\nPy3status is very open and flexible, check out the complete user guide to get more intimate with it:
Contributions to py3status including documentation, the core code, or for new or existing modules are very welcome.
Please read carefully the zen describing the minimal things to keep in mind when contributing or participating to this project.
Feel free to open an issue to propose your ideas as request for comments [RFC] and to join us on IRC OFTC #py3status channel for a live chat.
To make a contribution please create a pull request.
Any functional change should be done via pull requests, even by people with push access.
Each PR requires at least one approval from project maintainers before a PR can be merged.
"},{"location":"dev-guide/contributing/#zen-of-py3status","title":"Zen of py3status","text":""},{"location":"dev-guide/contributing/#efficient-and-simple-defaults","title":"efficient and simple defaults","text":"We like py3status because it's a drop-in replacement of i3status. i3 users don't expect fancy and magical things, they use i3 because it's simple and efficient. Keep configuration options and default formats as simple as possible
"},{"location":"dev-guide/contributing/#its-not-because-you-can-that-you-should","title":"it's not because you can that you should","text":"On modules, expose things that you WILL use, not things that you COULD use. On core, make features and options as seamless as possible (lazy loading) with sane defaults and no mandatory requirements.
"},{"location":"dev-guide/contributing/#good-enough-is-good-enough","title":"good enough is good enough","text":"Strive for and accept \"good enough\" features / proposals. We shall refrain from refining indefinitely.
"},{"location":"dev-guide/contributing/#one-featureidea-at-a-time","title":"one feature/idea at a time","text":"Trust and foster iteration with your peers by refraining from digressions. Keep discussions focused on the initial topic and easy to get into. Proposals should not contain multiple features or corrections at once.
"},{"location":"dev-guide/contributing/#modules-are-responsible-for-user-information-and-interactions","title":"modules are responsible for user information and interactions","text":"That is what's written in the bar and its behavior on clicks etc.
"},{"location":"dev-guide/contributing/#core-is-responsible-for-user-experience","title":"core is responsible for user experience","text":"Core features and configuration options should focus on user experience. Things that are related to the general output of the bar are handled by core. Smart things overlaying modules (such as standardized options) should also end up in the core.
"},{"location":"dev-guide/contributing/#rely-on-i3status-color-scheme","title":"rely on i3status color scheme","text":"No fancy colors by default, only i3status good/degraded/bad. If we want to provide enhanced coloring, this should be through a core feature such as thresholds.
"},{"location":"dev-guide/contributing/#rely-on-the-i3bar-protocol","title":"rely on the i3bar protocol","text":"what's possible with it, we should support and offer.
"},{"location":"dev-guide/contributing/#what-you-will-need","title":"What you will need","text":"i3status:
pytest pytest-flake8:
black:
tox:
First clone the git repository
# using https\n$ git clone https://github.com/ultrabug/py3status.git\n\n# using ssh (needs github account)\n$ git clone git@github.com:ultrabug/py3status.git\nRun setup.py to install
# cd to the directory containing setup.py\n$ cd py3status\n\n# install you may need to use sudo to have required permissions\n$ pip install -e .\nyou can now run py3status and any changes to the code you make will be available after a reload.
Note
py3status will only be installed for the version of python that you used to run setup.py.
If you wish to have multiple versions available. First run setup.py develop using the required python versions. Next copy the executable eg sudo cp /usr/bin/py3status /usr/bin/py3status2 Then edit the hashbang to point to your chosen python version.
Starting with version 3.26, py3status will only run using python 3.
"},{"location":"dev-guide/contributing/#documentation","title":"Documentation","text":"Documentation pages are located under the docs/ folder.
To run the documentation site locally (useful for previewing changes), use:
# you need to install hatch\n# pip install --user hatch\nhatch -e docs mkdocs serve\nPy3status uses tox for testing. All submissions to the project must pass testing. To install these via pip use
$ pip install pytest\n$ pip install pytest-flake8\n$ pip install tox\n$ pip install black # needs python 3.6+\nThe tests can be run by using tox in the py3status root directory.
Tests are kept in the tests directory.
When you create your Pull Request, checks from the Github Actions CI will automatically run.
If something fails in the CI:
Warning, by default (at least on Archlinux), i3status has cap_net_admin capabilities, which will make it fail with operation not permitted when running inside a Docker container.
$ getcap `which i3status`\n/usr/sbin/i3status = cap_net_admin+ep\nTo allow it to run without these capabilities (hence disabling some of the functionalities), remove it with:
$ sudo setcap -r `which i3status`\nA small tool to measure py3status performance between changes and allows testing of old versions, etc. It's a little clunky but it does the job. https://github.com/tobes/py3status-profiler
# pprofile\nRunning tests for 10 minutes.\n[\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588] 100.00% 10:00 (22.12)\nuser 21.41s\nsystem 0.71s\ntotal 22.12s\n\n# vmprof\nRunning tests for 10 minutes.\n[\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588] 100.00% 10:00 (2.10)\nuser 1.77s\nsystem 0.33s\ntotal 2.1s\n\n# cprofile\nRunning tests for 10 minutes.\n[\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588] 100.00% 10:00 (0.92)\nuser 0.87s\nsystem 0.05s\ntotal 0.92\nThe Py3 module is a special helper object that gets injected into py3status modules, providing extra functionality. A module can access it via the self.py3 instance attribute of its py3status class.
Special constant that when returned for cached_until will cause the module to not update unless externally triggered.
Show as Error
"},{"location":"dev-guide/the-py3-helper/#log_info","title":"LOG_INFO","text":"Show as Informational
"},{"location":"dev-guide/the-py3-helper/#log_warning","title":"LOG_WARNING","text":"Show as Warning
"},{"location":"dev-guide/the-py3-helper/#exceptions","title":"Exceptions","text":""},{"location":"dev-guide/the-py3-helper/#commanderror","title":"CommandError","text":"An error occurred running the given command.
This exception provides some additional attributes
error_code: The error code returned from the call
output: Any output returned by the call
error: Any error output returned by the call
Base Py3 exception class. All custom Py3 exceptions derive from this class.
"},{"location":"dev-guide/the-py3-helper/#requestexception","title":"RequestException","text":"A Py3.request() base exception. This will catch any of the more specific exceptions.
"},{"location":"dev-guide/the-py3-helper/#requestinvalidjson","title":"RequestInvalidJSON","text":"The request has not returned valid JSON
"},{"location":"dev-guide/the-py3-helper/#requesttimeout","title":"RequestTimeout","text":"A timeout has occurred during a request made via Py3.request().
"},{"location":"dev-guide/the-py3-helper/#requesturlerror","title":"RequestURLError","text":"A URL related error has occurred during a request made via Py3.request().
"},{"location":"dev-guide/the-py3-helper/#methods","title":"Methods","text":""},{"location":"dev-guide/the-py3-helper/#check_commandscmd_list","title":"check_commands(cmd_list)","text":"Checks to see if commands in list are available using shutil.which().
returns the first available command.
If a string is passed then that command will be checked for.
"},{"location":"dev-guide/the-py3-helper/#command_outputcommand-shellfalse-capture_stderrfalse-localizedfalse","title":"command_output(command, shell=False, capture_stderr=False, localized=False)","text":"Run a command and return its output as unicode. The command can either be supplied as a sequence or string.
:param command: command to run can be a str or list :param shell: if True then command is run through the shell :param capture_stderr: if True then STDERR is piped to STDOUT :param localized: if False then command is forced to use its default (English) locale
A CommandError is raised if an error occurs
"},{"location":"dev-guide/the-py3-helper/#command_runcommand","title":"command_run(command)","text":"Runs a command and returns the exit code. The command can either be supplied as a sequence or string.
An Exception is raised if an error occurs
"},{"location":"dev-guide/the-py3-helper/#composite_createitem","title":"composite_create(item)","text":"Create and return a Composite.
The item may be a string, dict, list of dicts or a Composite.
"},{"location":"dev-guide/the-py3-helper/#composite_joinseparator-items","title":"composite_join(separator, items)","text":"Join a list of items with a separator. This is used in joining strings, responses and Composites.
A Composite object will be returned.
"},{"location":"dev-guide/the-py3-helper/#composite_updateitem-update_dict-softfalse","title":"composite_update(item, update_dict, soft=False)","text":"Takes a Composite (item) if item is a type that can be converted into a Composite then this is done automatically. Updates all entries it the Composite with values from update_dict. Updates can be soft in which case existing values are not overwritten.
A Composite object will be returned.
"},{"location":"dev-guide/the-py3-helper/#errormsg-timeoutnone","title":"error(msg, timeout=None)","text":"Raise an error for the module.
:param msg: message to be displayed explaining the error :param timeout: how long before we should retry. For permanent errors py3.CACHE_FOREVER should be returned. If not supplied then the modules cache_timeout will be used.
Flatten a dictionary.
Values that are dictionaries are flattened using delimiter in between (eg. parent-child)
Values that are lists are flattened using delimiter followed by the index (eg. parent-0)
example:
{\n 'fish_facts': {\n 'sharks': 'Most will drown if they stop moving',\n 'skates': 'More than 200 species',\n },\n 'fruits': ['apple', 'peach', 'watermelon'],\n 'number': 52\n}\n\n# becomes\n\n{\n 'fish_facts-sharks': 'Most will drown if they stop moving',\n 'fish_facts-skates': 'More than 200 species',\n 'fruits-0': 'apple',\n 'fruits-1': 'peach',\n 'fruits-2': 'watermelon',\n 'number': 52\n}\n\n# if intermediates is True then we also get unflattened elements\n# as well as the flattened ones.\n\n{\n 'fish_facts': {\n 'sharks': 'Most will drown if they stop moving',\n 'skates': 'More than 200 species',\n },\n 'fish_facts-sharks': 'Most will drown if they stop moving',\n 'fish_facts-skates': 'More than 200 species',\n 'fruits': ['apple', 'peach', 'watermelon'],\n 'fruits-0': 'apple',\n 'fruits-1': 'peach',\n 'fruits-2': 'watermelon',\n 'number': 52\n}\nDetermines if format_string contains a placeholder string names or a list of placeholders names.
names is tested against placeholders using fnmatch so the following patterns can be used:
* matches everything\n? matches any single character\n[seq] matches any character in seq\n[!seq] matches any character not in seq\nThis is useful because a simple test like '{placeholder}' in format_string will fail if the format string contains placeholder formatting eg '{placeholder:.2f}'
Takes a value and formats it for user output, we can choose the unit to use eg B, MiB, kbits/second. This is mainly for use with bytes/bits it converts the value into a human readable form. It has various additional options but they are really only for special cases.
The function returns a tuple containing the new value (this is a number so that the user can still format it if required) and a unit that is the units that we have been converted to.
By supplying unit to the function we can force those units to be used eg unit=KiB would force the output to be in Kibibytes. By default we use non-si units but if the unit is si eg kB then we will switch to si units. Units can also be things like Mbit/sec.
If the auto parameter is False then we use the unit provided. This only makes sense when the unit is singular eg 'Bytes' and we want the result in bytes and not say converted to MBytes.
optimal is used to control the size of the output value. We try to provide an output value of that number of characters (including decimal point), it may also be less due to rounding. If a fixed unit is used the output may be more than this number of characters.
"},{"location":"dev-guide/the-py3-helper/#get_color_names_listformat_string-matchesnone","title":"get_color_names_list(format_string, matches=None)","text":"Returns a list of color names in format_string.
If matches is provided then it is used to filter the result using fnmatch so the following patterns can be used:
* matches everything\n? matches any single character\n[seq] matches any character in seq\n[!seq] matches any character not in seq\nReturn a string from a Composite.
"},{"location":"dev-guide/the-py3-helper/#get_outputmodule_name","title":"get_output(module_name)","text":"Return the output of the named module. This will be a list.
"},{"location":"dev-guide/the-py3-helper/#get_placeholder_formats_listformat_string","title":"get_placeholder_formats_list(format_string)","text":"Parses the format_string and returns a list of tuples [(placeholder, format), ...].
eg '{placeholder:.2f}' will give [('placeholder', ':.2f')]
Returns a list of placeholders in format_string.
If matches is provided then it is used to filter the result using fnmatch so the following patterns can be used:
* matches everything\n? matches any single character\n[seq] matches any character in seq\n[!seq] matches any character not in seq\nThis is useful because we just get simple placeholder without any formatting that may be applied to them eg '{placeholder:.2f}' will give ['{placeholder}']
Return the control program of the current window manager.
On i3, will return \"i3-msg\" On sway, will return \"swaymsg\"
"},{"location":"dev-guide/the-py3-helper/#i3s_config","title":"i3s_config()","text":"returns the i3s_config dict.
"},{"location":"dev-guide/the-py3-helper/#is_colorcolor","title":"is_color(color)","text":"Tests to see if a color is defined. Because colors can be set to None in the config and we want this to be respected in an expression like.
color = self.py3.COLOR_MUTED or self.py3.COLOR_BAD\nThe color is treated as True but sometimes we want to know if the color has a value set in which case the color should count as False. This function is a helper for this second case.
"},{"location":"dev-guide/the-py3-helper/#is_compositeitem","title":"is_composite(item)","text":"Check if item is a Composite and return True if it is.
"},{"location":"dev-guide/the-py3-helper/#is_my_eventevent","title":"is_my_event(event)","text":"Checks if an event triggered belongs to the module receiving it. This is mainly for containers who will also receive events from any children they have.
Returns True if the event name and instance match that of the module checking.
"},{"location":"dev-guide/the-py3-helper/#logmessage-levelinfo","title":"log(message, level='info')","text":"Log the message. The level must be one of LOG_ERROR, LOG_INFO or LOG_WARNING
"},{"location":"dev-guide/the-py3-helper/#notify_usermsg-levelinfo-rate_limit5-titlenone-iconnone","title":"notify_user(msg, level='info', rate_limit=5, title=None, icon=None)","text":"Send a notification to the user. level must be 'info', 'error' or 'warning'. rate_limit is the time period in seconds during which this message should not be repeated. icon must be an icon path or icon name.
"},{"location":"dev-guide/the-py3-helper/#play_soundsound_file","title":"play_sound(sound_file)","text":"Plays sound_file if possible.
"},{"location":"dev-guide/the-py3-helper/#prevent_refresh","title":"prevent_refresh()","text":"Calling this function during the on_click() method of a module will request that the module is not refreshed after the event. By default the module is updated after the on_click event has been processed.
"},{"location":"dev-guide/the-py3-helper/#register_functionfunction_name-function","title":"register_function(function_name, function)","text":"Register a function for the module.
The following functions can be registered:
"},{"location":"dev-guide/the-py3-helper/#content_function","title":"content_function()","text":"Called to discover what modules a container is displaying. This is used to determine when updates need passing on to the container and also when modules can be put to sleep.
the function must return a set of module names that are being displayed.
Note
This function should only be used by containers.
"},{"location":"dev-guide/the-py3-helper/#urgent_functionmodule_names","title":"urgent_function(module_names)","text":"This function will be called when one of the contents of a container has changed from a non-urgent to an urgent state. It is used by the group module to switch to displaying the urgent module.
module_names is a list of modules that have become urgent
Note
This function should only be used by containers.
"},{"location":"dev-guide/the-py3-helper/#requesturl-paramsnone-datanone-headersnone-timeoutnone-authnone-cookiejarnone-retry_timesnone-retry_waitnone","title":"request(url, params=None, data=None, headers=None, timeout=None, auth=None, cookiejar=None, retry_times=None, retry_wait=None)","text":"Make a request to a url and retrieve the results.
If the headers parameter does not provide an 'User-Agent' key, one will be added automatically following the convention:
py3status/<version> <per session random uuid>\nhttp://example.com(username, password)returns: HttpResponse
"},{"location":"dev-guide/the-py3-helper/#safe_formatformat_string-param_dictnone-force_compositefalse-attr_getternone-max_widthnone","title":"safe_format(format_string, param_dict=None, force_composite=False, attr_getter=None, max_width=None)","text":"Parser for advanced formatting.
Unknown placeholders will be shown in the output eg {foo}.
Square brackets [] can be used. The content of them will be removed from the output if there is no valid placeholder contained within. They can also be nested.
A pipe (vertical bar) | can be used to divide sections the first valid section only will be shown in the output.
A backslash \\ can be used to escape a character eg \\[ will show [ in the output.
\\? is special and is used to provide extra commands to the format string, example \\?color=#FF00FF. Multiple commands can be given using an ampersand & as a separator, example \\?color=#FF00FF&show.
\\?if=<placeholder> can be used to check if a placeholder exists. An exclamation mark ! after the equals sign = can be used to negate the condition.
\\?if=<placeholder>=<value> can be used to determine if {} would be replaced with . [] in don't need to be escaped.
{<placeholder>} will be converted, or removed if it is None or empty. Formatting can also be applied to the placeholder Eg {number:03.2f}.
example format_string:
\"[[{artist} - ]{title}]|{file}\" This will show artist - title if artist is present, title if title but no artist, and file if file is present but not artist or title.
param_dict is a dictionary of placeholders that will be substituted. If a placeholder is not in the dictionary then if the py3status module has an attribute with the same name then it will be used.
Composites can be included in the param_dict.
The result returned from this function can either be a string in the case of simple parsing or a Composite if more complex.
If force_composite parameter is True a composite will always be returned.
attr_getter is a function that will when called with an attribute name as a parameter will return a value.
max_width lets you to control the total max width of 'full_text' the module is allowed to output on the bar.
"},{"location":"dev-guide/the-py3-helper/#stop_sound","title":"stop_sound()","text":"Stops any currently playing sounds for this module.
"},{"location":"dev-guide/the-py3-helper/#storage_delkeynone","title":"storage_del(key=None)","text":"Remove the value stored with the key from storage. If key is not supplied then all values for the module are removed.
"},{"location":"dev-guide/the-py3-helper/#storage_getkey","title":"storage_get(key)","text":"Retrieve a value for the module.
"},{"location":"dev-guide/the-py3-helper/#storage_items","title":"storage_items()","text":"Return key, value pairs of the stored data for the module.
Keys will contain the following metadata entries: - '_ctime': storage creation timestamp - '_mtime': storage last modification timestamp
"},{"location":"dev-guide/the-py3-helper/#storage_keys","title":"storage_keys()","text":"Return a list of the keys for values stored for the module.
Keys will contain the following metadata entries: - '_ctime': storage creation timestamp - '_mtime': storage last modification timestamp
"},{"location":"dev-guide/the-py3-helper/#storage_setkey-value","title":"storage_set(key, value)","text":"Store a value for the module.
"},{"location":"dev-guide/the-py3-helper/#threshold_get_colorvalue-namenone","title":"threshold_get_color(value, name=None)","text":"Obtain color for a value using thresholds.
The value will be checked against any defined thresholds. These should have been set in the i3status configuration. If more than one threshold is needed for a module then the name can also be supplied. If the user has not supplied a named threshold but has defined a general one that will be used.
If the gradients config parameter is True then rather than sharp thresholds we will use a gradient between the color values.
Returns the time a given number of seconds into the future. Helpful for creating the cached_until value for the module output.
Note
from version 3.1 modules no longer need to explicitly set a cached_until in their response unless they wish to directly control it.
seconds: specifies the number of seconds that should occur before the update is required. Passing a value of CACHE_FOREVER returns CACHE_FOREVER which can be useful for some modules.
sync_to: causes the update to be synchronized to a time period. 1 would cause the update on the second, 60 to the nearest minute. By default we synchronize to the nearest second. 0 will disable this feature.
offset: is used to alter the base time used. A timer that started at a certain time could set that as the offset and any synchronization would then be relative to that time.
Trigger an event on a named module.
"},{"location":"dev-guide/the-py3-helper/#updatemodule_namenone","title":"update(module_name=None)","text":"Update a module. If module_name is supplied the module of that name is updated. Otherwise the module calling is updated.
"},{"location":"dev-guide/the-py3-helper/#update_placeholder_formatsformat_string-formats","title":"update_placeholder_formats(format_string, formats)","text":"Update a format string adding formats if they are not already present. This is useful when for example a placeholder has a floating point value but by default we only want to show it to a certain precision.
"},{"location":"dev-guide/writing-modules/","title":"Writing custom py3status modules","text":"Writing custom modules for py3status is as easy as declaring a Python class. This guide will teach you how.
"},{"location":"dev-guide/writing-modules/#importing-custom-modules","title":"Importing custom modules","text":"First of all, it is important to know that py3status will try to find your custom modules in the following locations:
~/.config/py3status/modules~/.config/i3status/py3status~/.config/i3/py3status~/.i3/py3statuswhich if you are used to XDG_CONFIG paths relates to:
XDG_CONFIG_HOME/py3status/modulesXDG_CONFIG_HOME/i3status/py3statusXDG_CONFIG_HOME/i3/py3status~/.i3/py3statusYou can also specify the modules location using py3status -i <path to custom modules directory> in your i3 configuration file.
Now let's start by looking at a simple example.
Here we start with the most basic module that just outputs a static string to the status bar.
# -*- coding: utf-8 -*-\n\"\"\"\nExample module that says 'Hello World!'\n\nThis demonstrates how to produce a simple custom module.\n\"\"\"\n\n\nclass Py3status:\n\n def hello_world(self):\n return {\n 'full_text': 'Hello World!',\n 'cached_until': self.py3.CACHE_FOREVER\n }\nSave the file as hello_world.py in a directory that py3status will check for modules. By default it will look in $HOME/.i3/py3status/ or you can specify additional directories using --include when you run py3status.
You need to tell py3status about your new module, so in your i3status.conf add:
order += \"hello_world\"\nThen restart i3 by pressing Mod + Shift + R. Your new module should now show up in the status bar.
The Py3status class tells py3status that this is a module. The module gets loaded. py3status then calls any public methods that the class contains to get a response. In our example there is a single method hello_world(). Read more here: module methods.
The response that a method returns must be a python dict. It should contain at least two key / values.
This is the text that will be displayed in the status bar.
"},{"location":"dev-guide/writing-modules/#cached_until","title":"cached_until","text":"This tells py3status how long it should consider your response valid before it should re-run the method to get a fresh response. In our example our response will not need to be updated so we can use the special self.py3.CACHE_FOREVER constant. This tells py3status to consider our response always valid.
cached_until should be generated via the self.py3.time_in() method.
This is a special object that gets injected into py3status modules. It helps provide functionality for the module, such as the CACHE_FOREVER constant. Read more about the py3.
Allow users to supply configuration to a module.
# -*- coding: utf-8 -*-\n\"\"\"\nExample module that says 'Hello World!' that can be customised.\n\nThis demonstrates how to use configuration parameters.\n\nConfiguration parameters:\n format: Display format (default 'Hello World!')\n\"\"\"\n\n\nclass Py3status:\n\n format = 'Hello World!'\n\n def hello_world(self):\n return {\n 'full_text': self.format,\n 'cached_until': self.py3.CACHE_FOREVER\n }\nThis module still outputs 'Hello World' as before but now you can customise the output using your i3status.config for example to show the text in French.
hello_world {\n format = 'Bonjour tout le monde!'\n}\nIn your module self.format will have been set to the value supplied in the config.
Catch click events and perform an action.
# -*- coding: utf-8 -*-\n\"\"\"\nExample module that handles events\n\nThis demonstrates how to use events.\n\"\"\"\n\n\nclass Py3status:\n\n def __init__(self):\n self.full_text = 'Click me'\n\n def click_info(self):\n return {\n 'full_text': self.full_text,\n 'cached_until': self.py3.CACHE_FOREVER\n }\n\n def on_click(self, event):\n \"\"\"\n event will be a dict like\n {'y': 13, 'x': 1737, 'button': 1, 'name': 'example', 'instance': 'first'}\n \"\"\"\n button = event['button']\n # update our output (self.full_text)\n format_string = 'You pressed button {button}'\n data = {'button': button}\n self.full_text = self.py3.safe_format(format_string, data)\n # Our modules update methods will get called automatically.\nThe on_click method of a module is special and will get called when the module is clicked on. The event parameter will be a dict that gives information about the event.
A typical event dict will look like this: {'y': 13, 'x': 1737, 'button': 1, 'name': 'example', 'instance': 'first'}
You should only receive events for the module clicked on, so generally we only care about the button.
The __init__() method is called when our class is instantiated.
Note
init is called before any config parameters have been set.
We use the safe_format() method of py3 for formatting. Read more about the py3.
Status string placeholders allow us to add information to formats.
# -*- coding: utf-8 -*-\n\"\"\"\nExample module that demonstrates status string placeholders\n\nConfiguration parameters:\n format: Initial format to use\n (default 'Click me')\n format_clicked: Display format to use when we are clicked\n (default 'You pressed button {button}')\n\nFormat placeholders:\n {button} The button that was pressed\n\"\"\"\n\n\nclass Py3status:\n format = 'Click me'\n format_clicked = 'You pressed button {button}'\n\n def __init__(self):\n self.button = None\n\n def click_info(self):\n if self.button:\n data = {'button': self.button}\n full_text = self.py3.safe_format(self.format_clicked, data)\n else:\n full_text = self.format\n\n return {\n 'full_text': full_text,\n 'cached_until': self.py3.CACHE_FOREVER\n }\n\n def on_click(self, event):\n \"\"\"\n event will be a dict like\n {'y': 13, 'x': 1737, 'button': 1, 'name': 'example', 'instance': 'first'}\n \"\"\"\n self.button = event['button']\n # Our modules update methods will get called automatically.\nThis works just like the previous example but we can now be customised. The following example assumes that our module has been saved as click_info.py.
click_info {\n format = \"Cliquez ici\"\n format_clicked = \"Vous avez appuy\u00e9 sur le bouton {button}\"\n}\nself.py3 in our module has color constants that we can access, these allow the user to set colors easily in their config.
# -*- coding: utf-8 -*-\n\"\"\"\nExample module that uses colors.\n\nWe generate a random number between and color it depending on its value.\nClicking on the module will update it an a new number will be chosen.\n\nConfiguration parameters:\n format: Initial format to use\n (default 'Number {number}')\n\nFormat placeholders:\n {number} Our random number\n\nColor options:\n color_high: number is 5 or higher\n color_low: number is less than 5\n\"\"\"\n\nfrom random import randint\n\n\nclass Py3status:\n format = 'Number {number}'\n\n def random(self):\n number = randint(0, 9)\n full_text = self.py3.safe_format(self.format, {'number': number})\n\n if number < 5:\n color = self.py3.COLOR_LOW\n else:\n color = self.py3.COLOR_HIGH\n\n return {\n 'full_text': full_text,\n 'color': color,\n 'cached_until': self.py3.CACHE_FOREVER\n }\n\n def on_click(self, event):\n # by defining on_click pressing any mouse button will refresh the\n # module.\n pass\nThe colors can be set in the config in the module or its container or in the general section. The following example assumes that our module has been saved as number.py. Although the constants are capitalized they are defined in the config in lower case.
number {\n color_high = '#FF0000'\n color_low = '#00FF00'\n}\nPy3status will call a method in a module to provide output to the i3bar. Methods that have names starting with an underscore will not be used in this way. Any methods defined as static methods will also not be used.
"},{"location":"dev-guide/writing-modules/#outputs","title":"Outputs","text":"Output methods should provide a response dict.
Example response:
{\n 'full_text': \"This text will be displayed\",\n 'cached_until': 1470922537, # Time in seconds since the epoch\n}\nThe response can include the following keys
cached_until
The time (in seconds since the epoch) that the output will be classed as no longer valid and the output function will be called again.
Since version 3.1, if no cached_until value is provided the output will be cached for cache_timeout seconds by default this is 60 and can be set using the -t or --timeout option when running py3status. To never expire the self.py3.CACHE_FOREVER constant should be used.
cached_until should be generated via the self.py3.time_in() method.
color
The color that the module output will be displayed in.
composite
Used to output more than one item to i3bar from a single output method. If this is provided then full_text should not be.
full_text
This is the text output that will be sent to i3bar.
index
The index of the output. Allows composite output to identify which component of their output had an event triggered.
separator
If False no separator will be shown after the output block (requires i3bar 4.12).
urgent
If True the output will be shown as urgent in i3bar.
Some special method are also defined.
kill()
Called just before a module is destroyed.
on_click(event)
Called when an event is received by a module.
post_config_hook()
Called once an instance of a module has been created and the configuration parameters have been set. This is useful for any work a module must do before its output methods are run for the first time. post_config_hook() introduced in version 3.1
Py3 is a special helper object that gets injected into py3status modules, providing extra functionality. A module can access it via the self.py3 instance attribute of its py3status class. For details see py3.
"},{"location":"dev-guide/writing-modules/#composites","title":"Composites","text":"Whilst most modules return a simple response eg:
{\n 'full_text': <some text>,\n 'cached_until': <cache time>,\n}\nSometimes it is useful to provide a more complex, composite response. A composite is made up of more than one simple response which allows for example a response that has multiple colors. Different parts of the response can also be differentiated between when a click event occurs and so allow clicking on different parts of the response to have different outcomes. The different parts of the composite will not have separators between them in the output so they will appear as a single module to the user.
The format of a composite is as follows:
{\n 'cached_until': <cache time>,\n 'composite': [\n {\n 'full_text': <some text>,\n },\n {\n 'full_text': <some more text>,\n 'index': <some index>\n },\n ]\n}\nThe index key in the response is used to identify the individual block and when the modules on_click() method is called the event will include this. Supplied index values should be strings. If no index is given then it will have an integer value indicating its position in the composite.
Py3status allows modules to maintain state through the use of the storage functions of the Py3 helper.
Currently bool, int, float, None, unicode, dicts, lists, datetimes etc are supported. Basically anything that can be pickled. We do our best to ensure that the resulting pickles are compatible with both python versions 2 and 3.
The following helper functions are defined in the modules py3.
These functions may return None if storage is not available as well as some metadata such as storage creation timestamp _ctime and last modification timestamp _mtime.
Example:
def module_function(self):\n # set some storage\n self.py3.storage_set('my_key', value)\n # get the value or None if key not present\n value = self.py3.storage_get('my_key')\nAll contributed modules should have correct documentation. This documentation is in a specific format and is used to generate user documentation.
The docstring of a module is used. The format is as follows:
(default 7).Here is an example of a docstring.
\"\"\"\nSingle line summary\n\nLonger description of the module. This should help users understand the\nmodules purpose.\n\nConfiguration parameters:\n parameter: Explanation of this parameter (default <value>)\n parameter_other: This parameter has a longer explanation that continues\n onto a second line so it is indented.\n (default <value>)\n\nFormat placeholders:\n {info} Description of the placeholder\n\nColor options:\n color_meaning: what this signifies, defaults to color_good\n color_meaning2: what this signifies\n\nRequires:\n program: Information about the program\n python_lib: Information on the library\n\nExample:\n\nmodule { parameter = \"Example\" parameter_other = 7 }
\n@author <author>\n@license <license>\n\"\"\"\nSometimes it is necessary to deprecate configuration parameters. Modules are able to specify information about deprecation so that it can be done automatically. Deprecation information is specified in the Meta class of a py3status module using the deprecated attribute. The following types of deprecation are supported.
The deprecation types will be performed in the order here.
rename
The parameter has been renamed. We will update the configuration to use the new name.
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'rename': [\n {\n 'param': 'format_available', # parameter name to be renamed\n 'new': 'icon_available', # the parameter that will get the value\n 'msg': 'obsolete parameter use `icon_available`', # message\n },\n ],\n }\nformat_fix_unnamed_param
Some formats used {} as a placeholder this needs to be updated to a named placeholder eg {value}.
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'format_fix_unnamed_param': [\n {\n 'param': 'format', # parameter to be changed\n 'placeholder': 'percent', # the place holder to use\n 'msg': '{} should not be used in format use `{percent}`', # message\n },\n ],\n }\nrename_placeholder
We can use this to rename placeholders in format strings
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'rename_placeholder': [\n {\n 'placeholder': 'cpu', # old placeholder name\n 'new': 'cpu_usage', # new placeholder name\n 'format_strings': ['format'], # config settings to update\n },\n ],\n }\nupdate_placeholder_format
This allows us to update the format of a placeholder in format strings. The key value pairs {placeholder: format} can be supplied as a dict in placeholder_formats or the dict can be provided by function the function will be called with the current config and must return a dict. If both are supplied then placeholder_formats will be updated using the dict supplied by the function.
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'update_placeholder_format': [\n {\n 'function': update_placeholder_format, # function returning dict\n 'placeholder_formats': { # dict of placeholder:format\n 'cpu_usage': ':.2f',\n },\n 'format_strings': ['format'], # config settings to update\n }\n ],\n }\nsubstitute_by_value
This allows one configuration parameter to set the value of another.
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'substitute_by_value': [\n {\n 'param': 'mode', # parameter to be checked for substitution\n 'value': 'ascii_bar', # value that will trigger the substitution\n 'substitute': {\n 'param': 'format', # parameter to be updated\n 'value': '{ascii_bar}', # the value that will be set\n },\n 'msg': 'obsolete parameter use `format = \"{ascii_bar}\"`', #message\n },\n ],\n }\nfunction
For more complex substitutions a function can be defined that will be called with the config as a parameter. This function must return a dict of key value pairs of parameters to update
class Py3status:\n\n class Meta:\n\n # Create a function to be called\n def deprecate_function(config):\n # This function must return a dict\n return {'thresholds': [\n (0, 'bad'),\n (config.get('threshold_bad', 20), 'degraded'),\n (config.get('threshold_degraded', 50), 'good'),\n ],\n }\n\n deprecated = {\n 'function': [\n {\n 'function': deprecate_function, # function to be called\n },\n ],\n }\nremove
The parameters will be removed.
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'remove': [\n {\n 'param': 'threshold_bad', # name of parameter to remove\n 'msg': 'obsolete set using thresholds parameter', #message\n },\n ],\n }\nSometimes it is necessary to update configuration parameters. Modules are able to specify information about updates so that it can be done automatically. Config updating information is specified in the Meta class of a py3status module using the update_config attribute. The following types of updates are supported.
update_placeholder_format
This allows us to update the format of a placeholder in format strings. The key value pairs {placeholder: format} can be supplied as a dict in placeholder_formats or the dict can be provided by function the function will be called with the current config and must return a dict. If both are supplied then placeholder_formats will be updated using the dict supplied by the function.
This is similar to the deprecation method but is to allow default formatting of placeholders to be set.
In a module like sysdata we have placeholders eg {cpu_usage} this ends up having a value something like 20.542317173377157 which is strange as the value to use but gives the user the ability to have as much precision as they want. A module writer may decide that they want this displayed as 20.54 so {cpu_usage:.2f} would do this. Having a default format containing that just looks long/silly and the user setting a custom format just wants to do format = 'CPU: {cpu_usage}%' and get expected results ie not the full precision. If they don't like the default formatting of the number they could still do format = 'CPU: {cpu_usage:d}%' etc.
So using this allows sensible defaults formatting and allows simple placeholders for user configurations.
class Py3status:\n\n class Meta:\n\n update_config = {\n 'update_placeholder_format': [\n {\n 'placeholder_formats': { # dict of placeholder:format\n 'cpu_usage': ':.2f',\n },\n 'format_strings': ['format'], # config settings to update\n }\n ],\n }\nEach module should be able to run independently for testing purposes. This is simply done by adding the following code to the bottom of your module.
if __name__ == \"__main__\":\n \"\"\"\n Run module in test mode.\n \"\"\"\n from py3status.module_test import module_test\n module_test(Py3status)\nIf a specific config should be provided for the module test, this can be done as follows.
if __name__ == \"__main__\":\n \"\"\"\n Run module in test mode.\n \"\"\"\n config = {\n 'always_show': True,\n }\n from py3status.module_test import module_test\n module_test(Py3status, config=config)\nSuch modules can then be tested independently by running python /path/to/module.py.
$ python loadavg.py\n[{'full_text': 'Loadavg ', 'separator': False,\n'separator_block_width': 0, 'cached_until': 1538755796.0},\n{'full_text': '1.87 1.73 1.87', 'color': '#9DD7FB'}]\n^C\nWe also can produce an output similar to i3bar output in terminal with python /path/to/module.py --term.
$ python loadavg.py --term\nLoadavg 1.41 1.61 1.82\nLoadavg 1.41 1.61 1.82\nLoadavg 1.41 1.61 1.82\n^C\nYou can share your custom modules and make them available for py3status users even if they are not directly part of the py3status main project!
All you have to do is to package your module and publish it to PyPI.
py3status will discover custom modules if they are installed in the same host interpreter and if an entry_point in your package setup.py is defined:
setup(\n entry_points={\"py3status\": [\"module = package_name.py3status_module_name\"]},\n)\nThe awesome pewpew module can be taken as an example on how to do it easily:
We will gladly add extra_requires pointing to your modules so that users can require them while installing py3status. Just open an issue to request this or propose a PR.
If you have installed py3status in a virtualenv (maybe because your custom module has dependencies that need to be available) you can also create an installable package from your module and publish it on PyPI.
Note
To clearly identify your py3status package and for others to discover it easily it is recommended to name the PyPI package py3status-<your module name>.
py3status comes with a large range of modules.
Modules in py3status are configured using your usual i3status.conf or your own py3status.conf which follows the exact same format.
py3status will try to find its configuration file in the following locations:
~/.config/py3status/config~/.config/i3status/config~/.config/i3/i3status.conf~/.i3status.conf~/.i3/i3status.conf/etc/xdg/i3status/config/etc/i3status.confwhich if you are used to XDG_CONFIG paths relates to:
XDG_CONFIG_HOME/py3status/configXDG_CONFIG_HOME/i3status/configXDG_CONFIG_HOME/i3/i3status.conf~/.i3status.conf~/.i3/i3status.confXDG_CONFIG_DIRS/i3status/config/etc/i3status.confYou can also specify the config location using py3status -c <path to config file> in your i3 configuration file.
To load a py3status module you just have to list it like any other i3status module using the order += parameter.
Ordering your py3status modules in your i3bar is just the same as i3status modules, just list the order parameter where you want your module to be displayed.
For example you could insert and load the imap module like this:
order += \"disk /home\"\norder += \"disk /\"\norder += \"imap\"\norder += \"time\"\nYour py3status modules are configured the exact same way as i3status modules, directly from your i3status.conf (or your own configuration file), like this :
# configure the py3status imap module\n# and run thunderbird when I left click on it\nimap {\n cache_timeout = 60\n imap_server = 'imap.myprovider.com'\n mailbox = 'INBOX'\n password = 'coconut'\n port = '993'\n user = 'mylogin'\n on_click 1 = \"exec thunderbird\"\n}\nPy3status itself does not handle the possible dependencies of the modules you use. Each module's documentation has a dedicated Requires section allowing you to know which libraries or binaries they depend on. It's up to you to install them on your system.
This special section holds py3status specific configuration. Settings here will affect all py3status modules. Many settings e.g. colors can still be overridden by also defining in the individual module.
stop_signal. Specify a signal number to be used by i3bar to stop/resume the bar refresh. This is useful if you want to prevent i3bar from stopping py3status when the bar is not visible (hidden/fullscreen).# prevent i3bar from stopping py3status when hidden/fullscreen\npy3status {\n stop_signal = 0\n}\nnagbar_font. Specify a font for i3-nagbar -f <font>.py3status {\n nagbar_font = 'pango:Ubuntu Mono 12'\n}\nstorage: Set storage name or path.Store cache in $XDG_CACHE_HOME or ~/.cache:
# default behavior\npy3status {\n storage = 'py3status_cache.data'\n}\nStore per config cache in $XDG_CACHE_HOME or ~/.cache:
# first config\npy3status {\n storage = 'py3status_top.data'\n}\n# second config\npy3status {\n storage = 'py3status_bottom.data'\n}\nStore per config cache in different directories:
# first config\npy3status {\n storage = '~/.config/py3status/cache_top.data'\n}\n# second config\npy3status {\n storage = '~/.config/py3status/cache_bottom.data'\n}\nYou can specify the following options in module configuration.
min_length: Specify a minimum length of characters for modules.position: Specify how modules should be positioned when the min_length is not reached. Either left (default), center, or right.static_string {\n min_length = 15\n position = 'center'\n}\nYou can specify the options in module or py3status configuration section.
The following options will work on i3.
align: Specify how modules should be aligned when the min_width is not reached. Either left (default), center, or right.background: Specify a background color for py3status modules.markup: Specify how modules should be parsed.min_width: Specify a minimum width of pixels for modules.separator: Specify a separator boolean for modules.separator_block_width: Specify a separator block width for modules.The following options will work on i3-gaps.
border: Specify a border color for modules.border_bottom: Specify a border width for modulesborder_left: Specify a border width for modules.border_right: Specify a border width for modules.border_top: Specify a border width for modules.The following options will work on py3status.
min_length: Specify a minimum length of characters for modules.position: Specify how modules should be positioned when the min_length is not reached. Either left (default), center, or right.# customize a theme\npy3status {\n align = 'left'\n markup = 'pango'\n min_width = 20\n separator = True\n separator_block_width = 9\n\n background = '#285577'\n border = '#4c7899'\n border_bottom = 1\n border_left = 1\n border_right = 1\n border_top = 1\n\n min_length = 15\n position = 'right'\n}\nYou can specify the options in module or py3status configuration section.
The following options will work on i3bar and py3status.
urgent_background: Specify urgent background color for modules.urgent_foreground: Specify urgent foreground color for modules.urgent_border: Specify urgent border color for modules.The following options will work on i3bar-gaps and py3status.
urgent_border_bottom: Specify urgent border width for modulesurgent_border_left: Specify urgent border width for modules.urgent_border_right: Specify urgent border width for modules.urgent_border_top: Specify urgent border width for modules.You lose urgent functionality too that can be sometimes utilized by container modules, e.g., frame and group.
# customize urgent\npy3status {\n urgent_background = 'blue'\n urgent_foreground = 'white'\n urgent_border = 'red'\n urgent_border_bottom = 1\n urgent_border_left = 1\n urgent_border_right = 1\n urgent_border_top = 1\n}\nYou can specify the options in module or py3status configuration section.
resources: Specify a list of 3-tuples, e.g., [(option, resource, fallback)], to import resources.# import resources\npy3status {\n resources = [\n ('color_bad', '*color9', 'lightcoral'),\n ('color_good', '*color10', 'lightgreen'),\n ('color_degraded', '*color11', 'khaki'),\n ('nagbar_font', 'py3status.font', 'pango:Ubuntu Mono 12'),\n ]\n}\n# import 16 colors\npy3status {\n resources = [\n ('color_color0', '*color0', 'black'),\n ('color_color1', '*color1', 'black'),\n ('color_color2', '*color2', 'black'),\n ('color_color3', '*color3', 'black'),\n ('color_color4', '*color4', 'black'),\n ('color_color5', '*color5', 'black'),\n ('color_color6', '*color6', 'black'),\n ('color_color7', '*color7', 'black'),\n ('color_color8', '*color8', 'black'),\n ('color_color9', '*color9', 'black'),\n ('color_color10', '*color10', 'black'),\n ('color_color11', '*color11', 'black'),\n ('color_color12', '*color12', 'black'),\n ('color_color13', '*color13', 'black'),\n ('color_color14', '*color14', 'black'),\n ('color_color15', '*color15', 'black'),\n ]\n}\n\n# apply colors\ncoin_market {\n thresholds = [(-100, \"color9\"), (0, \"color10\")]\n}\nPy3status allows you to hide individual configuration parameters so that they do not leak into log files, user notifications or to the i3bar. Additionally they allow you to obfuscate configuration parameters using base64 encoding.
To \"hide\" a value you can use the hide() configuration function. This prevents the module displaying the value as a format placeholder and from appearing in the logs.
# Example of 'hidden' configuration\nimap {\n imap_server = 'imap.myprovider.com'\n password = hide('hunter22')\n user = 'mylogin'\n}\nTo base64 encode a value you can use the base64() configuration function. This also prevents the module displaying the value as a format placeholder and from appearing in the logs.
# Example of obfuscated configuration\nimap {\n imap_server = 'imap.myprovider.com'\n password = base64('Y29jb251dA==')\n user = 'mylogin'\n}\nSince version 3.1 obfuscation options can also be added by the legacy method. Add :hide or :base64 to the name of the parameters. You are advised to use the new hide() and base64() configuration functions.
Note
Legacy obfuscation is only available for string: parameters with :hide or :base64. If you want other types then be sure to use hide() and base64() configuration functions.
# normal_parameter will be shown in log files etc as 'some value'\n# obfuscated_parameter will be shown in log files etc as '***'\nmodule {\n normal_parameter = 'some value'\n obfuscated_parameter:hide = 'some value'\n}\nIn the previous example configuration the users password is in plain text. Users may want to make it less easy to read. Py3status allows strings to be base64 encoded.
To use an encoded string add :base64 to the name of the parameter.
# Example of obfuscated configuration\nimap {\n imap_server = 'imap.myprovider.com'\n password:base64 = 'Y29jb251dA=='\n user = 'mylogin'\n}\nWarning
Base64 encoding is very simple and should not be considered secure in any way.
"},{"location":"user-guide/configuration/#configuring-colors","title":"Configuring colors","text":"Since version 3.1 py3status allows greater color configuration. Colors can be set in the general section of your i3status.conf or in an individual modules configuration. If a color is not in a modules configuration then the values from the general section will be used.
If a module does not specify colors but it is in a container, then the colors of the container will be used if they are set, before using ones defined in the general section.
Generally colors can specified using hex values eg #FF00FF or #F0F. It is also possible to use css3 color names eg red hotpink. Check here for al ist of available color names.
general {\n # These will be used if not supplied by a module\n color = '#FFFFFF'\n color_good = '#00FF00'\n color_bad = '#FF0000'\n color_degraded = '#FFFF00'\n}\n\ntime {\n color = 'FF00FF'\n format = \"%H:%M\"\n}\n\nbattery_level {\n color_good = '#00AA00'\n color_bad = '#AA0000'\n color_degraded = '#AAAA00'\n color_charging = '#FFFF00'\n}\nSome modules allow you to define thresholds in a module. These are used to determine which color to use when displaying the module. Thresholds are defined in the config as a list of tuples. With each tuple containing a value and a color. The color can either be a named color eg good referring to color_good or a hex value.
volume_status {\n thresholds = [\n (0, \"#FF0000\"),\n (20, \"degraded\"),\n (50, \"bad\"),\n ]\n}\nIf the value checked against the threshold is equal to or more than a threshold then that color supplied will be used.
In the above example the logic would be
if 0 >= value < 20 use #FF0000\nelse if 20 >= value < 50 use color_degraded\nelse if 50 >= value use color_good\nSome modules may allow more than one threshold to be defined. If all the thresholds are the same they can be defined as above but if you wish to specify them separately you can by giving a dict of lists.
my_module {\n thresholds = {\n 'threshold_1': [\n (0, \"#FF0000\"),\n (20, \"degraded\"),\n (50, \"bad\"),\n ],\n 'threshold_2': [\n (0, \"good\"),\n (30, \"bad\"),\n ],\n }\n}\nYou can specify hidden color to hide a block.
# hide a block when ``1avg`` (i.e., 12.4) is less than 20 percent\nformat = \"[\\?color=1avg [\\?color=darkgray&show 1min] {1min}]\"\nloadavg {\n thresholds = [\n (0, \"hidden\"),\n (20, \"good\"),\n (40, \"degraded\"),\n (60, \"#ffa500\"),\n (80, \"bad\"),\n ]\n}\n\n# hide cpu block when ``cpu_used_percent`` is less than 50 percent\n# hide mem block when ``mem_used_percent`` is less than 50 percent\nsysdata {\n thresholds = [\n (50, \"hidden\"),\n (75, \"bad\"),\n ]\n}\nAll modules allow you to define the format of their output. This is done with the format option. You can:
mpd_status {\n format = \"MPD:\"\n}\n\\ to escape a character (\\[ will show [).mpd_status {\n format = \"MPD: {state} {artist} {title}\"\n}\n- Unknown placeholders act as if they were static text and\n placeholders that are empty or None will be removed.\n- Formatting can also be applied to the placeholder Eg\n `{number:03.2f}`.\n[]. The following example will show artist - title if artist is present and title if title but no artist is present.mpd_status {\n format = \"MPD: {state} [[{artist} - ]{title}]\"\n}\n|. The following example will show the filename if neither artist nor title are present.mpd_status {\n format = \"MPD: {state} [[{artist} - ]{title}]|{file}\"\n}\n\\? can be used to provide extra commands to the format string. Multiple commands can be given using an ampersand & as a separator.my_module {\n format = \"\\?color=#FF00FF&show blue\"\n}\n\\? with a an if statement. Multiple conditions or commands can be combined by using an ampersand & as a separator. Here are some examples:\\?if=online green | red checks if the placeholder exists and would display green in that case. A condition that evaluates to false invalidates a section and the section can be hidden with [] or skipped with |\\?if=!online red | green this dose the same as the above condition, the only difference is that the exclamation mark ! negates the condition.\\?if=state=play PLAYING! | not playing checks if the placeholder contains play and displays PLAYING! if not it will display not playing.A format string using nearly all of the above options could look like this:
mpd_status {\n format = \"MPD: {state} [\\?if=![stop] [[{artist} - ]{title}]|[{file}]]\"\n}\nThis will show MPD: [state] if the state of the MPD is [stop] or MPD: [state] artist - title if it is [play] or [pause] and artist and title are present, MPD: [state] title if artist is missing and MPD: [state] file if artist and title are missing.
Some modules use i3bar's urgent feature to indicate that something important has occurred. The allow_urgent configuration parameter can be used to allow/prevent a module from setting itself as urgent.
# prevent modules showing as urgent, except github\npy3status {\n allow_urgent = false\n}\n\ngithub {\n allow_urgent = true\n}\nWhen a module error has occurred, it will be reported on the bar. The on_error configuration parameter allows users to choose what to do instead.
Supported values:
show (default): report the error on the bar (click to view)hide: hide the module on the bar# hide errors on all modules by default (still reported on logs)\npy3status {\n on_error = \"hide\"\n}\n\n# hide errors on non-NVIDIA hardwares\nnvidia_smi {\n on_error = \"hide\"\n}\n\n# hide errors on sway where xrandr does not work\nxrandr {\n on_error = \"hide\"\n}\nThe module_group module allows you to group several modules together. Only one of the modules are displayed at a time. The displayed module can either be cycled through automatically or by user action (the default, on mouse scroll).
This module is very powerful and allows you to save a lot of space on your bar.
order += \"group tz\"\n\n# cycle through different timezone hours every 10s\ngroup tz {\n cycle = 10\n format = \"{output}\"\n\n tztime la {\n format = \"LA %H:%M\"\n timezone = \"America/Los_Angeles\"\n }\n\n tztime ny {\n format = \"NY %H:%M\"\n timezone = \"America/New_York\"\n }\n\n tztime du {\n format = \"DU %H:%M\"\n timezone = \"Asia/Dubai\"\n }\n}\nThe module_frame module also allows you to group several modules together, however in a frame all the modules are shown. This allows you to have more than one module shown in a group.
order += \"group frames\"\n\n# group showing disk space or times using button to change what is shown.\ngroup frames {\n click_mode = \"button\"\n\n frame time {\n tztime la {\n format = \"LA %H:%M\"\n timezone = \"America/Los_Angeles\"\n }\n\n tztime ny {\n format = \"NY %H:%M\"\n timezone = \"America/New_York\"\n }\n\n tztime du {\n format = \"DU %H:%M\"\n timezone = \"Asia/Dubai\"\n }\n }\n\n frame disks {\n disk \"/\" {\n format = \"/ %avail\"\n }\n\n disk \"/home\" {\n format = \"/home %avail\"\n }\n }\n}\nFrames can also have a toggle button to hide/show the content
# A frame showing times in different cities.\n# We also have a button to hide/show the content\n\nframe time {\n format = '{output}{button}'\n format_separator = ' ' # have space instead of usual i3bar separator\n\n tztime la {\n format = \"LA %H:%M\"\n timezone = \"America/Los_Angeles\"\n }\n\n tztime ny {\n format = \"NY %H:%M\"\n timezone = \"America/New_York\"\n }\n\n tztime du {\n format = \"DU %H:%M\"\n timezone = \"Asia/Dubai\"\n }\n}\npy3status allows you to easily add click events to modules in your i3bar. These modules can be both i3status or py3status modules. This is done in your i3status.config using the on_click parameter.
Just add a new configuration parameter named on_click [button number] to your module config and py3status will then execute the given i3 command (using i3-msg).
This means you can run simple tasks like executing a program or execute any other i3 specific command.
As an added feature and in order to get your i3bar more responsive, every on_click command will also trigger a module refresh. This works for both py3status modules and i3status modules as described in the refresh command below.
# button numbers\n1 = left click\n2 = middle click\n3 = right click\n4 = scroll up\n5 = scroll down\n# reload the i3 config when I left click on the i3status time module\n# and restart i3 when I middle click on it\ntime {\n on_click 1 = \"reload\"\n on_click 2 = \"restart\"\n}\n\n# control the volume with your mouse (need >i3-4.8)\n# launch alsamixer when I left click\n# kill it when I right click\n# toggle mute/unmute when I middle click\n# increase the volume when I scroll the mouse wheel up\n# decrease the volume when I scroll the mouse wheel down\nvolume master {\n format = \"\u266a: %volume\"\n device = \"default\"\n mixer = \"Master\"\n mixer_idx = 0\n on_click 1 = \"exec i3-sensible-terminal -e alsamixer\"\n on_click 2 = \"exec amixer set Master toggle\"\n on_click 3 = \"exec killall alsamixer\"\n on_click 4 = \"exec amixer set Master 1+\"\n on_click 5 = \"exec amixer set Master 1-\"\n}\n\n# run wicd-gtk GUI when I left click on the i3status ethernet module\n# and kill it when I right click on it\nethernet eth0 {\n # if you use %speed, i3status requires root privileges\n format_up = \"E: %ip\"\n format_down = \"\"\n on_click 1 = \"exec wicd-gtk\"\n on_click 3 = \"exec killall wicd-gtk\"\n}\n\n# run thunar when I left click on the / disk info module\ndisk \"/\" {\n format = \"/ %free\"\n on_click 1 = \"exec thunar /\"\n}\n\n# this is a py3status module configuration\n# open an URL on opera when I left click on the weather_yahoo module\nweather_yahoo paris {\n cache_timeout = 1800\n woeid = 615702\n forecast_days = 2\n on_click 1 = \"exec opera http://www.meteo.fr\"\n request_timeout = 10\n}\nThere are two commands you can pass to the on_click parameter that have a special meaning to py3status :
refresh : This will refresh (expire the cache) of the clicked module. This also works for i3status modules (it will send a SIGUSR1 to i3status for you).refresh_all : This will refresh all the modules from your i3bar (i3status included). This has the same effect has sending a SIGUSR1 to py3status.Since version 3.3 it is possible to use the output text of a module in the on_click command. To do this $OUTPUT can be used in command and it will be substituted by the modules text output when the command is run.
# copy module output to the clipboard using xclip\nmy_module {\n on_click 1 = 'exec echo $OUTPUT | xclip -i'\n}\nIf the output of a module is a composite then the output of the part clicked on can be accessed using $OUTPUT_PART.
You may use the value of an environment variable in your configuration with the env(...) directive. These values are captured at startup and may be converted to the needed datatype (only str, int, float, bool and auto are currently supported).
Note, the auto conversion will try to guess the type of the contents and automatically convert to that type. Without an explicit conversion function, it defaults to auto.
This is primarily designed to obfuscate sensitive information when sharing your configuration file, such as usernames, passwords, API keys, etc.
The env(...) expression can be used anywhere a normal constant would be used. Note, you cannot use the directive in place of a dictionary key, i.e {..., env(KEY): 'val', ...}.
See the examples below!
order += \"my_module\"\norder += env(ORDER_MODULE)\n\nmodule {\n normal_parameter = 'some value'\n env_parameter = env(SOME_ENVIRONMENT_PARAM)\n sensitive_api_key = env(API_KEY)\n\n complex_parameter = {\n 'key': env(VAL)\n }\n\n equivalent1 = env(MY_VAL)\n equivalent2 = env(MY_VAL, auto)\n\n list_of_tuples = [\n (env(APPLE_NUM, int), 'apple'),\n (2, env(ORANGE))\n ]\n\n float_param = env(MY_NUM, float)\n}\nYou can use the standard output of a shell script in your configuration with the shell(...) directive. These values are captured at startup and may be converted to the needed datatype (only str, int, float, bool and auto (default) are currently supported).
The shell script executed must return a single line of text on stdout and then terminate. If the type is explicitly declared bool, the exit status of the script is respected (a non-zero exit status being interpreted falsey). In any other case if the script exits with a non-zero exit status an error will be thrown.
The shell(...) expression can be used anywhere a constant or an env(...) directive can be used (see the section \"Environment Variables\").
Usage example:
my_module {\n password = shell(pass show myPasswd | head -n1)\n some_string = shell(/opt/mydaemon/get_api_key.sh, str)\n pid = shell(cat /var/run/mydaemon/pidfile, int)\n my_bool = shell(pgrep thttpd, bool)\n}\nDue to the way the config is parsed you need to to escape any closing parenthesis ) using a backslash \\).
static_string {\n # note we need to explicitly cast the result to str\n # because we are using it as the format which must be a\n # string\n format = shell(echo $((6 + 2\\)\\), str)\n}\nRefreshing of modules can be triggered when an udev event is detected on a specific subsystem using the on_udev_<subsystem> configuration parameter and an associated action.
Possible actions:
refresh: immediately refresh the module and keep on updating it as usualrefresh_and_freeze: module is ONLY refreshed when said udev subsystem emits an event# refresh xrandr only when udev 'drm' events are triggered\nxrandr {\n on_udev_drm = \"refresh_and_freeze\"\n}\nNote
This feature will only activate when pyudev is installed on the system. This is an optional dependency of py3status and is therefore not enforced by all package managers.
Timeouts are handled thanks to the global request_timeout setting.
Request Timeout for URL request based modules can be specified in the module configuration. To find out if your module supports that, look for self.py3.request in the code. Otherwise, we will use 10.
# stop waiting for a response after 10 seconds\nexchange_rate {\n request_timeout = 10\n}\nRetries are handled thanks to the global request_retry_times and request_retry_wait settings.
Requests failing due to network unavailability or remote server timeouts are retried automatically request_retry_times times (default 3) at a request_retry_wait (default 2) seconds interval.
This allows to be more graceful to i3 startup when network is not up yet or to short network disruptions and not display an error on the bar in that case.
To find out if your module supports that, look for self.py3.request in the code.
# try to contact the OWM API 10 times every 5 seconds before displaying\n# an error on the bar for the module\n# that is equivalent to 50 seconds of retrying before an error occurs\nweather_owm {\n request_retry_times = 10\n request_retry_wait = 5\n}\nWant Py3status in your beloved tmux? Sure!
While Py3status is by default running using the i3bar output format, you can change the output_format of the general section of the configuration file to get your favorite status bar in the following programs:
Stable updates, official releases:
$ pacman -S py3status\nReal-time updates from master branch:
$ yay -S py3status-git\nStable updates. In testing and unstable, and soon in stable backports:
$ apt-get install py3status\nBuster users might want to check out issue #1916 and use pip3 instead or the alternative method proposed until this debian bug is handled and stable.
Note
If you want to use pip, you should consider using pypi-install from the python-stdeb package (which will create a .deb out from a python package) instead of directly calling pip.
$ pip3 install py3status\n$ dnf install py3status\nCheck available USE flags if you need them!
$ emerge -a py3status\nIn community repository since Alpine Linux 3.17.
$ apk add py3status\n$ pip install py3status\nThere are optional requirements that you could find useful:
py3status[udev] for udev support.Or if you want everything:
py3status[all] to install all core extra requirements and features.$ xbps-install -S py3status\nTo have py3status globally persistent add to your NixOS configuration file py3status as a Python 3 package with:
(python3Packages.py3status.overrideAttrs (oldAttrs: {\n propagatedBuildInputs = with python3Packages;[ pytz tzlocal ] ++ oldAttrs.propagatedBuildInputs;\n}))\nIf you are, and you probably are, using i3 you might want a section in your /etc/nixos/configuration.nix that looks like this:
{\n services.xserver.windowManager.i3 = {\n enable = true;\n extraPackages = with pkgs; [\n dmenu\n i3status\n i3lock\n (python3Packages.py3status.overrideAttrs (oldAttrs: {\n propagatedBuildInputs = with python3Packages; [ pytz tzlocal ] ++ oldAttrs.propagatedBuildInputs;\n }))\n ];\n };\n}\nIn this example I included the python packages pytz and tzlocal which are necessary for the py3status module clock. The default packages that come with i3 (dmenu, i3status, i3lock) have to be mentioned if they should still be there.
$ nix-env -i python3.6-py3status\nDisplay air quality polluting in a given location.
An air quality index (AQI) is a number used by government agencies to communicate to the public how polluted the air currently is or how polluted it is forecast to become. As the AQI increases, an increasingly large percentage of the population is likely to experience increasingly severe adverse health effects. Different countries have their own air quality indices, corresponding to different national air quality standards.
Configuration parameters:
auth_token Personal token required. See https://aqicn.org/data-platform/token for more information. (default 'demo')
cache_timeout refresh interval for this module. A message from the site: The default quota is max 1000 requests per minute (~16RPS) and with burst up to 60 requests. See https://aqicn.org/api/ for more information. (default 3600)
format display format for this module (default '[\\?color=aqi {city_name}: {aqi} {category}]')
format_datetime specify strftime characters to format (default {})
location location or uid to query. To search for nearby stations in Krak\u00f3w, try https://api.waqi.info/search/?token=YOUR_TOKEN&keyword=krak\u00f3w For best results, use uid instead of name in location, eg @8691. (default 'Shanghai')
quality_thresholds specify a list of tuples, eg (number, 'color', 'name') (default [(0, '#009966', 'Good'), (51, '#FFDE33', 'Moderate'), (101, '#FF9933', 'Sensitively Unhealthy'), (151, '#CC0033', 'Unhealthy'), (201, '#660099', 'Very Unhealthy'), (301, '#7E0023', 'Hazardous')])
thresholds specify color thresholds to use (default {'aqi': True})
Notes: Your station may have individual scores for pollutants not listed below. See https://api.waqi.info/feed/@UID/?token=TOKEN (Replace UID and TOKEN) for a full list of placeholders to use.
Format placeholders:
{aqi} air quality index
{attributions_0_name} attribution name, there maybe more, change the 0
{attributions_0_url} attribution url, there maybe more, change the 0
{category} health risk category, eg Good, Moderate, Unhealthy, etc
{city_geo_0} monitoring station latitude
{city_geo_1} monitoring station longitude
{city_name} monitoring station name
{city_url} monitoring station url
{dominentpol} dominant pollutant, eg pm25
{idx} Unique ID for the city monitoring station, eg 7396
{time} epoch timestamp, eg 1510246800
{time_s} local timestamp, eg 2017-11-09 17:00:00
{time_tz} local timezone, eg -06:00
{iaqi_co} individual score for pollutant carbon monoxide
{iaqi_h} individual score for pollutant h (?)
{iaqi_no2} individual score for pollutant nitrogen dioxide
{iaqi_o3} individual score for pollutant ozone
{iaqi_pm25} individual score for pollutant particulates smaller than 2.5 \u03bcm in aerodynamic diameter
{iaqi_pm10} individual score for pollutant particulates smaller than 10 \u03bcm in aerodynamic diameter
{iaqi_pm15} individual score for pollutant particulates smaller than than 15 \u03bcm in aerodynamic diameter
{iaqi_p} individual score for pollutant particulates
{iaqi_so2} individual score for pollutant sulfur dioxide
{iaqi_t} individual score for pollutant t (?)
{iaqi_w} individual score for pollutant w (?)
AQI denotes an air quality index. IQAI denotes an individual AQI score. Try https://en.wikipedia.org/wiki/Air_pollution#Pollutants for more information on the pollutants retrieved from your monitoring station.
format_datetime placeholders:
key epoch_placeholder, eg time, vtime
value % strftime characters to be translated, eg '%b %d' ----> 'Nov 11'
Color options:
color_bad print a color for error (if any) from the siteColor thresholds:
xxx print a color based on the value of xxx placeholderExamples:
# show last updated time\nair_quality {\n format = '{city_name}: {aqi} {category} - {time}'\n format_datetime = {'time': '%-I%P'}\n}\nauthor beetleman, lasers
license BSD
"},{"location":"user-guide/modules/#apt_updates","title":"apt_updates","text":"Display number of pending updates for Debian based Distros.
Thanks to Iain Tatch <iain.tatch@gmail.com> for the script that this is based on. This will display a count of how many 'apt' updates are waiting to be installed.
Configuration parameters:
cache_timeout How often we refresh this module in seconds (default 600)
format Display format to use (default 'UPD[\\?not_zero : {apt}]')
Format placeholders:
{apt} Number of pending apt updatesRequires:
apt Needed to display pending 'apt' updatesauthor Joshua Pratt <jp10010101010000@gmail.com>
license BSD
"},{"location":"user-guide/modules/#arch_updates","title":"arch_updates","text":"Display number of pending updates for Arch Linux.
Configuration parameters:
cache_timeout refresh interval for this module (default 3600)
format display format for this module, otherwise auto (default None)
hide_if_zero don't show on bar if True (default False)
Format placeholders:
{aur} Number of pending aur updates
{pacman} Number of pending pacman updates
{total} Total updates pending
Requires:
pacman-contrib contributed scripts and tools for pacman systems
auracle a flexible command line client for arch linux's user repository
trizen lightweight pacman wrapper and AUR helper
yay yet another yogurt. pacman wrapper and aur helper written in go
paru feature packed AUR helper
pikaur pacman wrapper and AUR helper written in python
Note: py3status for Arch-based distributions should include an alpm hook to refresh this module after packages and/or files being modified.
author Iain Tatch <iain.tatch@gmail.com>
license BSD
"},{"location":"user-guide/modules/#async_script","title":"async_script","text":"Display output of a given script asynchronously.
Always displays the last line of output from a given script, set by script_path. If a line contains only a color (/^#[0-F]{6}$/), it is used as such (set force_nocolor to disable). The script may have parameters.
Configuration parameters:
force_nocolor if true, won't check if a line contains color (default False)
format see placeholders below (default '{output}')
script_path script you want to show output of (compulsory) (default None)
strip_output shall we strip leading and trailing spaces from output (default False)
Format placeholders:
{output} output of script given by \"script_path\"Examples:
async_script {\n format = \"{output}\"\n script_path = \"ping 127.0.0.1\"\n}\nauthor frimdo ztracenastopa@centrum.cz, girst
"},{"location":"user-guide/modules/#audiosink","title":"audiosink","text":"Display and toggle default audiosink.
Configuration parameters:
cache_timeout How often we refresh this module in seconds (default 10)
display_name_mapping dictionary mapping devices names to display names (default {})
format display format for this module (default '{audiosink}')
sinks_to_ignore list of devices names to ignore (default [])
Format placeholders:
{audiosink} comma seperated list of (display) names of default sink(s)Requires:
pulseaudio networked sound serverExamples:
audiosink {\n display_name_mapping = {\"Family 17h/19h HD Audio Controller Analog Stereo\": \"Int\", \"ThinkPad Dock USB Audio Analog Stereo\": \"Dock\"}\n format = r\"{audiosink}\"\n sinks_to_ignore = [\"Renoir Radeon High Definition Audio Controller Digital Stereo (HDMI)\"]\n}\nauthor Jens Brandt <py3status@brandt-george.de>
license BSD
"},{"location":"user-guide/modules/#aws_bill","title":"aws_bill","text":"Display bill for Amazon Web Services.
WARNING: This module generate some costs on the AWS bill. Take care about the cache_timeout to limit these fees!
Configuration parameters:
aws_access_key_id Your AWS access key (default '')
aws_account_id The root ID of the AWS account Can be found here` https://console.aws.amazon.com/billing/home#/account (default '')
aws_secret_access_key Your AWS secret key (default '')
billing_file Csv file location (default '/tmp/.aws_billing.csv')
cache_timeout How often we refresh this module in seconds (default 3600)
format string that formats the output. See placeholders below. (default '{bill_amount}$')
s3_bucket_name The bucket where billing files are sent by AWS. Follow this article to activate this feature: https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-reports.html (default '')
Format placeholders:
{bill_amount} AWS bill amountColor options:
color_good Balance available
color_bad An error has occurred
Requires:
boto a python interface to amazon web services (aws)author nawadanp
"},{"location":"user-guide/modules/#backlight","title":"backlight","text":"Adjust screen backlight brightness.
Configuration parameters:
brightness_delta Change the brightness by this step. (default 8)
brightness_initial Set brightness to this value on start. (default None)
brightness_minimal Don't go below this brightness to avoid black screen (default 1)
button_down Button to click to decrease brightness. Setting to 0 disables. (default 5)
button_up Button to click to increase brightness. Setting to 0 disables. (default 4)
cache_timeout How often we refresh this module in seconds (default 10)
command The program to use to change the backlight. Currently xbacklight, light and brightnessctl are supported. The program needs to be installed and on your path. If no program is installed, this module will attempt to use logind support instead (default 'xbacklight')
device Device name or full path to use, eg, acpi_video0 or /sys/class/backlight/acpi_video0, otherwise automatic (default None)
format Display brightness, see placeholders below (default '\u263c: {level}%')
hide_when_unavailable Hide if no backlight is found (default False)
low_tune_threshold If current brightness value is below this threshold, the value is changed by a minimal value instead of the brightness_delta. (default 0)
Format placeholders:
{level} brightnessRequires: one of xbacklight: need for changing brightness, not detection light: program to easily change brightness on backlight-controllers brightnessctl: change brightness wayland compatible dbus-python + logind v243: logind to change brightness without X
author Tjaart van der Walt (github:tjaartvdwalt), J\u00e9r\u00e9my Rosen (github:boucman)
license BSD
"},{"location":"user-guide/modules/#battery_level","title":"battery_level","text":"Display battery information.
Configuration parameters:
battery_id id of the battery to be displayed set to 'all' for combined display of all batteries (default 0)
blocks a string, where each character represents battery level especially useful when using icon fonts (e.g. FontAwesome) (default \"_\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588\")
cache_timeout a timeout to refresh the battery state (default 60)
charging_character a character to represent charging battery especially useful when using icon fonts (e.g. FontAwesome) set to 'None' if you want to hide the charging state of your battery (default \"\u26a1\")
format string that formats the output. See placeholders below. (default \"{icon}\")
format_notify_charging format of the notification received when you click on the module while your computer is plugged in (default 'Charging ({percent}%)')
format_notify_discharging format of the notification received when you click on the module while your computer is not plugged in (default \"{time_remaining}\")
format_status_bad a string to put in {status} when bad (default \"CRIT\")
format_status_charging a string to put in {status} when charging (default \"CHG\")
format_status_degraded a string to put in {status} when degraded (default \"LOW\")
format_status_discharging a string to put in {status} when discharging (default \"BAT\")
format_status_full a string to put in {status} when full (default \"FULL\")
hide_seconds hide seconds in remaining time (default False)
hide_when_full hide any information when battery is fully charged (when the battery level is greater than or equal to 'threshold_full') (default False)
measurement_mode either 'acpi' or 'sys', or None to autodetect. 'sys' should be more robust and does not have any extra requirements, however the time measurement may not work in some cases (default None)
notification show current battery state as notification on click (default False)
notify_low_level display notification when battery is running low (when the battery level is less than 'threshold_degraded') (default False)
on_udev_power_supply dynamic variable to watch for power_supply udev subsystem events to trigger specified action. (default \"refresh\")
sys_battery_path set the path to your battery(ies), without including its number (default \"/sys/class/power_supply/\")
threshold_bad a percentage below which the battery level should be considered bad (default 10)
threshold_degraded a percentage below which the battery level should be considered degraded (default 30)
threshold_full a percentage at or above which the battery level should should be considered full (default 100)
Format placeholders:
{ascii_bar} - a string of ascii characters representing the battery level, an alternative visualization to '{icon}' option
{icon} - a character representing the battery level, as defined by the 'blocks' and 'charging_character' parameters
{percent} - the remaining battery percentage (previously '{}')
{time_remaining} - the remaining time until the battery is empty
{power} - the current power consumption in Watts. Not working with acpi.
{status} - the current battery status string as defined by 'format_status_*'
Color options:
color_bad Battery level is below threshold_bad
color_charging Battery is charging (default \"#FCE94F\")
color_degraded Battery level is below threshold_degraded
color_good Battery level is above thresholds
Requires: - the acpi the acpi command line utility (only if measurement_mode='acpi')
author shadowprince, AdamBSteele, maximbaz, 4iar, m45t3r
license Eclipse Public License
"},{"location":"user-guide/modules/#bluetooth","title":"bluetooth","text":"Display bluetooth status.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default \"{format_adapter}\")
format_adapter display format for adapters (default \"{format_device}\")
format_adapter_separator show separator if more than one (default \" \")
format_device display format for devices (default \"\\?if=connected&color=connected {alias}\")
format_device_separator show separator if more than one (default \" \")
thresholds specify color thresholds to use (default [(False, \"bad\"), (True, \"good\")])
Format placeholders:
{format_adapter} format for adapters
{adapter} number of adapters, eg 1
format_adapter placeholders:
{format_device} format for devices
{device} number of devices, eg 5
{address} eg, 00:00:00:00:00:00
{addresstype} eg, public
{alias} eg, thinkpad
{class} eg, 123456
{discoverable} eg, False
{discoverabletimeout} eg, 0
{discovering} eg, False
{modalias} eg, usb:v1D68234ABCDEF5
{name} eg, z420
{pairable} eg, True
{pairabletimeout} eg, 0
{path} eg, /org/bluez/hci0
{powered} eg, True
{uuids} eg, []
format_device placeholders:
{adapter} eg, /org/bluez/hci0
{address} eg, 00:00:00:00:00:00
{addresstype} eg, public
{alias} eg, MSFT Mouse
{battery} eg, 95
{class} eg, 1234
{connected} eg, False
{icon} eg, input-mouse
{legacypairing} eg, False
{modalias} eg, usb:v1D68234ABCDEF5
{name} eg, Microsoft Bluetooth Notebook Mouse 5000
{paired} eg, True
{servicesresolved} eg, False
{trusted} eg, True
{uuids} eg, []
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
pygobject Python bindings for GObject IntrospectionExamples:
# always display devices\nbluetooth {\n format_device = \"\\?color=connected {alias}\"\n}\n\n# set an alias via blueman-manager or bluetoothctl\n# $ bluetoothctl\n# [bluetooth] # devices\n# [bluetooth] # connect 00:00:00:00:00:00\n# [bluetooth] # set-alias \"MSFT Mouse\"\n\n# display missing adapter (feat. request)\nbluetooth {\n format = \"\\?if=adapter {format_adapter}|\\?color=darkgray No Adapter\"\n}\n\n# legacy default\nbluetooth {\n format = \"\\?color=good BT: {format_adapter}|\\?color=bad BT\"\n format_device_separator = \"\\|\"\n}\nauthor jmdana, lasers
license BSD
"},{"location":"user-guide/modules/#check_tcp","title":"check_tcp","text":"Display status of a TCP port on a given host.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{host}:{port} {state}')
host name of host to check for (default 'localhost')
icon_off show this when unavailable (default 'DOWN')
icon_on show this when available (default 'UP')
port number of port to check for (default 22)
Format placeholders:
{state} port stateColor options:
color_down Closed, default to color_bad
color_up Open, default to color_good
author obb, Moritz L\u00fcdecke
"},{"location":"user-guide/modules/#clock","title":"clock","text":"Display date and time.
This module allows one or more datetimes to be displayed. All datetimes share the same format_time but can set their own timezones. Timezones are defined in the format using the TZ name in squiggly brackets eg {GMT}, {Portugal}, {Europe/Paris}, {America/Argentina/Buenos_Aires}.
See https://docs.python.org/3/library/zoneinfo.html for supported formats.
{Local} can be used for the local settings of your computer.
Note: Timezones are case sensitive!
A full list of timezones can be found at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
Configuration parameters:
block_hours length of time period for all blocks in hours (default 12)
blocks a string, where each character represents time period from the start of a time period. (default '\ud83d\udd5b\ud83d\udd67\ud83d\udd50\ud83d\udd5c\ud83d\udd51\ud83d\udd5d\ud83d\udd52\ud83d\udd5e\ud83d\udd53\ud83d\udd5f\ud83d\udd54\ud83d\udd60\ud83d\udd55\ud83d\udd61\ud83d\udd56\ud83d\udd62\ud83d\udd57\ud83d\udd63\ud83d\udd58\ud83d\udd64\ud83d\udd59\ud83d\udd65\ud83d\udd5a\ud83d\udd66')
button_change_format button that switches format used setting to None disables (default 1)
button_change_time_format button that switches format_time used. Setting to None disables (default 2)
button_reset button that switches display to the first timezone. Setting to None disables (default 3)
cycle If more than one display then how many seconds between changing the display (default 0)
format defines the timezones displayed. This can be a single string or a list. If a list is supplied then the formats can be cycled through using cycle or by button click. (default '{Local}')
format_time format to use for the time, strftime directives such as %H can be used this can be either a string or to allow multiple formats as a list. The one used can be changed by button click. (default ['[{name_unclear} ]%c', '[{name_unclear} ]%x %X', '[{name_unclear} ]%a %H:%M', '[{name_unclear} ]{icon}'])
locale Override the system locale. Examples: when set to 'fr_FR' %a on Tuesday is 'mar.'. (default None)
round_to_nearest_block defines how a block icon is chosen. Examples: when set to True, '13:14' is '\ud83d\udd50', '13:16' is '\ud83d\udd5c' and '13:31' is '\ud83d\udd5c'; when set to False, '13:14' is '\ud83d\udd50', '13:16' is '\ud83d\udd50' and '13:31' is '\ud83d\udd5c'. (default True)
Format placeholders:
{icon} a character representing the time from blocks
{name} friendly timezone name eg Buenos Aires
{name_unclear} friendly timezone name eg Buenos Aires but is empty if only one timezone is provided
{timezone} full timezone name eg America/Argentina/Buenos_Aires
{timezone_unclear} full timezone name eg America/Argentina/Buenos_Aires but is empty if only one timezone is provided
Examples:
# cycling through London, Warsaw, Tokyo\nclock {\n cycle = 30\n format = [\"{Europe/London}\", \"{Europe/Warsaw}\", \"{Asia/Tokyo}\"]\n format_time = \"{name} %H:%M\"\n}\n\n# Show the time and date in New York\nclock {\n format = \"Big Apple {America/New_York}\"\n format_time = \"%Y-%m-%d %H:%M:%S\"\n}\n\n# wall clocks\nclock {\n format = \"{Asia/Calcutta} {Africa/Nairobi} {Asia/Bangkok}\"\n format_time = \"{name} {icon}\"\n}\nauthor tobes ultrabug
license BSD
"},{"location":"user-guide/modules/#cmus","title":"cmus","text":"Display song currently playing in cmus.
cmus (C* Music Player) is a small, fast and powerful console audio player which supports most major audio formats. Various features include gapless playback, ReplayGain support, MP3 and Ogg streaming, live filtering, instant startup, customizable key-bindings, and vi-style default key-bindings.
Configuration parameters:
button_next mouse button to skip next track (default None)
button_pause mouse button to pause/play the playback (default 1)
button_previous mouse button to skip previous track (default None)
button_stop mouse button to stop the playback (default 3)
cache_timeout refresh interval for this module (default 5)
format display format for this module (default '[\\?if=is_started [\\?if=is_playing > ][\\?if=is_paused || ]' '[\\?if=is_stopped .. ][[{artist}][\\?soft - ][{title}]' '|\\?show cmus: waiting for user input]]')
replacements specify a list/dict of string placeholders to modify (default None)
sleep_timeout sleep interval for this module. when cmus is not running, this interval will be used. this allows some flexible timing where one might want to refresh constantly with some placeholders... or to refresh only once every minute rather than every few seconds. (default 20)
Control placeholders:
{is_paused} a boolean based on cmus status
{is_playing} a boolean based on cmus status
{is_started} a boolean based on cmus status
{is_stopped} a boolean based on cmus status
{continue} a boolean based on data status
{play_library} a boolean based on data status
{play_sorted} a boolean based on data status
{repeat} a boolean based on data status
{repeat_current} a boolean based on data status
{replaygain} a boolean based on data status
{replaygain_limit} a boolean based on data status
{shuffle} a boolean based on data status
{softvol} a boolean based on data status
{stream} a boolean based on data status
Format placeholders:
{aaa_mode} shuffle mode, eg artist, album, all
{albumartist} album artist, eg (new output here)
{album} album name, eg (new output here)
{artist} artist name, eg (new output here)
{bitrate} audio bitrate, eg 229
{comment} comment, eg URL
{date} year number, eg 2015
{duration} length time in seconds, eg 171
{durationtime} length time in [HH:]MM:SS, eg 02:51
{file} file location, eg /home/user/Music...
{position} elapsed time in seconds, eg 17
{positiontime} elapsed time in [HH:]MM:SS, eg 00:17
{replaygain_preamp} replay gain preamp, eg 0.000000
{status} playback status, eg playing, paused, stopped
{title} track title, eg (new output here)
{tracknumber} track number, eg 0
{vol_left} left volume number, eg 90
{vol_right} right volume number, eg 90
Placeholders are retrieved directly from cmus-remote --query command. The list was harvested only once and should not represent a full list.
Color options:
color_paused Paused, defaults to color_degraded
color_playing Playing, defaults to color_good
color_stopped Stopped, defaults to color_bad
Requires:
cmus a small feature-rich ncurses-based music playerauthor lasers
"},{"location":"user-guide/modules/#coin_balance","title":"coin_balance","text":"Display balances of diverse crypto-currencies.
This module grabs your current balance of different crypto-currents from a wallet server. The server must conform to the bitcoin RPC specification. Currently Bitcoin, Dogecoin, and Litecoin are supported.
Configuration parameters:
cache_timeout An integer specifying the cache life-time of the output in seconds (default 30)
coin_password A string containing the password for the server for 'coin'. The 'coin' part must be replaced by a supported coin identifier (see below for a list of identifiers). If no value is supplied, the value of 'password' (see below) will be used. If 'password' too is not set, the value will be retrieved from the standard 'coin' daemon configuration file. (default None)
coin_username A string containing the username for the server for 'coin'. The 'coin' part must be replaced by a supported coin identifier (see below for a list of identifiers). If no value is supplied, the value of 'username' (see below) will be used. If 'username' too is not set, the value will be retrieved from the standard 'coin' daemon configuration file. (default None)
credentials (default None)
format A string describing the output format for the module. The {<coin>} placeholder (see below) will be used to determine how to fetch the coin balance. Multiple placeholders are allowed, but all balances will be fetched from the same host. (default 'LTC: {litecoin}')
host The coin-server hostname. Note that all coins will use the same host for their queries. (default 'localhost')
password A string containing the password for all coin-servers. If neither this setting, nor a specific coin_password (see above) is specified, the password for each coin will be read from the respective standard daemon configuration file. (default None)
protocol A string to select the server communication protocol. (default 'http')
username A string containing the username for all coin-servers. If neither this setting, nor a specific coin_username (see above) is specified, the username for each coin will be read from the respective standard daemon configuration file. (default None)
Format placeholders:
{<coin>} Your balance for the coin <coin> where <coin> is one of:Requires:
requests python module from pypi https://pypi.python.org/pypi/requests At least version 2.4.2 is required.Examples:
# Get your Bitcoin balance using automatic credential detection\ncoin_balance {\n cache_timeout = 45\n format = \"My BTC: {bitcoin}\"\n host = \"localhost\"\n protocol = \"http\"\n}\n\n# Get your Bitcoin, Dogecoin and Litecoin balances using specific credentials\n# for Bitcoin and automatic detection for Dogecoin and Litecoin\ncoin_balance {\n # ...\n format = \"{bitcoin} BTC {dogecoin} XDG {litecoin} LTC\"\n bitcoin_username = \"lcdata\"\n bitcoin_password = \"omikron-theta\"\n # ...\n}\n\n# Get your Dogecoin and Litecoin balances using 'global' credentials\ncoin_balance {\n # ...\n format = \"XDG: {dogecoin} LTC: {litecoin}\"\n username = \"crusher_b\"\n password = \"WezRulez\"\n # ...\n}\n\n# Get you Dogecoin, Litecoin, and Bitcoin balances by using 'global'\n# credentials for Bitcoin and Dogecoin but specific credentials for\n# Litecoin.\ncoin_balance {\n # ...\n format = \"XDG: {dogecoin} LTC: {litecoin} BTC: {bitcoin}\"\n username = \"zcochrane\"\n password = \"sunny_islands\"\n litecoin_username = 'locutus'\n litecoin_password = 'NCC-1791-D'\n # ...\n}\nauthor Felix Morgner <felix.morgner@gmail.com>
license 3-clause-BSD
"},{"location":"user-guide/modules/#coin_market","title":"coin_market","text":"Display cryptocurrency coins.
The site offer various types of data such as name, symbol, price, volume, total supply, et cetera for a wide range of cryptocurrencies in various currencies. For more information, visit https://coinmarketcap.com
Configuration parameters:
api_key specify CoinMarketCap api key (default None)
cache_timeout refresh interval for this module. a message from the site: please limit requests to no more than 30 calls per minute. (default 600)
format display format for this module (default '{format_coin}')
format_coin display format for coins (default '{name} ${usd_price:.2f} ' '[\\?color=usd_percent_change_24h {usd_percent_change_24h:.1f}%]')
format_coin_separator show separator if more than one (default ' ')
markets specify a list of markets (default ['btc', 'eth'])
thresholds specify color thresholds to use (default [(-100, 'bad'), (0, 'good')])
Format placeholders:
{format_coin} format for cryptocurrency coinsformat_coin placeholders:
{circulating_supply} eg 17906012
{cmc_rank} eg 1
{date_added} eg 2013-04-28T00:00:00.000Z
{id} eg 1
{is_active} eg 1
{is_fiat} eg 0
{is_market_cap_included_in_calc} eg 1
{last_updated} eg 2019-08-30T18:51:28.000Z
{max_supply} eg 21000000
{name} eg Bitcoin
{num_market_pairs} eg 7919
{platform} eg None
{slug} eg bitcoin
{symbol} eg BTC
{tags} eg ['mineable']
{total_supply} eg 17906012
Placeholders are retrieved directly from the URL. The list was harvested once and should not represent a full list.
To print coins in different currencies, replicate the placeholders below with valid options (eg '{gbp_price:.2f}'):
{xxx_last_updated} eg 2019-08-30T18:51:28.000Z' {xxx_market_cap} eg 171155540318.86005 {xxx_percent_change_1h} eg -0.127291 {xxx_percent_change_24h} eg 0.328918 {xxx_percent_change_7d} eg -8.00576 {xxx_price} eg 9558.55163723 {xxx_volume_24h} eg 13728947008.2722
See https://coinmarketcap.com/api/documentation/v1/#section/Standards-and-Conventions for valid options, otherwise USD... in lowercase.
Color thresholds:
xxx print a color based on the value of xxx placeholderExamples:
# view coins in GBP and EUR\ncoin_market {\n format_coin = \"{name} \u00a3{gbp_price:.2f} \u20ac{eur_price:.2f}\"\n}\n\n# colorize market names + symbols\ncoin_market {\n format_coin = \"[\\?color=name {name}] \"\n format_coin += \"[\\?color=symbol {symbol}] ${usd_price:.2f} \"\n format_coin += \"[\\?color=usd_percent_change_24h {usd_percent_change_24h}%]\"\n markets = [\"btc\", \"eth\", \"ltc\", \"doge\"]\n thresholds = {\n \"name\": [\n (\"Bitcoin\", \"greenyellow\"),\n (\"Ethereum\", \"deepskyblue\"),\n (\"Litecoin\", \"crimson\"),\n (\"Dogecoin\", \"orange\"),\n ],\n \"symbol\": [\n (\"BTC\", \"darkgray\"),\n (\"ETH\", \"darkgray\"),\n (\"LTC\", \"darkgray\"),\n (\"DOGE\", \"darkgray\"),\n ],\n \"usd_percent_change_24h\": [(-100, \"bad\"), (0, \"good\")],\n }\n}\nauthor lasers, x86kernel
"},{"location":"user-guide/modules/#conky","title":"conky","text":"Display Conky objects/variables on the bar.
Configuration parameters:
config specify configuration settings for conky (default {})
format display format for this module (default None)
thresholds specify color thresholds to use (default [])
Format placeholders: According to man page, Conky has more than 250 built-in objects/variables.
See `man -P 'less -p OBJECTS/VARIABLES' conky` for a full list of Conky\nobjects/variables to use. Not all of Conky objects/variables will be\nsupported or usable.\nColor thresholds:
xxx print a color based on the value of xxx placeholder Replace spaces with periods.Examples:
# add conky config options\n# See `man -P \"less -p 'CONFIGURATION SETTINGS'\" conky` for a full list\n# of Conky configuration options. Not all of Conky configuration options\n# will be supported or usable.\nconky {\n config = {\n 'update_interval': 10 # update interval for conky\n 'update_interval_on_battery': 60 # update interval when on battery\n 'format_human_readable': True, # if False, print in bytes\n 'short_units': True, # shortens units, eg kiB->k, GiB->G\n 'uppercase': True, # upper placeholders\n }\n}\n\n# display ip address\norder += \"conky addr\"\nconky addr {\n format = 'IP [\\?color=orange {addr eno1}]'\n}\n\n# display load averages\norder += \"conky loadavg\"\nconky loadavg {\n format = 'Loadavg '\n format += '[\\?color=lightgreen {loadavg 1} ]'\n format += '[\\?color=lightgreen {loadavg 2} ]'\n format += '[\\?color=lightgreen {loadavg 3}]'\n}\n\n# exec commands at different intervals, eg 5s, 60s, and 3600s\norder += \"conky date\"\nconky date {\n format = 'Exec '\n format += '[\\?color=good {execi 5 \"date\"}] '\n format += '[\\?color=degraded {execi 60 \"uptime -p\"}] '\n format += '[\\?color=bad {execi 3600 \"uptime -s\"}]'\n}\n\n# display diskio read, write, etc\norder += \"conky diskio\"\nconky diskio {\n format = 'Disk IO [\\?color=darkgray&show sda] '\n format += '[\\?color=lightskyblue '\n format += '{diskio_read sda}/{diskio_write sda} '\n format += '({diskio sda})]'\n\n # format += ' '\n # format += '[\\?color=darkgray&show sdb] '\n # format += '[\\?color=lightskyblue '\n # format += '{diskio_read sdb}/{diskio_write sdb} '\n # format += '({diskio sdb})]'\n config = {'short_units': True}\n}\n\n# display total number of processes and running processes\norder += \"conky proc\"\nconky proc {\n format = 'Processes [\\?color=cyan {processes}/{running_processes}]'\n}\n\n# display top 3 cpu (+mem_res) processes\norder += \"conky top_cpu\" {\nconky top_cpu {\n format = 'Top [\\?color=darkgray '\n format += '{top name 1} '\n format += '[\\?color=deepskyblue {top mem_res 1}] '\n format += '[\\?color=lightskyblue {top cpu 1}%] '\n\n format += '{top name 2} '\n format += '[\\?color=deepskyblue {top mem_res 2}] '\n format += '[\\?color=lightskyblue {top cpu 2}%] '\n\n format += '{top name 3} '\n format += '[\\?color=deepskyblue {top mem_res 3}] '\n format += '[\\?color=lightskyblue {top cpu 3}%]]'\n config = {'short_units': True}\n}\n\n# display top 3 memory processes\norder += \"conky top_mem\"\nconky top_mem {\n format = 'Top Mem [\\?color=darkgray '\n format += '{top_mem name 1} '\n format += '[\\?color=yellowgreen {top_mem mem_res 1}] '\n format += '[\\?color=lightgreen {top_mem mem 1}%] '\n\n format += '{top_mem name 2} '\n format += '[\\?color=yellowgreen {top_mem mem_res 2}] '\n format += '[\\?color=lightgreen {top_mem mem 2}%] '\n\n format += '{top_mem name 3} '\n format += '[\\?color=yellowgreen {top_mem mem_res 3}] '\n format += '[\\?color=lightgreen {top_mem mem 3}%]]'\n config = {'short_units': True}\n}\n\n# display memory, memperc, membar + thresholds\norder += \"conky memory\"\nconky memory {\n format = 'Memory [\\?color=lightskyblue {mem}/{memmax}] '\n format += '[\\?color=memperc {memperc}% \\[{membar}\\]]'\n thresholds = [\n (0, 'darkgray'), (0.001, 'good'), (50, 'degraded'),\n (75, 'orange'), (85, 'bad')\n ]\n}\n\n# display swap, swapperc, swapbar + thresholds\norder += \"conky swap\"\nconky swap {\n format = 'Swap [\\?color=lightcoral {swap}/{swapmax}] '\n format += '[\\?color=swapperc {swapperc}% \\[{swapbar}\\]]'\n thresholds = [\n (0, 'darkgray'), (0.001, 'good'), (50, 'degraded'),\n (75, 'orange'), (85, 'bad')\n ]\n}\n\n# display up/down speed and up/down total\norder += \"conky network\"\nconky network {\n format = 'Speed [\\?color=title {upspeed eno1}/{downspeed eno1}] '\n format += 'Total [\\?color=title {totalup eno1}/{totaldown eno1}]'\n color_title = '#ff6699'\n}\n\n# display file systems + thresholds\norder += \"conky filesystem\"\nconky filesystem {\n # home filesystem\n format = 'Home [\\?color=violet {fs_used /home}/{fs_size /home} '\n format += '[\\?color=fs_used_perc./home '\n format += '{fs_used_perc /home}% \\[{fs_bar /home}\\]]]'\n\n # hdd filesystem\n # format += ' HDD [\\?color=violet {fs_used '\n # format += '/run/media/user/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\n # format += '}/{fs_size '\n # format += '/run/media/user/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\n # format += '}[\\?color=fs_used_perc.'\n # format += '/run/media/user/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\n # format += ' {fs_used_perc '\n # format += '/run/media/user/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\n # format += '}% \\[{fs_bar '\n # format += '/run/media/user/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\n # format += '}\\]]]'\n\n thresholds = [\n (0, 'darkgray'), (0.001, 'good'), (50, 'degraded'),\n (75, 'orange'), (85, 'bad')\n ]\n}\n\n# show cpu percents/bars + thresholds\norder += \"conky cpu\"\nconky cpu {\n format = 'CPU '\n format += '[\\?color=cpu.cpu0 {cpu cpu0}% {cpubar cpu0}] '\n format += '[\\?color=cpu.cpu1 {cpu cpu1}% {cpubar cpu1}] '\n format += '[\\?color=cpu.cpu2 {cpu cpu2}% {cpubar cpu2}] '\n format += '[\\?color=cpu.cpu3 {cpu cpu3}% {cpubar cpu3}]'\n\n thresholds = [\n (0, 'darkgray'), (0.001, 'good'), (50, 'degraded'),\n (75, 'orange'), (85, 'bad')\n ]\n}\n\n# show more examples, many outputs\norder += \"conky info\"\nconky info {\n format = '[\\?color=title&show OS] [\\?color=output {distribution}] '\n format += '[\\?color=title&show CPU] [\\?color=output {cpu cpu0}%] '\n format += '[\\?color=title&show MEM] '\n format += '[\\?color=output {mem}/{memmax} ({memperc}%)] '\n format += '[\\?color=title&show HDD] [\\?color=output {fs_used_perc}%] '\n format += '[\\?color=title&show Kernel] [\\?color=output {kernel}] '\n format += '[\\?color=title&show Loadavg] [\\?color=output {loadavg 1}] '\n format += '[\\?color=title&show Uptime] [\\?color=output {uptime}] '\n format += '[\\?color=title&show Freq GHZ] [\\?color=output {freq_g}]'\n color_title = '#ffffff'\n color_output = '#00bfff'\n}\n\n# change console bars - shoutout to su8 for adding this\nconky {\n config = {\n 'console_bar_fill': \"'#'\",\n 'console_bar_unfill': \"'_'\",\n 'default_bar_width': 10,\n }\n}\n\n# display nvidia stats - shoutout to brndnmtthws for fixing this\n# See `man -P 'less -p nvidia\\ argument' conky` for more nvidia variables.\norder += \"conky nvidia\"\nconky nvidia {\n format = 'GPU Temp [\\?color=greenyellow {nvidia temp}] '\n format += 'GPU Freq [\\?color=greenyellow {nvidia gpufreq}] '\n format += 'Mem Freq [\\?color=greenyellow {nvidia memfreq}] '\n format += 'MTR Freq [\\?color=greenyellow {nvidia mtrfreq}] '\n format += 'Perf [\\?color=greenyellow {nvidia perflevel}] '\n format += 'Mem Perc [\\?color=greenyellow {nvidia memperc}]'\n config = {\n 'nvidia_display': \"':0'\"\n }\n}\nauthor lasers
"},{"location":"user-guide/modules/#deadbeef","title":"deadbeef","text":"Display songs currently playing in DeaDBeeF.
Configuration parameters:
cache_timeout refresh interval for this module (default 5)
format display format for this module (default '[{artist} - ][{title}]')
replacements specify a list/dict of string placeholders to modify (default None)
sleep_timeout when deadbeef is not running, this interval will be used to allow faster refreshes with time-related placeholders and/or to refresh few times per minute rather than every few seconds (default 20)
Format placeholders:
{album} name of the album
{artist} name of the artist
{length} length time in [HH:]MM:SS
{playback_time} elapsed time in [HH:]MM:SS
{title} title of the track
{tracknumber} track number in two digits
{year} year in four digits
For more placeholders, see title formatting 2.0 in 'deadbeef --help' or https://github.com/DeaDBeeF-Player/deadbeef/wiki/Title-formatting-2.0 Not all of Foobar2000 remapped metadata fields will work with deadbeef and a quick reminder about using {placeholders} here instead of %placeholder%.
Color options:
color_paused Paused, defaults to color_degraded
color_playing Playing, defaults to color_good
color_stopped Stopped, defaults to color_bad
Requires:
deadbeef a GTK+ audio player for GNU/LinuxExamples:
# see 'deadbeef --help' for more buttons\ndeadbeef {\n on_click 1 = 'exec deadbeef --play-pause'\n on_click 8 = 'exec deadbeef --random'\n}\nauthor mrt-prodz
"},{"location":"user-guide/modules/#dexcom","title":"dexcom","text":"Display glucose readings from your Dexcom CGM system.
Dexcom CGM systems provide glucose readings up to every five minutes. Designed to help diabetes patients keep track of their blood glucose levels with ease.
Configuration parameters:
format display format for this module (default \"Dexcom [\\?color=mg_dl {mg_dl} mg/dL {trend_arrow}] [\\?color=darkgrey {datetime}]\")
format_datetime specify strftime characters to format (default {\"datetime\": \"%-I:%M %p\"})
ous specify whether if the Dexcom Share user is outside of the US (default False)
password specify password for the Dexcom Share user (default None)
thresholds specify color thresholds to use (default { \"mg_dl\": [(55, \"bad\"), (70, \"degraded\"), (80, \"good\"), (130, \"degraded\"), (180, \"bad\")], \"mmol_l\": [(3.1, \"bad\"), (3.9, \"degraded\"), (4.4, \"good\"), (7.2, \"degraded\"), (10.0, \"bad\")], })
username specify username for the Dexcom Share user, not follower (default None)
Format placeholders:
{mg_dl} blood glucose value in mg/dL, eg 80
{mmol_l} blood glucose value in mmol/L, eg 4.4
{trend} blood glucose trend information, eg 4
{trend_direction} blood glucose trend direction, eg Flat
{trend_description} blood glucose trend information description, eg steady
{trend_arrow} blood glucose trend as unicode arrow, eg \u2192
{datetime} glucose reading recorded time as datetime
format_datetime placeholders:
key epoch_placeholder, eg {datetime}
value % strftime characters to be translated, eg '%b %d' ----> 'Jan 1'
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
pydexcom A simple Python API to interact with Dexcom Share serviceNotes: IF GLUCOSE ALERTS AND CGM READINGS DO NOT MATCH SYMPTOMS OR EXPECTATIONS, USE A BLOOD GLUCOSE METER TO MAKE DIABETES TREATMENT DECISIONS.
Examples:
# compact\ndexcom {\n format = \"[\\?color=mg_dl {mg_dl} {trend_arrow}][\\?color=darkgrey {datetime}]\"\n format_datetime = {\"datetime\": \"%-I:%M\"}\n}\nauthor lasers
"},{"location":"user-guide/modules/#diskdata","title":"diskdata","text":"Display disk information.
Configuration parameters:
cache_timeout refresh interval for this module. (default 10)
disk show stats for disk or partition, i.e. sda1. None for all disks. (default None)
format display format for this module. (default \"{disk}: {used_percent}%[ ({total})]\")
format_rate display format for rates value (default \"[\\?min_length=11 {value:.1f} {unit}]\")
format_space display format for disk space values (default \"[\\?min_length=5 {value:.1f}]\")
sector_size size of the disk's sectors. (default 512)
si_units use SI units (default False)
thresholds specify color thresholds to use (default {'free': [(0, 'bad'), (10, 'degraded'), (100, 'good')], 'total': [(0, 'good'), (1024, 'degraded'), (1024 * 1024, 'bad')], 'used_percent': [(0, 'good'), (40, 'degraded'), (75, 'bad')]})
unit unit to use. If the unit contains a multiplier prefix, only this exact unit will ever be used (default \"B/s\")
Format placeholders:
{disk} the selected disk
{free} free space on disk in GB
{used} used space on disk in GB
{total_space} total space on disk in GB
{used_percent} used space on disk in %
{read} reading rate
{total} total IO rate
{write} writing rate
format_rate placeholders:
{unit} name of the unit
{value} numeric value of the rate
format_space placeholders:
{value} numeric value of the free/used space on the deviceColor thresholds:
{free} Change color based on the value of free
{used} Change color based on the value of used
{used_percent} Change color based on the value of used_percent
{read} Change color based on the value of read
{total} Change color based on the value of total
{write} Change color based on the value of write
author guiniol
license BSD
"},{"location":"user-guide/modules/#do_not_disturb","title":"do_not_disturb","text":"Turn on and off desktop notifications.
Configuration parameters:
cache_timeout refresh interval for this module; for xfce4-notifyd (default 30)
format display format for this module (default '{name} [\\?color=state&show DND]')
pause specify whether to pause or kill processes; for dunst see Dunst Miscellaneous section for more information (default True)
server specify server to use, eg mako, dunst or xfce4-notifyd, otherwise auto (default None)
state specify state to use on startup, otherwise last False: disable Do Not Disturb on startup True: enable Do Not Disturb on startup last: toggle last known state on startup None: query current state from notification manager (doesn't work on dunst<1.5.0) (default 'last')
thresholds specify color thresholds to use (default [(0, 'bad'), (1, 'good')])
Format placeholders:
{name} name, eg Mako, Dunst, Xfce4-notifyd
{state} do not disturb state, eg 0, 1
Color thresholds:
xxx print a color based on the value of xxx placeholderDunst Miscellaneous: When paused, dunst will not display any notifications but keep all notifications in a queue. This can for example be wrapped around a screen locker (i3lock, slock) to prevent flickering of notifications through the lock and to read all missed notifications after returning to the computer. This means that by default (pause = False), all notifications sent while DND is active will NOT be queued and displayed when DND is deactivated.
Mako Miscellaneous: Mako requires that you manually create a 'do-not-disturb' mode as shown in https://man.voidlinux.org/mako.5#MODES. This module expects this mode to be configured by the user as suggested by the mako documentation: [mode=do-not-disturb] invisible=1
Examples:
# display ON/OFF\ndo_not_disturb {\n format = '{name} [\\?color=state [\\?if=state ON|OFF]]'\n}\n\n# display 1/0\ndo_not_disturb {\n format = '{name} [\\?color=state {state}]'\n}\n\n# display DO NOT DISTURB/DISTURB\ndo_not_disturb {\n format = '[\\?color=state [\\?if=state DO NOT DISTURB|DISTURB]]'\n thresholds = [(0, \"darkgray\"), (1, \"good\")]\n}\nauthor Maxim Baz https://github.com/maximbaz (dunst)
author Robert Ricci https://github.com/ricci (xfce4-notifyd)
author Cyrinux https://github.com/cyrinux (mako)
license BSD
"},{"location":"user-guide/modules/#dpms","title":"dpms","text":"Turn on and off DPMS and screen saver blanking.
Configuration parameters:
button_off mouse button to turn off screen (default None)
button_toggle mouse button to toggle DPMS (default 1)
cache_timeout refresh interval for this module (default 15)
format display format for this module (default '{icon}')
icon_off show when DPMS is disabled (default 'DPMS')
icon_on show when DPMS is enabled (default 'DPMS')
Format placeholders:
{icon} DPMS iconColor options:
color_on Enabled, defaults to color_good
color_off Disabled, defaults to color_bad
author Andre Doser <dosera AT tf.uni-freiburg.de>
"},{"location":"user-guide/modules/#dropboxd_status","title":"dropboxd_status","text":"Display status of Dropbox daemon.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default \"Dropbox: {status}\")
status_busy text for placeholder {status} when Dropbox is busy (default None)
status_off text for placeholder {status} when Dropbox isn't running (default \"isn't running\")
status_on text for placeholder {status} when Dropbox is up to date (default \"Up to date\")
Value for status_off if not set: - Dropbox isn't running!
Value for status_on if not set: - Up to date
Values for status_busy if not set: - Connecting... - Starting... - Downloading file list... - Syncing \"filename\"
Format placeholders:
{status} Dropbox statusColor options:
color_bad Not running
color_degraded Busy
color_good Up to date
Requires:
dropbox-cli command line interface for dropboxNotes: Some distributions offer an option to install dropbox-cli. If you don't see one for your distribution, then you need to download CLI Python script, https://www.dropbox.com/help/desktop-web/linux-commands#commands, rename it to dropbox-cli, make the script executable and available in your PATH.
author Tjaart van der Walt (github:tjaartvdwalt)
license BSD
"},{"location":"user-guide/modules/#emerge_status","title":"emerge_status","text":"Display information about the currently running emerge process.
Configuration parameters:
cache_timeout how often we refresh this module in second. NOTE: when emerge is running, we will refresh this module every second. (default 30)
emerge_log_file path to the emerge log file. (default '/var/log/emerge.log')
format display format for this module (default '{prefix}[\\?if=is_running : [\\?if=!total=0 ' '[{current}/{total} {action} {category}/{pkg}]' '|calculating...]|: stopped 0/0]')
prefix prefix in statusbar (default \"emrg\")
Format placeholders:
{action} current emerge action
{category} category of the currently emerged package
{current} number of package that is currently emerged
{pkg} name of the currently emerged packaged
{total} total number of packages that will be emerged
Examples:
# Hide if not running\nemerge_status {\n format = \"[\\?if=is_running {prefix}: [\\?if=!total=0 \"\n format += \"{current}/{total} {action} {category}/{pkg}\"\n format += \"|calculating...]]\"\n}\n\n# Minimalistic\nemerge_status {\n format = \"[\\?if=is_running [\\?if=!total=0 {current}/{total}]]\"\n}\n\n# Minimalistic II\nemerge_status {\n format = \"[\\?if=is_running {current}/{total}]\"\n}\nauthor AnwariasEu
"},{"location":"user-guide/modules/#exchange_rate","title":"exchange_rate","text":"Display foreign exchange rates.
Configuration parameters:
api_key the exchangeratesapi.io API access key (default None)
base specify base currency to use for exchange rates (default 'EUR')
cache_timeout refresh interval for this module (default 600)
format display format for this module (default '${USD} \u00a3{GBP} \u00a5{JPY}')
Format placeholders: See https://api.exchangeratesapi.io/latest for a full list of foreign exchange rates published by the European Central Bank. Not all of exchange rates will be available. Also, see https://en.wikipedia.org/wiki/ISO_4217
author tobes
license BSD
"},{"location":"user-guide/modules/#external_script","title":"external_script","text":"Display output of a given script.
Display output of any executable script set by script_path. Only the first two lines of output will be used. The first line is used as the displayed text. If the output has two or more lines, the second line is set as the text color (and should hence be a valid hex color code such as #FF0000 for red). If the second line is urgent, or has ! prefixing the hex color, then the \"urgent\" flag will be set. The script should not have any parameters, but it could work.
Configuration parameters:
button_show_notification button to show notification with full output (default None)
cache_timeout how often we refresh this module in seconds (default 15)
convert_numbers convert decimal numbers to a numeric type (default True)
format see placeholders below (default '{output}')
localize should script output be localized (if available) (default True)
script_path script you want to show output of (compulsory) (default None)
strip_output shall we strip leading and trailing spaces from output (default False)
Format placeholders:
{lines} number of lines in the output
{output} output of script given by \"script_path\"
{composite} composite output of script given by \"script_path\"
Examples:
external_script {\n format = \"my name is {output}\"\n script_path = \"/usr/bin/whoami\"\n}\nauthor frimdo ztracenastopa@centrum.cz
"},{"location":"user-guide/modules/#fedora_updates","title":"fedora_updates","text":"Display number of pending updates for Fedora Linux.
This will display a count of how many dnf updates are waiting to be installed. Additionally check for update security notices.
Configuration parameters:
cache_timeout How often we refresh this module in seconds (default 600)
check_security Check for security updates (default True)
format Display format to use (default 'DNF: {updates}')
Format placeholders:
{updates} number of pending dnf updatesColor options:
color_bad Security notice
color_degraded Upgrade available
color_good No upgrades needed
author tobes
license BSD
"},{"location":"user-guide/modules/#file_status","title":"file_status","text":"Display if files or directories exists.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '\\?color=path [\\?if=path \u25cf|\u25a0]')
format_path format for paths (default '{basename}')
format_path_separator show separator if more than one (default ' ')
paths specify a string or a list of paths to check (default None)
thresholds specify color thresholds to use (default [(0, 'bad'), (1, 'good')])
Format placeholders:
{format_path} format for paths
{path} number of paths, eg 1, 2, 3
format_path placeholders:
{basename} basename of pathname
{pathname} pathname
Color options:
color_bad files or directories does not exist
color_good files or directories exists
Color thresholds:
format path: print a color based on the number of pathsExamples:
# add multiple paths with wildcard or with pathnames\nfile_status {\n paths = ['/tmp/test*', '~user/test1', '~/Videos/*.mp4']\n}\n\n# colorize basenames\nfile_status {\n paths = ['~/.config/i3/modules/*.py']\n format = '{format_path}'\n format_path = '\\?color=good {basename}'\n format_path_separator = ', '\n}\nauthor obb, Moritz L\u00fcdecke, Cyril Levis (@cyrinux)
"},{"location":"user-guide/modules/#frame","title":"frame","text":"Group modules and treat them as a single one.
This can be useful for example when adding modules to a group and you wish two modules to be shown at the same time.
By adding the {button} placeholder in the format you can enable a toggle button to hide or show the content.
Configuration parameters:
button_toggle Button used to toggle if one in format. Setting to None disables (default 1)
format Display format to use (default '{output}')
format_button_closed Format for the button when frame open (default '+')
format_button_open Format for the button when frame closed (default '-')
format_separator Specify separator between contents. If this is None then the default i3bar separator will be used (default None)
open If button then the frame can be set to be open or close (default True)
Format placeholders:
{button} If used a button will be used that can be clicked to hide/show the contents of the frame.
{output} The output of the modules in the frame
{output_xxx} The output of the module xxx (even if the button is currently toggled off).
Examples:
# A frame showing times in different cities.\n# We also have a button to hide/show the content\nframe time {\n format = '{output}{button}'\n format_separator = ' ' # have space instead of usual i3bar separator\n\n tztime la {\n format = \"LA %H:%M\"\n timezone = \"America/Los_Angeles\"\n }\n tztime ny {\n format = \"NY %H:%M\"\n timezone = \"America/New_York\"\n }\n tztime du {\n format = \"DU %H:%M\"\n timezone = \"Asia/Dubai\"\n }\n}\n\n# Define a group which shows volume and battery info or the current time.\n# The frame, volume_status and battery_level modules are named to prevent\n# them clashing with any other defined modules of the same type.\ngroup {\n frame {\n volume_status {}\n battery_level {}\n }\n time {}\n}\n\n# Define a group where the button is colored only if sub module has some output\nframe ipv6 {\n format = \"[\\?if=output_ipv6 {output}{button}|\\?color=#bad {output}{button}]\"\n open = false\n\n ipv6 {\n format_up = \"%ip\"\n format_down = \"\"\n }\n}\nauthor tobes
"},{"location":"user-guide/modules/#getjson","title":"getjson","text":"Display JSON data fetched from a URL.
This module gets the given url configuration parameter and assumes the response is a JSON object. The keys of the JSON object are used as the format placeholders. The format placeholders are replaced by the value. Objects that are nested can be accessed by using the delimiter configuration parameter in between.
Configuration parameters:
cache_timeout refresh interval for this module (default 30)
delimiter the delimiter between parent and child objects (default '-')
format display format for this module (default None)
password basic auth password information (default None)
url specify URL to fetch JSON from (default None)
username basic auth user information (default None)
Format placeholders: Placeholders will be replaced by the JSON keys.
Placeholders for objects with sub-objects are flattened using 'delimiter'\nin between (eg. {'parent': {'child': 'value'}} will use placeholder\n{parent-child}).\n\nPlaceholders for list elements have 'delimiter' followed by the index\n(eg. {'parent': ['this', 'that']) will use placeholders {parent-0}\nfor 'this' and {parent-1} for 'that'.\nExamples:
# straightforward key replacement\ngetjson {\n url = \"https://ifconfig.co/json\"\n format = \"{latitude}, {longitude}\"\n}\n\n# access child objects\ngetjson {\n url = 'https://api.icndb.com/jokes/random'\n format = '{value-joke}'\n}\n\n# access title from 0th element of articles list\ngetjson {\n url = 'https://newsapi.org/v1/articles?source=bbc-news&sortBy=top&apiKey={KEY}'\n format = '{articles-0-title}'\n}\n\n# access if top-level object is a list\ngetjson {\n url = 'https://jsonplaceholder.typicode.com/posts/1/comments'\n format = '{0-name}'\n}\nauthor vicyap
"},{"location":"user-guide/modules/#github","title":"github","text":"Display Github notifications and issue/pull requests for a repo.
To check notifications a Github username and personal access token are required. You can create a personal access token at https://github.com/settings/tokens/new?scopes=notifications&description=py3status The only scope needed is notifications is selected automatically for you, which provides readonly access to notifications.
The Github API is rate limited so setting cache_timeout too small may cause issues see https://developer.github.com/v3/#rate-limiting for details
Configuration parameters:
auth_token Github personal access token, needed to check notifications see above. (default None)
button_action Button that when clicked opens the Github notification page if notifications, else the project page for the repository if there is one (otherwise the github home page). Setting to None disables. (default 3)
button_refresh Button that when clicked refreshes module. Setting to None disables. (default 2)
cache_timeout How often we refresh this module in seconds (default 60)
format display format for this module, see Examples below (default None)
format_notifications Format of {notification} status placeholder. (default ' N{notifications_count}')
notifications Type of notifications can be all for all notifications or repo to only get notifications for the repo specified. If repo is not provided then all notifications will be checked. (default 'all')
repo Github repo to check (default 'ultrabug/py3status')
url_api Change only if using Enterprise Github, example https://github.domain.com/api/v3. (default 'https://api.github.com')
url_base Change only if using Enterprise Github, example https://github.domain.com. (default 'https://github.com')
username Github username, needed to check notifications. (default None)
Format placeholders:
{issues} Number of open issues.
{notifications} Notifications. If no notifications this will be empty.
{notifications_count} Number of notifications. This is also the Only placeholder available to format_notifications.
{pull_requests} Number of open pull requests
{repo} short name of the repository being checked. eg py3status
{repo_full} full name of the repository being checked. eg ultrabug/py3status
Examples:
# default formats\ngithub {\n # with username and auth_token, this will be used\n format = '{repo} {issues}/{pull_requests}{notifications}'\n\n # otherwise, this will be used\n format '{repo} {issues}/{pull_requests}'\n}\n\n# set github access credentials\ngithub {\n auth_token = '40_char_hex_access_token'\n username = 'my_username'\n}\n\n# just check for any notifications\ngithub {\n auth_token = '40_char_hex_access_token'\n username = 'my_username'\n format = 'Github {notifications_count}'\n}\nauthor tobes
"},{"location":"user-guide/modules/#gitlab","title":"gitlab","text":"Display number of issues, requests and more from a GitLab project.
A token is required. See https://gitlab.com/profile/personal_access_tokens to make one. Make a name, eg py3status, and enable api in scopes. Save.
Configuration parameters:
auth_token specify a personal access token to use (default None)
button_open mouse button to open project url (default 1)
button_refresh mouse button to refresh this module (default 2)
cache_timeout refresh interval for this module (default 900)
format display format for this module (default '[{name} ][[{open_issues_count}][\\?soft /]' '[{open_merge_requests_count}]]')
project specify a project to use (default 'gitlab-org/gitlab-ce')
thresholds specify color thresholds to use (default [])
Format placeholders: See sp below for a full list of supported GitLab placeholders to use. Not all of GitLab placeholders will be usable.
single_project:\n {name} project name, eg py3status\n {star_count} number of stars, eg 2\n {forks_count} number of forks, eg 3\n {open_issues_count} number of open issues, eg 4\n {statistics_commit_count} number of commits, eg 5678\nmerge_requests:\n {open_merge_requests_count} number of open merge requests, eg 9\ntodos:\n {todos_count} number of todos, eg 4\npipelines:\n {pipelines_status} project status of pipelines, eg success\nNotes:
sp https://docs.gitlab.com/ee/api/projects.html#get-single-project
mr https://docs.gitlab.com/ee/api/merge_requests.html
td https://docs.gitlab.com/ee/api/todos.html
pipe https://docs.gitlab.com/ee/api/pipelines.html
Color thresholds:
xxx print a color based on the value of xxx placeholderExamples:
# follow a fictional project, add an icon\ngitlab {\n auth_token = 'abcdefghijklmnopq-a4'\n project = 'https://gitlab.com/ultrabug/py3status'\n\n format = '[\\?if=name [\\?color=orangered&show \uf296] {name} ]'\n format += '[[{open_issues_count}][\\?soft /]'\n format += '[{open_merge_requests_count}][\\?soft /]'\n format += '[{pipelines_status}]]'\n}\nauthor lasers, Cyril Levis (@cyrinux)
"},{"location":"user-guide/modules/#glpi","title":"glpi","text":"Display number of open tickets from GLPI.
It features thresholds to colorize the output and forces a low timeout to limit the impact of a server connectivity problem on your i3bar freshness.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 300)
critical set bad color above this threshold (default 20)
db database to use (default '')
format format of the module output (default '{tickets_open} tickets')
host database host to connect to (default '')
password login password (default '')
timeout timeout for database connection (default 5)
user login user (default '')
warning set degraded color above this threshold (default 15)
Format placeholders:
{tickets_open} The number of open ticketsColor options:
color_bad Open ticket above critical threshold
color_degraded Open ticket above warning threshold
Requires: MySQL-python: https://pypi.org/project/MySQL-python/
author ultrabug
"},{"location":"user-guide/modules/#google_calendar","title":"google_calendar","text":"Display upcoming Google Calendar events.
This module will display information about upcoming Google Calendar events in one of two formats which can be toggled with a button press. The event URL may also be opened in a web browser with a button press.
Some events details can be retreived in the Google Calendar API Documentation. https://developers.google.com/calendar/v3/reference/events
Configuration parameters:
auth_token The path to where the access/refresh token will be saved after successful credential authorization. (default '~/.config/py3status/google_calendar.auth_token')
blacklist_events Event names in this list will not be shown in the module (case insensitive). (default [])
browser_invocation Command to run to open browser. Curly braces stands for URL opened. (default \"xdg-open {}\")
button_open Opens the event URL in the default web browser. (default 3)
button_refresh Refreshes the module and updates the list of events. (default 2)
button_toggle Toggles a boolean to hide/show the data for each event. (default 1)
cache_timeout How often the module is refreshed in seconds (default 60)
calendar_id The ID of the calendar to display. (default \"primary\")
client_secret the path to your client_secret file which contains your OAuth 2.0 credentials. (default '~/.config/py3status/google_calendar.client_secret')
events_within_hours Select events within the next given hours. (default 12)
force_lowercase Sets whether to force all event output to lower case. (default False)
format The format for module output. (default '{events}|\\?color=event \u2687')
format_date The format for date related format placeholders. May be any Python strftime directives for dates. (default '%a %d-%m')
format_event The format for each event. The information can be toggled with 'button_toggle' based on the value of 'is_toggled'. (default '[\\?color=event {summary}][\\?if=is_toggled ({start_time}' ' - {end_time}, {start_date})|[ ({location})][ {format_timer}]]')
format_notification The format for event warning notifications. (default '{summary} {start_time} - {end_time}')
format_separator The string used to separate individual events. (default ' | ')
format_time The format for time-related placeholders except {format_timer}. May use any Python strftime directives for times. (default '%I:%M %p')
format_timer The format used for the {format_timer} placeholder to display time until an event starts or time until an event in progress is over. (default '\\?color=time ([\\?if=days {days}d ][\\?if=hours {hours}h ]' '[\\?if=minutes {minutes}m])[\\?if=is_current left]')
ignore_all_day_events Sets whether to display all day events or not. (default False)
num_events The maximum number of events to display. (default 3)
preferred_event_link link to open in the browser. accepted values : hangoutLink (open the VC room associated with the event), htmlLink (open the event's details in Google Calendar) fallback to htmlLink if the preferred_event_link does not exist it the event. (default \"htmlLink\")
response Only display events for which the response status is on the list. Available values in the Google Calendar API's documentation, look for the attendees[].responseStatus. (default ['accepted'])
thresholds Thresholds for events. The first entry is the color for event 1, the second for event 2, and so on. (default [])
time_to_max Threshold (in minutes) for when to display the {format_timer} string; e.g. if time_to_max is 60, {format_timer} will only be displayed for events starting in 60 minutes or less. (default 180)
warn_threshold The number of minutes until an event starts before a warning is displayed to notify the user; e.g. if warn_threshold is 30 and an event is starting in 30 minutes or less, a notification will be displayed. disabled by default. (default 0)
warn_timeout The number of seconds before a warning should be issued again. (default 300)
Control placeholders:
{is_toggled} a boolean toggled by button_toggleFormat placeholders:
{events} All the events to display.format_event and format_notification placeholders:
{description} The description for the calendar event.
{end_date} The end date for the event.
{end_time} The end time for the event.
{location} The location for the event.
{start_date} The start date for the event.
{start_time} The start time for the event.
{summary} The summary (i.e. title) for the event.
{format_timer} The time until the event starts (or until it is over if already in progress).
format_timer placeholders:
{days} The number of days until the event.
{hours} The number of hours until the event.
{minutes} The number of minutes until the event.
Color options:
color_event Color for a single event.
color_time Color for the time associated with each event.
Requires: 1. Python library google-api-python-client. 2. Python library python-dateutil. 3. OAuth 2.0 credentials for the Google Calendar api.
Follow Step 1 of the guide here to obtain your OAuth 2.0 credentials:\nhttps://developers.google.com/google-apps/calendar/quickstart/python\n\nDownload the client_secret.json file which contains your client ID and\nclient secret. In your config file, set configuration parameter\nclient_secret to the path to your client_secret.json file.\n\nThe first time you run the module, a browser window will open asking you\nto authorize access to your calendar. After authorization is complete,\nan access/refresh token will be saved to the path configured in\nauth_token, and i3status will be restarted. This restart will\noccur only once after the first time you successfully authorize.\nExamples:
# add color gradients for events and dates/times\ngoogle_calendar {\n thresholds = {\n 'event': [(1, '#d0e6ff'), (2, '#bbdaff'), (3, '#99c7ff'),\n (4, '#86bcff'), (5, '#62a9ff'), (6, '#8c8cff'), (7, '#7979ff')],\n 'time': [(1, '#ffcece'), (2, '#ffbfbf'), (3, '#ff9f9f'),\n (4, '#ff7f7f'), (5, '#ff5f5f'), (6, '#ff3f3f'), (7, '#ff1f1f')]\n }\n}\nauthor Igor Grebenkov
license BSD
"},{"location":"user-guide/modules/#graphite","title":"graphite","text":"Display Graphite metrics.
Configuration parameters:
cache_timeout how often we refresh this module in seconds. (default 120)
datapoint_selection when multiple data points are returned, use \"max\" or \"min\" to determine which one to display. (default \"max\")
format you MUST use placeholders here to display data, see below. (default '')
graphite_url URL to your graphite server. (default '')
http_timeout HTTP query timeout to graphite. (default 10)
proxy You can configure the proxy with HTTP or HTTPS. examples: proxy = 'https://myproxy.example.com:1234/' proxy = 'http://user:passwd@myproxy.example.com/' proxy = 'socks5://user:passwd@host:port' (proxy_socks is available after an 'pip install requests[socks]') (default None)
targets semicolon separated list of targets to query graphite for. (default '')
threshold_bad numerical threshold, if set will send a notification and colorize the output. (default None)
threshold_degraded numerical threshold, if set will send a notification and colorize the output. (default None)
timespan time range to query graphite for. (default \"-2minutes\")
value_comparator choose between \"max\" and \"min\" to compare thresholds to the data point value. (default \"max\")
value_format pretty format long numbers with \"K\", \"M\" etc. (default True)
value_round round values so they're not displayed as floats. (default True)
Dynamic format placeholders: The \"format\" parameter placeholders are dynamically based on the data points names returned by the \"targets\" query to graphite.
For example if your target is `\"carbon.agents.localhost-a.memUsage\"`,\nyou'd get a JSON result like this:\n\n ```\n {\n \"target\": \"carbon.agents.localhost-a.memUsage\",\n \"datapoints\": [[19693568.0, 1463663040]]\n }\n ```\n\nSo the placeholder you could use on your \"format\" config is:\n `format = \"{carbon.agents.localhost-a.memUsage}\"`\n\nTIP: use aliases !\n ```\n targets = \"alias(carbon.agents.localhost-a.memUsage, 'local_memuse')\"\n format = \"local carbon mem usage: {local_memuse} bytes\"\n ```\nColor options:
color_bad threshold_bad has been exceeded
color_degraded threshold_degraded has been exceeded
author ultrabug
"},{"location":"user-guide/modules/#group","title":"group","text":"Group modules and switch between them.
Groups can be configured in your config. The active one of these groups is shown in the i3bar. The active group can be changed by a user click. If the click is not used by the group module then it will be passed down to the displayed module.
Modules can be i3status core modules or py3status modules. The active group can be cycled through automatically.
The group can handle clicks by reacting to any that are made on it or its content or it can use a button and only respond to clicks on that. The way it does this is selected via the click_mode option.
Configuration parameters:
align Text alignment when fixed_width is set can be 'left', 'center' or 'right' (default 'center')
button_next Button that when clicked will switch to display next module. Setting to 0 will disable this action. (default 5)
button_prev Button that when clicked will switch to display previous module. Setting to 0 will disable this action. (default 4)
button_toggle Button that when clicked toggles the group content being displayed between open and closed. This action is ignored if {button} is not in the format. Setting to 0 will disable this action (default 1)
click_mode This defines how clicks are handled by the group. If set to all then the group will respond to all click events. This may cause issues with contained modules that use the same clicks that the group captures. If set to button then only clicks that are directly on the {button} are acted on. The group will need {button} in its format. (default 'all')
cycle Time in seconds till changing to next module to display. Setting to 0 will disable cycling. (default 0)
fixed_width Reduce the size changes when switching to new group (default False)
format display format for this module, see Examples below (default None)
format_button_closed Format for the button when group open (default '+')
format_button_open Format for the button when group closed (default '-')
format_closed Format for module output when closed. (default \"{button}\")
open Is the group open and displaying its content. Has no effect if {button} not in format (default True)
Format placeholders:
{button} The button to open/close or change the displayed group
{output} Output of current active module
Examples:
# default formats\ngroup {\n format = '{output}' # if click_mode is 'all'\n format = '{output} {button}' # if click_mode is 'button'\n}\n\n# Create a disks group that will show space on '/' and '/home'\n# Change between disk modules every 30 seconds\norder += \"group disks\"\ngroup disks {\n cycle = 30\n format = \"Disks: {output} {button}\"\n click_mode = \"button\"\n\n disk \"/\" {\n format = \"/ %avail\"\n }\n disk \"/home\" {\n format = \"/home %avail\"\n }\n}\nauthor tobes
"},{"location":"user-guide/modules/#hamster","title":"hamster","text":"Display time tracking activities from Hamster.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 10)
format see placeholders below (default '{current}')
Format placeholders:
{current} current activityRequires:
hamster time tracking applicationauthor Aaron Fields (spirotot [at] gmail.com)
license BSD
"},{"location":"user-guide/modules/#hddtemp","title":"hddtemp","text":"Display hard drive temperatures.
hddtemp is a small utility with daemon that gives the hard drive temperature via S.M.A.R.T. (Self-Monitoring, Analysis, and Reporting Technology). This module requires the user-defined hddtemp daemon to be running at all times.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{format_hdd}')
format_hdd display format for hard drives (default '{name} [\\?color=temperature {temperature}\u00b0{unit}]')
format_separator show separator if more than one (default ' ')
thresholds specify color thresholds to use (default [(19, 'skyblue'), (24, 'deepskyblue'), (25, 'lime'), (41, 'yellow'), (46, 'orange'), (51, 'red'), (56, 'tomato')])
Format placeholders:
{format_hdd} format for hard drivesformat_hdd placeholders:
{name} name, eg ADATA SP550
{path} path, eg /dev/sda
{temperature} temperature, eg 32
{unit} temperature unit, eg C
Temperatures: Less than 25\u00b0C: Too cold (color deepskyblue) 25\u00b0C to 40\u00b0C: Ideal (color good) 41\u00b0C to 50\u00b0C: Acceptable (color degraded) 46\u00b0C to 50\u00b0C: Almost too hot (color orange) More than 50\u00b0C: Too hot (color bad)
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
hddtemp utility to monitor hard drive temperatures
nc netcat / ncat is command-line utility for reading data from hddtemp telnet interface
Bible of HDD failures: Hard disk temperatures higher than 45\u00b0C led to higher failure rates. Temperatures lower than 25\u00b0C led to higher failure rates as well. Aging hard disk drives (3 years and older) were much more prone to failure when their average temperatures were 40\u00b0C and higher.
Hard disk manufacturers often state the operating temperatures of\ntheir hard disk drives to be between 0\u00b0C to 60\u00b0C. This can be misleading\nbecause what they mean is that your hard disk will function at these\ntemperatures, but it doesn't tell you anything about how long they are\ngoing to survive at this range.\nhttp://www.buildcomputers.net/hdd-temperature.html\nBackblaze: Overall, there is not a correlation between operating temperature and failure rates The one exception is the Seagate Barracuda 1.5TB drives, which fail slightly more when they run warmer. As long as you run drives well within their allowed range of operating temperatures, keeping them cooler doesn\u2019t matter. https://www.backblaze.com/blog/hard-drive-temperature-does-it-matter/
Examples:
# compact the format\nhddtemp {\n format = 'HDD {format_hdd}'\n format_hdd = '\\?color=temperature {temperature}\u00b0C'\n}\n\n# show paths instead of names\nhddtemp {\n format_hdd = '{path} [\\?color=temperature {temperature}\u00b0{unit}]'\n}\n\n# show more colors\nhddtemp {\n gradients = True\n}\nauthor lasers
"},{"location":"user-guide/modules/#hueshift","title":"hueshift","text":"Shift color temperature on the screen.
Configuration parameters:
button_down mouse button to decrease color temperature (default 5)
button_toggle mouse button to toggle color temperature (default 1)
button_up mouse button to increase color temperature (default 4)
command specify blueshift, redshift, or sct to use, otherwise auto (default None)
delta specify interval value to change color temperature (default 100)
format display format for this module (default '{name} [\\?if=enabled&color=darkgray disabled' '|[\\?color=color_temperature {color_temperature}K]]')
maximum specify maximum color temperature to use (default 25000)
minimum specify minimum color temperature to use (default 1000)
thresholds specify color thresholds to use (default [(6499, '#f6c'), (6500, '#ff6'), (6501, '#6cf')])
Control placeholders:
{enabled} a boolean based on pgrep processing data, eg False, TrueFormat placeholders:
{color_temperature} color temperature, eg 6500
{name} name, eg Blueshift, Redshift, Sct
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
blueshift an extensible and highly configurable alternative to redshift
redshift program to adjust the color temperature of your screen
sct set color temperature with about 40 lines of C or so
Suggestions:
campfire 4500 dust storm on mars: 2000 coffee free all nighter: 8000Notes: hueshift can be disabled due to enabled running processes. sct and blueshift shifts only on one monitor, ideal for laptops. redshift shifts more than one, ideal for multi-monitors setups.
Examples:
# different theme\nhueshift {\n format = '\\?color=color_temperature \u263c {color_temperature}K'\n}\n\n# for best results, add some limitations\nhueshift {\n minimum = 3000\n maximum = 10000\n}\nauthor lasers
"},{"location":"user-guide/modules/#i3block","title":"i3block","text":"Support i3blocks blocklets in py3status.
i3blocks, https://github.com/vivien/i3blocks, is a project to allow simple scripts to provide output to the i3bar. This module allows these blocklets to run under py3status. The configuration of the blocklets is similar to how they are configured in i3blocks.
Configuration parameters:
cache_timeout How often the blocklet should be called (in seconds). This is similar to cache_timeout used by standard modules. However it can also take the following values; once the blocklet will be called once, repeat the blocklet will be called constantly, or persist where the command will be expected to keep providing new data. If this is not set or is None then the blocklet will not be called unless clicked on. To simplify i3block compatibility, this configuration parameter can also be provided as interval. (default None)
command Path to blocklet or command (default None)
format What to display on the bar (default '{output}')
instance Will be provided to the blocklet as $BLOCK_INSTANCE (default '')
label Will be prepended to the blocklets output (default '')
name Name of the blocklet - passed as $BLOCK_NAME (default '')
Format placeholders:
{output} The output of the blockletNotes: i3blocks and i3blocklets are subject to their respective licenses.
This support is experimental and done for convenience to users so they\ncan benefit from both worlds, issues or PRs regarding i3blocks related\nblocklets should not be raised.\n\nSome blocklets may return pango markup eg `<span ...` if so set\n`markup = pango` in the config for that module.\n\n`format` configuration parameter is used as is standard in py3status, not\nas in i3blocks configuration. Currently blocklets must provide responses\nin the standard i3blocks manner of one line per value (not as json).\nExamples:
# i3blocks config\n[time]\ncommand=date '+%D %T'\ninterval=5\n\n[wifi]\ninstance=wls1\nlabel='wifi:'\ncommand=~/i3blocks/wifi.sh\ninterval=5\n\n# py3status config\norder += 'i3block time'\ni3block time {\n command = \"date '+%D %T'\"\n interval = 5\n}\n\n# different py3status config\norder += 'i3block wifi'\ni3block wifi {\n instance = wls1\n label = 'wifi:'\n command = '~/i3blocks/wifi.sh'\n interval = 5\n}\nauthor tobes
"},{"location":"user-guide/modules/#i3pystatus","title":"i3pystatus","text":"Support i3pystatus modules in py3status.
i3pystatus, https://github.com/enkore/i3pystatus, is an alternative to py3status and provides a variety of modules. This py3status module allows these modules to run and be display inside py3status.
Configuration parameters:
module specify i3pystatus module to use (default None)Requires:
i3pystatus i3status replacement written in pythonExamples:
# the modules parameters are provided as such\ni3pystatus clock {\n module = 'clock'\n format = [('%a %b %-d %b %X', 'America/New_York'), ('%X', 'Etc/GMT+9')]\n}\n\n# if backend(s) are provided they should be given as a dict with the key being\n# the backend name and the value being a dict of the backend settings\ni3pystatus weather {\n module = 'weather'\n format = '{condition} {current_temp}{temp_unit}[ {icon}]'\n format += '[ Hi: {high_temp}][ Lo: {low_temp}][ {update_error}]'\n backend = {\n 'weathercom.Weathercom': {\n 'location_code': '94107:4:US',\n 'units': 'imperial',\n }\n }\n}\n\n# backends that have no configuration should be defined as shown here\ni3pystatus updates{\n module = 'updates'\n backends = {'dnf.Dnf': {}}\n}\nauthor tobes
"},{"location":"user-guide/modules/#icinga2","title":"icinga2","text":"Display service status for Icinga2.
Configuration parameters:
base_url the base url to the icinga-web2 services list (default '')
ca (default True)
cache_timeout how often the data should be updated (default 60)
disable_acknowledge enable or disable counting of acknowledged service problems (default False)
format define a format string like \"CRITICAL: %d\" (default '{status_name}: {count}')
password password to authenticate against the icinga-web2 interface (default '')
status set the status you want to obtain (0=OK,1=WARNING,2=CRITICAL,3=UNKNOWN) (default 0)
url_parameters (default '?service_state={service_state}&format=json')
user username to authenticate against the icinga-web2 interface (default '')
Format placeholders:
{status_name} status name, eg OK, WARNING, CRITICAL
{count} count, eg 0, 1, 2
author Ben Oswald <ben.oswald@root-space.de>
license BSD License <https://opensource.org/licenses/BSD-2-Clause>
source https://github.com/nazco/i3status-modules
"},{"location":"user-guide/modules/#imap","title":"imap","text":"Display number of unread messages from IMAP account.
Configuration parameters:
allow_urgent display urgency on unread messages (default False)
auth_scope scope to use with OAuth2 (default 'https://mail.google.com/')
auth_token path to where the pickled access/refresh token will be saved after successful credential authorization. (default '~/.config/py3status/imap_auth_token.pickle')
cache_timeout refresh interval for this module (default 60)
client_secret the path to the client secret file with OAuth 2.0 credentials (if None then OAuth not used) (default None)
criterion status of emails to check for (default 'UNSEEN')
debug log warnings (default False)
degraded_when_stale color as degraded when updating failed (default True)
format display format for this module (default 'Mail: {unseen}')
hide_if_zero hide this module when no new mail (default False)
mailbox name of the mailbox to check (default 'INBOX')
password login password (default None)
port number to use (default '993')
read_timeout timeout for read(2) syscalls (default 5)
security login authentication method: 'ssl' or 'starttls' (startssl needs python 3.2 or later) (default 'ssl')
server server to connect (default None)
use_idle use IMAP4 IDLE instead of polling; requires compatible server; uses cache_timeout for IDLE's timeout; will auto detect when set to None (default None)
user login user (default None)
Format placeholders:
{unseen} number of unread emailsColor options:
color_new_mail use color when new mail arrives, default to color_goodOAuth: OAuth2 will be used for authentication instead of a password if the client_secret path is set.
To create a client_secret for your Google account, visit\nhttps://console.developers.google.com/ and create an \"OAuth client ID\" from\nthe credentials tab.\n\nThis client secret enables the app (in this case, the IMAP py3status module)\nto request access to a user's email. Therefore the client secret doesn't\nhave to be for the same Google account as the email account being accessed.\n\nWhen the IMAP module first tries to access your email account a browser\nwindow will open asking for authorization to access your email.\nAfter authorization is complete, an access/refresh token will be saved to\nthe path configured in auth_token.\n\nRequires: Using OAuth requires the google-auth and google-auth-oauthlib\nlibraries to be installed.\n\nNote: the same client secret file can be used as with the py3status Google\nCalendar module.\nauthor obb, girst
"},{"location":"user-guide/modules/#insync","title":"insync","text":"Display Insync status.
Thanks to Iain Tatch <iain.tatch@gmail.com> for the script that this is based on.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{status} {queued}')
status_offline show when Insync is offline (default 'OFFLINE')
status_paused show when Insync is paused (default 'PAUSED')
status_share show when Insync is sharing (default 'SHARE')
status_synced show when Insync has finished syncing (default 'SYNCED')
status_syncing show when Insync is syncing (default 'SYNCING')
Format placeholders:
{status} Insync status
{queued} Number of files queued
Color options:
color_bad Offline
color_degraded Default (e.g. Paused/Syncing)
color_good Synced
Requires:
insync an unofficial Google Drive client with support for various desktopsauthor Joshua Pratt <jp10010101010000@gmail.com>
license BSD
"},{"location":"user-guide/modules/#kdeconnector","title":"kdeconnector","text":"Display information about your smartphone with KDEConnector.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 30)
device the device name, you need this if you have more than one device connected to your PC (default None)
device_id alternatively to the device name you can set your device id here (default None)
format see placeholders below (default '{name}{notif_status} {bat_status} {charge}%')
format_disconnected text if device is disconnected (default 'device disconnected')
low_threshold percentage value when text is twitch to color_bad (default 20)
status_bat text when battery is discharged (default '\u2b07')
status_chr text when device is charged (default '\u2b06')
status_full text when battery is full (default '\u263b')
status_no_notif text when you have no notifications (default '')
status_notif text when notifications are available (default ' \u2709')
Format placeholders:
{bat_status} battery state
{charge} the battery charge
{name} name of the device
{notif_size} number of notifications
{notif_status} shows if a notification is available or not
{net_type} shows cell network type
{net_strength} shows cell network strength
Color options:
color_bad Device unknown, unavailable or battery below low_threshold and not charging
color_degraded Connected and battery not charging
color_good Connected and battery charging
Requires:
kdeconnect adds communication between kde and your smartphone
dbus-python Python bindings for dbus PyGObject: Python bindings for GObject Introspectiom
Examples:
kdeconnector {\n device_id = \"aa0844d33ac6ca03\"\n format = \"{name} {charge} {bat_status}\"\n low_battery = \"10\"\n}\nauthor Moritz L\u00fcdecke, valdur55
"},{"location":"user-guide/modules/#keyboard_layout","title":"keyboard_layout","text":"Display keyboard layout.
Configuration parameters:
button_next mouse button to cycle next layout (default 4)
button_prev mouse button to cycle previous layout (default 5)
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{layout}')
layouts specify a list of layouts to use (default None)
Format placeholders:
{layout} keyboard layoutColor options:
color_<layout> colorize the layout. eg color_fr = '#729FCF'Requires:
xkblayout-state or
setxkbmap and xset (works for the first two predefined layouts. overrides XkbLayout when switching layout.)
Examples:
# define keyboard layouts that can be switched between\nkeyboard_layout {\n layouts = ['gb', 'fr', 'dvorak']\n}\nauthor shadowprince, tuxitop
license Eclipse Public License
"},{"location":"user-guide/modules/#keyboard_locks","title":"keyboard_locks","text":"Display NumLock, CapsLock, and ScrLock keys.
Configuration parameters:
cache_timeout refresh interval for this module (default 1)
format display format for this module (default '[\\?if=num_lock&color=good NUM|\\?color=bad NUM] ' '[\\?if=caps_lock&color=good CAPS|\\?color=bad CAPS] ' '[\\?if=scroll_lock&color=good SCR|\\?color=bad SCR]')
Control placeholders:
{num_lock} a boolean based on xset data
{caps_lock} a boolean based on xset data
{scroll_lock} a boolean based on xset data
Color options:
color_good Lock on
color_bad Lock off
Examples:
# hide NUM, CAPS, SCR\nkeyboard_locks {\n format = '\\?color=good [\\?if=num_lock NUM][\\?soft ]'\n format += '[\\?if=caps_lock CAPS][\\?soft ][\\?if=scroll_lock SCR]'\n}\nauthor lasers
"},{"location":"user-guide/modules/#khal_calendar","title":"khal_calendar","text":"Displays upcoming khal events.
Configuration parameters:
cache_timeout refresh interval for this module (default 60)
config_path Path to khal configuration file. The default None resolves to /home/$USER/.config/khal/config (default None)
date_end Until which datetime the module searches for events (default 'eod')
format display format for this module (default '{appointments}')
max_results an upper bound for the number of returned calendar entries (default None)
output_format khal conform format for displaying event output (default '{start-time} {title}')
Format placeholders:
{appointments} list of events in time rangeRequires:
khal https://github.com/pimutils/khalauthor @xenrox
license BSD
"},{"location":"user-guide/modules/#lm_sensors","title":"lm_sensors","text":"Display temperatures, voltages, fans, and more from hardware sensors.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
chips specify a list of chips to use (default [])
format display format for this module (default '{format_chip}')
format_chip display format for chips (default '{name} {format_sensor}')
format_chip_separator show separator if more than one (default ' ')
format_sensor display format for sensors (default '[\\?color=darkgray {name}] [\\?color=auto.input&show {input}]')
format_sensor_separator show separator if more than one (default ' ')
sensors specify a list of sensors to use (default [])
thresholds specify color thresholds to use (default {'auto.input': True})
Format placeholders:
{format_chip} format for chipsFormat_chip placeholders:
{name} chip name, eg coretemp-isa-0000, nouveau-pci-0500
{adapter} adapter type, eg ISA adapter, PCI adapter
{format_sensor} format for sensors
Format_sensor placeholders:
{name} sensor name, eg core_0, gpu_core, temp1, fan1
See sensors -u for a full list of placeholders for format_chip, format_sensors without the prefixes, chips and sensors options.
See https://www.kernel.org/doc/Documentation/hwmon/sysfs-interface for more information on the sensor placeholders.
Color options for auto.input threshold:
color_zero zero value or less (color red)
color_min minimum value (color lightgreen)
color_excl_input input value excluded from threshold (color None)
color_input input value (color lime)
color_near_max input value near maximum value (color yellow)
color_max maximum value (color orange)
color_near_crit input value near critical value (color lightcoral)
color_crit critical value (color red)
Color thresholds:
format_sensor xxx: print a color based on the value of xxx placeholder auto.input: print a color based on the value of input placeholder against a customized thresholdRequires:
lm_sensors a tool to read temperature/voltage/fan sensors
sensors-detect see man sensors-detect # --auto to read about using defaults or to compile a list of kernel modules
Examples:
# identify possible chips, sensors, placeholders, etc\n [user@py3status ~] $ sensors -u\n ----------------------------- # \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n coretemp-isa-0000 # chip {name} # chip: coretemp*\n Adapter: ISA adapter # \u251c\u2500\u2500 {adapter} type\n ---- # \u2502------------------------------------\n Core 0: # \u251c\u2500\u2500 sensor {name} # sensor: core_0\n temp2_input: 48.000 # \u2502 \u251c\u2500\u2500 {input}\n temp2_max: 81.000 # \u2502 \u251c\u2500\u2500 {max}\n temp2_crit: 91.000 # \u2502 \u251c\u2500\u2500 {crit}\n temp2_crit_alarm: 0.000 # \u2502 \u2514\u2500\u2500 {crit_alarm}\n Core 1: # \u2514\u2500\u2500 sensor {name} # sensor: core_1\n temp3_input: 48.000 # \u251c\u2500\u2500 {input}\n temp3_max: 81.000 # \u251c\u2500\u2500 {max}\n temp3_crit: 91.000 # \u251c\u2500\u2500 {crit}\n temp3_crit_alarm: 0.000 # \u2514\u2500\u2500 {crit_alarm}\n # \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n k10temp-pci-00c3 # chip {name} # chip: k10temp*\n Adapter: PCI adapter # \u251c\u2500\u2500 {adapter} type\n ---- # \u2502------------------------------------\n temp1: # \u251c\u2500\u2500 sensor {name} # sensor: temp1\n temp1_input: 30.000 # \u2502 \u251c\u2500\u2500 {input}\n temp1_max: -71.000 # \u2502 \u251c\u2500\u2500 {max}\n temp1_min: -15.000 # \u2502 \u251c\u2500\u2500 {min}\n temp1_alarm: 1.000 # \u2502 \u251c\u2500\u2500 {alarm}\n temp1_offset: 0.000 # \u2502 \u251c\u2500\u2500 {offset}\n temp1_beep: 0.000 # \u2502 \u2514\u2500\u2500 {beep}\n intrusion0: # \u2514\u2500\u2500 sensor {name} # sensor: intrusion0\n intrusion0_alarm: 0.000 # \u2514\u2500\u2500 {alarm}\n\n Solid lines denotes chips. Dashed lines denotes sensors.\n Sensor names are lowercased and its spaces replaced with underscores.\n The numbered prefixes, eg `temp1_*` are removed to keep names clean.\n\n# specify chips to use\nlm_sensors {\n chips = ['coretemp-isa-0000'] # full\n OR\n chips = ['coretemp-*'] # lm_sensors-compatible wildcard\n}\n\n# specify sensors to use\nlm_sensors {\n sensors = ['core_0', 'core_1', 'core_2', 'core_3'] # full\n OR\n sensors = ['core_*'] # fnmatch\n}\n\n# show name per chip, eg CPU 35\u00b0C 36\u00b0C 37\u00b0C 39\u00b0C GPU 52\u00b0C\nlm_sensors {\n format_chip = '[\\?if=name=coretemp-isa-0000 CPU ]'\n format_chip += '[\\?if=name=nouveau-pci-0500 GPU ]'\n format_chip += '{format_sensor}'\n format_sensor = '\\?color=auto.input {input}\u00b0C'\n sensors = ['core*', 'temp*']\n}\n\n# show name per sensor, eg CPU1 35\u00b0C CPU2 36\u00b0C CPU3 37\u00b0C CPU4 39\u00b0C GPU 52\u00b0C\nlm_sensors {\n format_chip = '{format_sensor}'\n format_sensor = '[\\?if=name=core_0 CPU1 ]'\n format_sensor += '[\\?if=name=core_1 CPU2 ]'\n format_sensor += '[\\?if=name=core_2 CPU3 ]'\n format_sensor += '[\\?if=name=core_3 CPU4 ]'\n format_sensor += '[\\?if=name=gpu_core GPU ]'\n format_sensor += '[\\?color=auto.input {input}\u00b0C]'\n sensors = ['core*', 'temp*']\n}\nauthor lasers
"},{"location":"user-guide/modules/#loadavg","title":"loadavg","text":"Display average system load over a period of time.
In UNIX computing, the system load is a measure of the amount of computational work that a computer system performs. The load average represents the average system load over a period of time. It conventionally appears in the form of three numbers which represent the system load during the last one-, five-, and fifteen-minute periods.
Configuration parameters:
cache_timeout refresh interval for this module (default 5)
format display format for this module (default 'Loadavg [\\?color=1avg {1min}] ' '[\\?color=5avg {5min}] [\\?color=15avg {15min}]')
thresholds specify color thresholds to use (default [(0, '#9dd7fb'), (20, 'good'), (40, 'degraded'), (60, '#ffa500'), (80, 'bad')])
Format placeholders:
{1min} load average during the last 1-minute, eg 1.44
{5min} load average during the last 5-minutes, eg 1.66
{15min} load average during the last 15-minutes, eg 1.52
{1avg} load average percentage during the last 1-minute, eg 12.00
{5avg} load average percentage during the last 5-minutes, eg 13.83
{15avg} load average percentage during the last 15-minutes, eg 12.67
Color thresholds:
xxx print a color based on the value of xxx placeholderNotes: http://blog.scoutapp.com/articles/2009/07/31/understanding-load-averages http://www.brendangregg.com/blog/2017-08-08/linux-load-averages.html
Examples:
# show load averages with static colors\nloadavg {\n format = 'Loadavg [\\?color=orange {1min} ][\\?color=gold {5min} {15min}]'\n}\n\n# remove prefix - easy copy and paste\nloadavg {\n format = '[\\?color=1avg {1min}] '\n format += '[\\?color=5avg {5min}] '\n format += '[\\?color=15avg {15min}]'\n}\n\n# show detailed load averages + percentages\nloadavg {\n format = 'Loadavg [\\?color=darkgray '\n format += '1min [\\?color=1avg {1min}]\\|[\\?color=1avg {1avg}%] '\n format += '5min [\\?color=5avg {5min}]\\|[\\?color=5avg {5avg}%] '\n format += '15min [\\?color=15avg {15min}]\\|[\\?color=15avg {15avg}%]]'\n}\n\n# show load averages with different colors + thresholds\nloadavg {\n # htop - default\n (0, '#9dd7fb'), # 1avg\n (0, 'cyan'), # 5avg\n (0, 'darkcyan'), $ 15avg\n\n # htop - monochrome\n (0, '#9dd7fb'), # 1avg\n (0, None), # 5avg\n (0, None), # 15avg\n\n # htop - black night\n (0, 'greenyellow'), # 1avg\n (0, 'limegreen'), # 5avg\n (0, 'limegreen'), # 15avg\n\n # htop - mc\n (0, '#ffffff'), # 1avg\n (0, '#aaaaaa'), # 5avg\n (0, '#555555'), # 15avg\n\n # three shades of blue\n (0, '#87cefa'), # 1avg\n (0, '#4bb6f8'), # 5avg\n (0, '#0991e5'), # 15avg\n\n # three shades of gray\n (0, '#dddddd'), # 1avg\n (0, '#bbbbbb'), # 5avg\n (0, '#999999'), # 15avg\n\n # htop - mc and three shades of gray is similar. htop - mc\n # have higher contrast between time periods over three shades\n # of gray for better readability. your mileage may vary.\n\n thresholds = {\n '1avg': [\n (0, 'REPLACE_ME'),\n (20, 'good'), (40, 'degraded'),\n (60, '#ffa500'), (80, 'bad')\n ],\n '5avg': [\n (0, 'REPLACE_ME'),\n (20, 'good'), (40, 'degraded'),\n (60, '#ffa500'), (80, 'bad')\n ],\n '15avg': [\n (0, 'REPLACE_ME'),\n (20, 'good'), (40, 'degraded'),\n (60, '#ffa500'), (80, 'bad')\n ],\n }\n}\n\n# don't show load averages if 1avg is under 60%\nloadavg {\n format = '[\\?if=1avg>59 Loadavg [\\?color=1avg {1min}] '\n format += '[\\?color=5avg {5min}] [\\?color=15avg {15min}]]'\n}\n\n# add your snippets here\nloadavg {\n format = \"...\"\n}\nauthor lasers
"},{"location":"user-guide/modules/#mail","title":"mail","text":"Display number of messages in various mailbox formats. This module supports Maildir, mbox, MH, Babyl, MMDF, and IMAP.
Configuration parameters:
accounts specify a dict consisting of mailbox types and a list of dicts consisting of mailbox settings and/or paths to use (default {})
cache_timeout refresh interval for this module (default 60)
format display format for this module (default '\\?not_zero Mail {mail}|No Mail')
thresholds specify color thresholds to use (default [])
Format placeholders:
{mail} number of messages
{maildir} number of Maildir messages
{mbox} number of mbox messages
{mh} number of MH messages
{babyl} number of Babyl messages
{mmdf} number of MMDF messages
{imap} number of IMAP messages
We can divide mailbox, eg {maildir}, into numbered placeholders based on number of mailbox accounts, eg {maildir_1}, and if we add name to a mailbox account, we can use {name} placeholder instead, eg {home}.
Color thresholds:
xxx print a color based on the value of xxx placeholderIMAP Subscriptions: You can specify a list of filters to decide which folders to search. By default, we search only the INBOX folder (ie: ['^INBOX$']). We can use regular expressions, so if you use more than one, it would be joined by a logical operator or.
`'.*'` will match all folders.\n`'pattern'` will match folders containing `pattern`.\n`'^pattern'` will match folders beginning with `pattern`.\n`'pattern$'` will match folders ending with `pattern`.\n`'^((?![Ss][Pp][Aa][Mm]).)*$'` will match all folders\nexcept for every possible case of `spam` folders.\n\nFor more documentation, see https://docs.python.org/3/library/re.html\nand/or any regex builder on the web. Don't forget to escape characters.\nExamples:
# add multiple accounts\nmail { #\n accounts = { # {mail}\n 'maildir': [ # \u251c\u2500\u2500 {maildir}\n {'path': '~/.mutt'}, # \u2502 \u251c\u2500\u2500 {maildir_1}\n {'path': '~/Mail'}, # \u2502 \u2514\u2500\u2500 {maildir_2}\n ], # \u2502\n 'mbox': [ # \u251c\u2500\u2500 {mbox}\n {'path': '~/home.mbox'}, # \u2502 \u251c\u2500\u2500 {mbox_1}\n { # \u2502 \u251c\u2500\u2500 {mbox_2}\n 'name': 'local', # <----\u2502----\u2502----\u2514\u2500\u2500 {local}\n 'path': '~/mbox' # \u2502 \u2502\n }, # \u2502 \u2502\n { # \u2502 \u2514\u2500\u2500 {mbox_3}\n 'name': 'debian', # <----\u2502---------\u2514\u2500\u2500 {debian}\n 'path': '/var/mail/$USER' # \u2502\n 'urgent': False, # <----\u2502---- disable urgent\n }, # \u2502\n ], # \u2502\n 'mh': [ # \u251c\u2500\u2500 {mh}\n {'path': '~/mh_mail'}, # \u2502 \u2514\u2500\u2500 {mh_1}\n ], # \u2502\n 'babyl': [ # \u251c\u2500\u2500 {babyl}\n {'path': '~/babyl_mail'}, # \u2502 \u2514\u2500\u2500 {babyl_1}\n ], # \u2502\n 'mmdf': [ # \u251c\u2500\u2500 {mmdf}\n {'path': '~/mmdf_mail'}, # \u2502 \u2514\u2500\u2500 {mmdf_1}\n ] # \u2502\n 'imap': [ # \u251c\u2500\u2500 {imap}\n { # \u2502 \u251c\u2500\u2500 {imap_1}\n 'name': 'home', # <----\u2502----\u2502----\u2514\u2500\u2500 {home}\n 'user': 'lasers', # \u2502 \u2502\n 'password': 'kiss_my_butt!', # \u2502 \u2502\n 'server': 'imap.gmail.com', # \u2502 \u2502\n # <---\u2502----\u2502 no filters to\n 'port': 993, # \u2502 \u2502 search folders, use\n # \u2502 \u2502 filters ['^INBOX$']\n }, # \u2502 \u2502\n { # \u2502 \u2514\u2500\u2500 {imap_2}\n 'name': 'work', # <----\u2502---------\u2514\u2500\u2500 {work}\n 'user': 'tobes', # \u2502\n 'password': 'i_love_python', #\n 'server': 'imap.yahoo.com', #\n # <---- no port, use port 993\n 'urgent': False, # <---- disable urgent\n # for this account\n 'filters': ['^INBOX$'] # <---- specify a list of filters\n # to search folders\n 'log': True, # <---- print a list of folders\n } # to filter in the log\n ]\n }\n allow_urgent = False <---- disable urgent for all accounts\n}\n\n# add colors, disable urgent\nmail {\n format = '[\\?color=mail&show Mail] {mail}'\n thresholds = [(1, 'good'), (5, 'degraded'), (15, 'bad')]\n allow_urgent = False\n}\n\n# identify the mailboxes, remove what you don't need\nmail {\n format = '[\\?color=mail '\n format += '[\\?if=imap&color=#00ff00 IMAP ]'\n format += '[\\?if=maildir&color=#ffff00 MAILDIR ]'\n format += '[\\?if=mbox&color=#ff0000 MBOX ]'\n format += '[\\?if=babyl&color=#ffa500 BABYL ]'\n format += '[\\?if=mmdf&color=#00bfff MMDF ]'\n format += '[\\?if=mh&color=#ee82ee MH ]'\n format += ']'\n format += '[\\?not_zero&color Mail {mail}|No Mail]'\n}\n\n# individual colorized mailboxes, remove what you don't need\nmail {\n format = '[\\?if=imap&color=#00ff00 IMAP] {imap} '\n format += '[\\?if=maildir&color=#ffff00 MAILDIR] {maildir} '\n format += '[\\?if=mbox&color=#ff0000 MBOX] {mbox} '\n format += '[\\?if=babyl&color=#ffa500 BABYL] {babyl} '\n format += '[\\?if=mmdf&color=#00bfff MMDF] {mmdf} '\n format += '[\\?if=mh&color=#ee82ee MH] {mh}'\n allow_urgent = False\n}\nauthor lasers
"},{"location":"user-guide/modules/#mega_sync","title":"mega_sync","text":"Display status of MEGAcmd.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for the module (default \"MEGA {format_sync}|No MEGA\")
format_sync display format for every sync (default \"{syncstate}\")
format_sync_separator show separator if more than one sync (default \" \")
Format placeholders:
{format_sync} Format for every sync returned by 'mega-sync' command.format_sync placeholders: Any column returned by 'mega-sync' command - in lower case! For example: id, syncstate, localpath
Requires: MEGAcmd: command-line interface for MEGA
author Maxim Baz (https://github.com/maximbaz)
license BSD
"},{"location":"user-guide/modules/#moc","title":"moc","text":"Display song currently playing in moc.
MOC (music on console) is a console audio player for Linux/Unix designed to be powerful and easy to use. It consists of two parts, a server (moc) and a player/interface (mocp). It supports OGG, WAV, MP3 and other formats.
Configuration parameters:
button_next mouse button to skip next track (default None)
button_pause mouse button to pause/play the playback (default 1)
button_previous mouse button to skip previous track (default None)
button_stop mouse button to stop the playback (default 3)
cache_timeout refresh interval for this module (default 5)
format display format for this module (default '\\?if=is_started [\\?if=is_stopped [] moc|' '[\\?if=is_paused ||][\\?if=is_playing >] {title}]')
replacements specify a list/dict of string placeholders to modify (default None)
sleep_timeout when moc is not running, this interval will be used to allow one to refresh constantly with time placeholders and/or to refresh once every minute rather than every few seconds (default 20)
Control placeholders:
{is_paused} a boolean based on moc status
{is_playing} a boolean based on moc status
{is_started} a boolean based on moc status
{is_stopped} a boolean based on moc status
Format placeholders:
{album} album name, eg (new output here)
{artist} artist name, eg (new output here)
{avgbitrate} audio average bitrate, eg 230kbps
{bitrate} audio bitrate, eg 230kbps
{currentsec} elapsed time in seconds, eg 32
{currenttime} elapsed time in [HH:]MM:SS, eg 00:32
{file} file location, eg /home/user/Music...
{rate} audio rate, eg 44kHz
{songtitle} song title, eg (new output here)
{state} playback state, eg PLAY, PAUSE, STOP
{timeleft} time left in [HH:]MM:SS, eg 71:30
{title} track title, eg (new output here)
{totalsec} total time in seconds, eg 4322
{totaltime} total time in seconds, eg 72:02
Placeholders are retrieved directly from mocp --info command. The list was harvested once and should not represent a full list.
Color options:
color_paused Paused, defaults to color_degraded
color_playing Playing, defaults to color_good
color_stopped Stopped, defaults to color_bad
Requires:
moc a console audio player with simple ncurses interfaceExamples:
# see 'man mocp' for more buttons\nmoc {\n on_click 9 = 'exec mocp --example'\n}\nauthor lasers
"},{"location":"user-guide/modules/#mpd_status","title":"mpd_status","text":"Display song currently playing in mpd.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 2)
format template string (see below) (default '{state} [[[{artist} ]- {title}]|[{file}]]')
hide_on_error hide the status if an error has occurred (default False)
hide_when_paused hide the status if state is paused (default False)
hide_when_stopped hide the status if state is stopped (default True)
host mpd host (default 'localhost')
idle_subsystems a list of subsystems to idle on. player: changes in song information, play state mixer: changes in volume options: e.g. repeat mode See the MPD protocol documentation for additional events. (default ['player', 'playlist', 'mixer', 'options'])
idle_timeout force idle to reset every n seconds (default 3600)
max_width maximum status length (default 120)
password mpd password (default None)
port mpd port (default '6600')
state_pause label to display for \"paused\" state (default '[pause]')
state_play label to display for \"playing\" state (default '[play]')
state_stop label to display for \"stopped\" state (default '[stop]')
use_idle whether to use idling instead of polling. None to autodetect (default None)
Format placeholders:
{state} state (paused, playing. stopped) can be defined via state_.. configuration parameters Refer to the mpc(1) manual page for the list of available placeholders to be used in the format. Placeholders should use braces {} rather than percent %% eg {artist}. Every placeholder can also be prefixed with next_ to retrieve the data for the song following the one currently playing.Color options:
color_pause Paused, default color_degraded
color_play Playing, default color_good
color_stop Stopped, default color_bad
Requires:
python-mpd2 (NOT python2-mpd2)Examples:
# Show state and (artist -) title, if no title fallback to file:\n{state} [[[{artist} - ]{title}]|[{file}]]\n\n# Show state, [duration], title (or file) and next song title (or file):\n{state} \\[{time}\\] [{title}|{file}] \u2192 [{next_title}|{next_file}]\nauthor shadowprince, zopieux
license Eclipse Public License
"},{"location":"user-guide/modules/#mpris","title":"mpris","text":"Display song/video and control MPRIS compatible players.
There are two ways to control the media player. Either by clicking with a mouse button in the text information or by using buttons. For former you have to define the button parameters in your config.
Configuration parameters:
button_next mouse button to play the next entry (default None)
button_next_player mouse button to switch next player in list (Same status as top player) (default None)
button_prev_player mouse button to switch previous player in list (Same status as top player) (default None)
button_previous mouse button to play the previous entry (default None)
button_stop mouse button to stop the player (default None)
button_switch_to_top_player mouse button to switch to top player (default None)
button_toggle mouse button to toggle between play and pause mode (default 1)
cache_timeout time (s) between Position update (default 0.5)
format display format for this module (default '[{artist} - ][{title}] {previous} {toggle} {next}')
format_none define output if no player is running (default 'no player running')
icon_next specify icon for next button (default u'\u25b9')
icon_pause specify icon for pause button (default u'\u25eb')
icon_play specify icon for play button (default u'\u25b7')
icon_previous specify icon for previous button (default u'\u25c3')
icon_stop specify icon for stop button (default u'\u25a1')
max_width maximum status length (default None)
player_priority priority of the players. Keep in mind that the state has a higher priority than player_priority. So when player_priority is \"[mpd, bomi]\" and mpd is paused and bomi is playing than bomi wins. (default [])
state_pause specify icon for pause state (default u'\u25eb')
state_play specify icon for play state (default u'\u25b7')
state_stop specify icon for stop state (default u'\u25a1')
Format placeholders:
{album} album name
{artist} artiste name (first one)
{length} time duration of the song
{player} show name of the player
{player_shortname} show name of the player from busname (usually command line name)
{state} playback status of the player
{time} played time of the song
{title} name of the song
{nowplaying} now playing field provided by VLC for stream info
Button placeholders:
{next} play the next title
{pause} pause the player
{play} play the player
{previous} play the previous title
{stop} stop the player
{toggle} toggle between play and pause
Color options:
color_control_inactive button is not clickable
color_control_active button is clickable
color_paused song is paused, defaults to color_degraded
color_playing song is playing, defaults to color_good
color_stopped song is stopped, defaults to color_bad
Requires:
mpris2 Python usable definiton of MPRIS2
dbus-python Python bindings for dbus PyGObject: Python bindings for GObject Introspection
Tested players:
bomi powerful and easy-to-use gui multimedia player based on mpv
cantata qt5 client for the music player daemon (mpd)
mpdris2 mpris2 support for mpd
vlc multi-platform mpeg, vcd/dvd, and divx player
Examples:
mpris {\n format = \"{previous}{play}{next} {player}: {state} [[{artist} - {title}]|[{title}]]\"\n format_none = \"no player\"\n player_priority = \"[mpd, cantata, vlc, bomi, *]\"\n}\n\nonly show information from mpd and vlc, but mpd has a higher priority:\nmpris {\n player_priority = \"[mpd, vlc]\"\n}\n\nshow information of all players, but mpd and vlc have the highest priority:\nmpris {\n player_priority = \"[mpd, vlc, *]\"\n}\n\nvlc has the lowest priority:\nmpris {\n player_priority = \"[*, vlc]\"\n}\nauthor Moritz L\u00fcdecke, tobes, valdur55
"},{"location":"user-guide/modules/#net_iplist","title":"net_iplist","text":"Display list of network interfaces and IP addresses.
This module supports both IPv4 and IPv6. There is the possibility to blacklist interfaces and IPs, as well as to show interfaces with no IP address. It will show an alternate text if no IP are available.
Configuration parameters:
cache_timeout refresh interval for this module in seconds. (default 30)
format format of the output. (default 'Network: {format_iface}')
format_iface format string for the list of IPs of each interface. (default '{iface}:[ {ip4}][ {ip6}]')
format_no_ip string to show if there are no IPs to display. (default 'no connection')
iface_blacklist list of interfaces to ignore. Accepts shell-style wildcards. (default ['lo'])
iface_sep string to write between interfaces. (default ' ')
ip_blacklist list of IPs to ignore. Accepts shell-style wildcards. (default [])
ip_sep string to write between IP addresses. (default ',')
remove_empty do not show interfaces with no IP. (default True)
Format placeholders:
{format_iface} the format_iface string.Format placeholders for format_iface:
{iface} name of the interface.
{ip4} list of IPv4 of the interface.
{ip6} list of IPv6 of the interface.
Color options:
color_bad no IPs to show
color_good IPs to show
Requires:
ip utility found in iproute2 packageExamples:
net_iplist {\n iface_blacklist = []\n ip_blacklist = ['127.*', '::1']\n}\nauthor guiniol
"},{"location":"user-guide/modules/#net_rate","title":"net_rate","text":"Display network transfer rate.
Configuration parameters:
all_interfaces ignore self.interfaces, but not self.interfaces_blacklist (default True)
cache_timeout how often we refresh this module in seconds (default 2)
devfile location of dev file under /proc (default '/proc/net/dev')
format format of the module output (default '{interface}: {total}')
format_no_connection when there is no data transmitted from the start of the plugin (default '')
format_value format to use for values (default \"[\\?min_length=11 {value:.1f} {unit}]\")
hide_if_zero hide indicator if rate == 0 (default False)
interfaces comma separated list of interfaces to track (default [])
interfaces_blacklist comma separated list of interfaces to ignore (default 'lo')
si_units use SI units (default False)
sum_values sum values of each interface instead of taking the top one (default False)
thresholds specify color thresholds to use (default [(0, 'bad'), (1024, 'degraded'), (1024 * 1024, 'good')])
unit unit to use. If the unit contains a multiplier prefix, only this exact unit will ever be used (default \"B/s\")
Format placeholders:
{down} download rate
{interface} name of interface
{total} total rate
{up} upload rate
format_value placeholders:
{unit} current unit
{value} numeric value
Color thresholds:
{down} Change color based on the value of down
{total} Change color based on the value of total
{up} Change color based on the value of up
author shadowprince
license Eclipse Public License
"},{"location":"user-guide/modules/#netdata","title":"netdata","text":"Display network speed and bandwidth usage.
Configuration parameters:
cache_timeout refresh interval for this module (default 2)
format display format for this module (default '{nic} [\\?color=down LAN(Kb): {down}\u2193 {up}\u2191] ' '[\\?color=total T(Mb): {download}\u2193 {upload}\u2191 {total}\u2195]')
nic specify a network interface to use (default None)
thresholds specify color thresholds to use (default {'down': [(0, 'bad'), (30, 'degraded'), (60, 'good')], 'total': [(0, 'good'), (400, 'degraded'), (700, 'bad')]})
Format placeholders:
{nic} network interface
{down} number of download speed
{up} number of upload speed
{download} number of download usage
{upload} number of upload usage
{total} number of total usage
Color thresholds:
xxx print a color based on the value of xxx placeholderauthor Shahin Azad <ishahinism at Gmail>
"},{"location":"user-guide/modules/#networkmanager","title":"networkmanager","text":"Display NetworkManager fields via nmcli, a command-line tool.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
devices specify a list of devices to use (default ['[e|w]'])*
format display format for this module (default '{format_device}')
format_device format for devices (default \"[\\?if=general_connection {general_device}[\\?soft ][\\?color=ap_signal {ap_ssid} {ap_bars} {ap_signal}%][\\?soft ][\\?color=good {ip4_address1}]]\")
format_device_separator show separator if more than one (default ' ')
thresholds specify color thresholds to use (default [(0, 'bad'), (30, 'degraded'), (65, 'good')])
Format placeholders:
{format_device} format for devicesFormat_device placeholders:
{general_connection} eg Py3status, Wired Connection 1
{general_device} eg wlp3s0b1, enp2s0
{general_type} eg wifi, ethernet
{ap_bars} signal strength in bars, eg \u2582\u2584\u2586_
{ap_chan} wifi channel, eg 6
{ap_mode} network mode, eg Adhoc or Infra
{ap_rate} bitrate, eg 54 Mbit/s
{ap_security} signal security, eg WPA2
{ap_signal} signal strength in percentage, eg 63
{ap_ssid} ssid name, eg Py3status
{ip4_address1} eg 192.168.1.108
{ip6_address1} eg 0000::0000:0000:0000:0000
Use nmcli --terse --fields=general,ap,ip4,ip6 device show for a full list of supported NetworkManager fields to use. Not all of NetworkManager fields will be usable. See man nmcli for more information.
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
nmcli cli configuration utility for NetworkManagerExamples:
# specify devices to use\nnetworkmanager {\n devices = ['e*'] # ethernet only\n devices = ['w*'] # wireless only\n devices = [] # ethernet, wireless, lo, etc\n}\nauthor Kevin Pulo <kev@pulo.com.au>
license BSD
"},{"location":"user-guide/modules/#ns_checker","title":"ns_checker","text":"Display DNS resolution success on a configured domain.
This module launch a simple query on each nameservers for the specified domain. Nameservers are dynamically retrieved. The FQDN is the only one mandatory parameter. It's also possible to add additional nameservers by appending them in nameservers list.
The default resolver can be overwritten with my_resolver.nameservers parameter.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 300)
domain domain name to check (default '')
format output format string (default '{total_count} NS {status}')
lifetime resolver lifetime (default 0.3)
nameservers specify a list of reference DNS nameservers (default [])
resolvers specify a list of DNS resolvers to use (default [])
Format placeholders:
{nok_count} The number of failed name servers
{ok_count} The number of working name servers
{status} The overall status of the name servers (OK or NOK)
{total_count} The total number of name servers
Color options:
color_bad One or more lookups have failed
color_good All lookups have succeeded
Requires:
dnspython a dns toolkit for pythonauthor nawadanp
"},{"location":"user-guide/modules/#nvidia_smi","title":"nvidia_smi","text":"Display NVIDIA properties currently exhibiting in the NVIDIA GPUs.
nvidia-smi, short for NVIDIA System Management Interface program, is a cross platform tool that supports all standard NVIDIA driver-supported Linux distros.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{format_gpu}')
format_gpu display format for NVIDIA GPUs (default '{gpu_name} [\\?color=temperature.gpu {temperature.gpu}\u00b0C] ' '[\\?color=memory.used_percent {memory.used_percent}%]')
format_gpu_separator show separator if more than one (default ' ')
memory_unit specify memory unit, eg 'KiB', 'MiB', 'GiB', otherwise auto (default None)
thresholds specify color thresholds to use (default [(0, 'good'), (65, 'degraded'), (75, 'orange'), (85, 'bad')])
Format placeholders:
{format_gpu} format for NVIDIA GPUsformat_gpu placeholders:
{index} Zero based index of the GPU.
{count} The number of NVIDIA GPUs in the system
{driver_version} The version of the installed NVIDIA display driver
{gpu_name} The official product name of the GPU
{gpu_uuid} Globally unique immutable identifier of the GPU
{memory.free} Total free memory
{memory.free_unit} Total free memory unit
{memory.total} Total installed GPU memory
{memory.total_unit} Total installed GPU memory unit
{memory.used} Total memory allocated by active contexts
{memory.used_percent} Total memory allocated by active contexts percentage
{memory.used_unit} Total memory unit
{temperature.gpu} Core GPU temperature in degrees C
Use python /path/to/nvidia_smi.py --list-properties for a full list of supported NVIDIA properties to use. Not all of supported NVIDIA properties will be usable. See nvidia-smi --help-query-gpu for more information.
Color thresholds:
format_gpu xxx: print a color based on the value of NVIDIA xxx propertyRequires:
nvidia-smi command line interface to query NVIDIA devicesExamples:
# display nvidia properties\nnvidia_smi {\n format_gpu = '{gpu_name} [\\?color=temperature.gpu {temperature.gpu}\u00b0C] '\n format_gpu += '[\\?color=memory.used_percent {memory.used} {memory.used_unit}'\n format_gpu += '[\\?color=darkgray&show \\|]{memory.used_percent:.1f}%]'\n}\nauthor lasers
"},{"location":"user-guide/modules/#online_status","title":"online_status","text":"Determine if you have an Internet Connection.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{icon}')
icon_off show when connection is offline (default '\u25a0')
icon_on show when connection is online (default '\u25cf')
timeout time to wait for a response, in seconds (default 2)
url specify URL to connect when checking for a connection (default 'https://www.google.com')
Format placeholders:
{icon} connection statusColor options:
color_off Connection offline, defaults to color_bad
color_on Connection online, defaults to color_good
author obb
"},{"location":"user-guide/modules/#pingdom","title":"pingdom","text":"Display response times of the configured Pingdom checks.
We also verify the status of the checks and colorize if needed. Pingdom API doc : https://www.pingdom.com/features/api/documentation/
Configuration parameters:
app_key create an APP KEY on pingdom first (default '')
cache_timeout how often to refresh the check from pingdom (default 600)
checks comma separated pindgom check names to display (default '')
format display format for this module (default '{pingdom}')
login pingdom login (default '')
max_latency maximal latency before coloring the output (default 500)
password pingdom password (default '')
request_timeout pindgom API request timeout (default 10)
Format placeholders:
{pingdom} pingdom response timesColor options:
color_bad Site is down
color_degraded Latency exceeded max_latency
Requires:
requests https://pypi.python.org/pypi/requestsauthor ultrabug
"},{"location":"user-guide/modules/#playerctl","title":"playerctl","text":"Display song/video and control players supported by playerctl
Playerctl is a command-line utility for controlling media players that implement the MPRIS D-Bus Interface Specification. With Playerctl you can bind player actions to keys and get metadata about the currently playing song or video.
Configuration parameters:
button_loop mouse button to cycle the loop status of the player (default None)
button_next mouse button to skip to the next track (default None)
button_pause mouse button to pause the playback (default None)
button_play mouse button to play the playback (default None)
button_play_pause mouse button to play/pause the playback (default 1)
button_previous mouse button to skip to the previous track (default None)
button_seek_backward mouse button to playback's position backward (default None)
button_seek_forward mouse button to playback's position forward (default None)
button_shuffle mouse button to toggle the shuffle mode of the player (default None)
button_stop mouse button to stop the playback (default 3)
button_volume_down mouse button to decrease the volume of the player (default None)
button_volume_up mouse button to increase the volume of the player (default None)
format display format for this module (default '{format_player}')
format_player display format for players (default '[\\?color=status [\\?if=status=Playing > ][\\?if=status=Paused || ]' '[\\?if=status=Stopped .. ][[{artist}][\\?soft - ][{title}|{player}]]]')
format_player_separator show separator if more than one player (default ' ')
players list of players to track. An empty list tracks all players (default [])
replacements specify a list/dict of string placeholders to modify (default None)
seek_delta time (in seconds) to change the playback's position by (default 5)
thresholds specify color thresholds to use for different placeholders (default {\"status\": [(\"Playing\", \"good\"), (\"Paused\", \"degraded\"), (\"Stopped\", \"bad\")]})
volume_delta percentage (from 0 to 100) to change the player's volume by (default 10)
Not all players support every button action
Format placeholders:
{format_player} format for playersFormat player placeholders:
{album} album name
{artist} artist name
{duration} length of track/video in [HH:]MM:SS, e.g. 03:22
{loop} loop status of the player, e.g. None, playlist, Track
{player} name of the player
{position} elapsed time in [HH:]MM:SS, e.g. 00:17
{shuffle} boolean indicating if the player's shuffle mode is on
{status} playback status, e.g. Playing, Paused, Stopped
{title} track/video title
{trackNumber} position of the track in the album or playlist
{volume} volume level of the player from 0 to 100
Not all media players support every placeholder
Requires:
playerctl mpris media player controller and lib for spotify, vlc, audacious, bmp, xmms2, and others.
python-gobject Python Bindings for GLib/GObject/GIO/GTK+
author jdholtz
"},{"location":"user-guide/modules/#pomodoro","title":"pomodoro","text":"Use Pomodoro technique to get things done easily.
Button 1 starts/pauses countdown. Button 2 switch Pomodoro/Break. Button 3 resets timer.
Configuration parameters:
display_bar display time in bars when True, otherwise in seconds (default False)
format define custom time format. See placeholders below (default '{ss}')
format_active format to display when timer is active (default 'Pomodoro [{format}]')
format_break format to display during break (default 'Break #{breakno} [{format}]')
format_break_stopped format to display during a break that is stopped (default 'Break #{breakno} ({format})')
format_separator separator between minutes:seconds (default ':')
format_stopped format to display when timer is stopped (default 'Pomodoro ({format})')
num_progress_bars number of progress bars (default 5)
pomodoros specify a number of pomodoros (intervals) (default 4)
sound_break_end break end sound (file path) (default None)
sound_pomodoro_end pomodoro end sound (file path) (default None)
sound_pomodoro_start pomodoro start sound (file path) (default None)
timer_break normal break time (seconds) (default 300)
timer_long_break long break time (seconds) (default 900)
timer_pomodoro pomodoro time (seconds) (default 1500)
Format placeholders:
{bar} display time in bars
{breakno} current break number
{ss} display time in total seconds (1500)
{mm} display time in total minutes (25)
{mmss} display time in (hh-)mm-ss (25:00)
Color options:
color_bad Pomodoro not running
color_degraded Pomodoro break
color_good Pomodoro active
Examples:
pomodoro {\n format = \"{mmss} {bar}\"\n}\nauthor Fandekasp (Adrien Lemaire), rixx, FedericoCeratto, schober-ch, ricci
"},{"location":"user-guide/modules/#process_status","title":"process_status","text":"Display status of a process on your system.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{icon}')
full match against the full command line (default False)
icon_off show this if a process is not running (default '\u25a0')
icon_on show this if a process is running (default '\u25cf')
process specify a process name to use (default None)
Format placeholders:
{icon} process icon
{process} process name
Color options:
color_bad Not running
color_good Running
author obb, Moritz L\u00fcdecke
"},{"location":"user-guide/modules/#prometheus","title":"prometheus","text":"Displays result of a Prometheus query.
Configuration parameters:
color Text colour. Supports py3status colour names. Examples: GOOD, DEGRADED, BAD, #E9967A (default None)
format Formatting of query result. Can refer to all labels from the query result. Query value placeholder __v. (default \"{__v:.0f}\")
join If query returned multiple rows, join them using this string. If you want to show just one, update your query. (default None)
query The PromQL query (default None)
query_interval Re-query interval in seconds. (default 60)
server str, URL pointing at your Prometheus(-compatible) server, example: http://prom.int.mydomain.net:9090 (default None)
units Dict with py3.format_units arguments, if you want human-readable unit formatting. Example: {\"unit\": \"Wh\", \"si\": True} If used, __v placeholder will contain formatted output. __n and __u will contain number and unit separately if you want to more finely control formatting. (default None)
Dynamic format placeholders: All query result labels are available as format placeholders. The vector values themselves are in placeholder __v. (Or __n and __u if you specified units).
Examples: # If blackbox exporter ran into any failures, show it. If everything # is healthy this will produce 0 rows hence not shown. query = \"probe_success == 0\" format = \"\ud83d\udc80 {job} {instance} \ud83d\udc80\" color = \"bad\"
# Basic Prometheus stat\nquery = \"sum(prometheus_sd_discovered_targets)\"\nformat = \"{__v:.0f} targets monitored\"\ncolor = \"ok\"\nauthor github.com/Wilm0r
"},{"location":"user-guide/modules/#rainbow","title":"rainbow","text":"Add color cycling fun to your i3bar.
This is the most pointless yet most exciting module you can imagine.
It allows color cycling of modules. Imagine the joy of having the current time change through the colors of the rainbow.
If you were completely insane you could also use it to implement the i3bar equivalent of the <blink> tag and cause yourself endless headaches and the desire to vomit.
The color for the contained module(s) is changed and cycles through your chosen gradient by default this is the colors of the rainbow. This module will increase the amount of updates that py3status needs to do so should be used sparingly.
Configuration parameters:
cycle_time How often we change this color in seconds (default 1)
force If True then the color will always be set. If false the color will only be changed if it has not been set by a module. (default False)
format display format for this module (default '{output}')
gradient The colors we will cycle through, This is a list of hex values (default [ '#FF0000', '#FFFF00', '#00FF00', '#00FFFF', '#0000FF', '#FF00FF', '#FF0000', ])
multi_color If True then each module the rainbow contains will be colored differently (default True)
steps Number of steps between each color in the gradient (default 10)
Format placeholders:
{output} rainbow outputExamples:
# show time colorfully\norder += \"rainbow time\"\nrainbow time {\n time {}\n}\n\n# blinking text black/white\norder += \"rainbow blink_time\"\nrainbow blink_time {\n gradient = [\n '#FFFFFF',\n '#000000',\n ]\n steps = 1\n time {}\n}\nauthor tobes
"},{"location":"user-guide/modules/#rate_counter","title":"rate_counter","text":"Display time spent and calculate the price of your service.
Configuration parameters:
cache_timeout how often to update in seconds (default 5)
config_file file path to store the time already spent and restore it the next session (default '~/.i3/py3status/counter-config.save')
format output format string (default 'Time: {days} day {hours}:{mins:02d} Cost: {total}')
format_money output format string (default '{price}$')
hour_price your price per hour (default 30)
tax tax value (1.02 = 2%) (default 1.02)
Format placeholders:
{days} The number of whole days in running timer
{hours} The remaining number of whole hours in running timer
{mins} The remaining number of whole minutes in running timer
{secs} The remaining number of seconds in running timer
{subtotal} The subtotal cost (time * rate)
{tax} The tax cost, based on the subtotal cost
{total} The total cost (subtotal + tax)
{total_hours} The total number of whole hours in running timer
{total_mins} The total number of whole minutes in running timer
format_money placeholders:
{price} numeric value of moneyColor options:
color_running Running, default color_good
color_stopped Stopped, default color_bad
author Amaury Brisou <py3status AT puzzledge.org>
"},{"location":"user-guide/modules/#rss_aggregator","title":"rss_aggregator","text":"Display unread feeds in your favorite RSS aggregator.
Configuration parameters:
aggregator feed aggregator used. Supported values are owncloud and ttrss. Other aggregators might be supported in future releases. Contributions are welcome. (default 'owncloud')
cache_timeout how often to run this check (default 60)
feed_ids list of IDs of feeds to watch, see note below (default [])
folder_ids list of IDs of folders ro watch (default [])
format format to display (default 'Feed: {unseen}')
password login password (default None)
server aggregator server to connect to (default 'https://yourcloudinstance.com')
user login user (default None)
Format placeholders:
{unseen} sum of numbers of unread feed elementsColor options:
color_new_items text color when there is new items (default color_good)
color_error text color when there is an error (default color_bad)
Requires:
requests python module from pypi https://pypi.python.org/pypi/requestsNotes: You can also decide to check only for specific feeds or folders of feeds. To use this feature, you have to first get the IDs of those feeds or folders. You can get those IDs by clicking on the desired feed or folder and watching the URL.
For OwnCloud/NextCloud with News application:\nhttps://yourcloudinstance.com/index.php/apps/news/#/items/feeds/FEED_ID\nhttps://yourcloudinstance.com/index.php/apps/news/#/items/folders/FOLDER_ID\n\nFor Tiny Tiny RSS 1.6 or newer:\nhttps://yourttrssinstance.com/index.php#f=FEED_ID&c=0\nhttps://yourttrssinstance.com/index.php#f=FOLDER_ID&c=1\n\nIf both feeds list and folders list are left empty, all unread feed items\nwill be counted. You may use both feeds list and folders list, but given\nfeeds shouldn't be included in given folders, else unread count number\nbehavior is unpredictable. Same warning when aggregator allows subfolders:\nthe folders list shouldn't include a folder and one of its subfolder.\nauthor raspbeguy
"},{"location":"user-guide/modules/#rt","title":"rt","text":"Display number of ongoing tickets from RT queues.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 300)
db database to use (default '')
format see placeholders below (default 'general: {General}')
host database host to connect to (default '')
password login password (default '')
threshold_critical set bad color above this threshold (default 20)
threshold_warning set degraded color above this threshold (default 10)
timeout timeout for database connection (default 5)
user login user (default '')
Format placeholders:
{YOUR_QUEUE_NAME} number of ongoing RT tickets (open+new+stalled)Color options:
color_bad Exceeded threshold_critical
color_degraded Exceeded threshold_warning
Requires: PyMySQL: https://pypi.org/project/PyMySQL/ or MySQL-python: https://pypi.org/project/MySQL-python/
It features thresholds to colorize the output and forces a low timeout to limit the impact of a server connectivity problem on your i3bar freshness.
author ultrabug
"},{"location":"user-guide/modules/#scratchpad","title":"scratchpad","text":"Display number of scratchpad windows and urgency hints.
Configuration parameters:
cache_timeout refresh interval for i3-msg or swaymsg (default 5)
format display format for this module (default \"\u232b [\\?color=scratchpad {scratchpad}]\")
thresholds specify color thresholds to use (default [(0, \"darkgray\"), (1, \"violet\")])
Format placeholders:
{scratchpad} number of scratchpads
{urgent} number of urgent scratchpads
Color thresholds:
xxx print a color based on the value of xxx placeholderOptional:
i3ipc an improved python library to control i3wm and swayExamples:
# hide zero scratchpad\nscratchpad {\n format = '[\\?not_zero \u232b [\\?color=scratchpad {scratchpad}]]'\n}\n\n# hide non-urgent scratchpad\nscratchpad {\n format = '[\\?not_zero \u232b {urgent}]'\n}\n\n# bring up scratchpads on clicks\nscratchpad {\n on_click 1 = 'scratchpad show'\n}\n\n# add more colors\nscratchpad {\n thresholds = [\n (0, \"darkgray\"), (1, \"violet\"), (2, \"deepskyblue\"), (3, \"lime\"),\n (4, \"yellow\"), (5, \"orange\"), (6, \"red\"), (7, \"tomato\"),\n ]\n}\nauthor shadowprince (counter), cornerman (async)
license Eclipse Public License (counter), BSD (async)
"},{"location":"user-guide/modules/#screenshot","title":"screenshot","text":"Take screenshots and upload them to a given server.
Configuration parameters:
file_length generated file_name length (default 4)
format display format for this module (default '\\?color=good [{basename}|\\?show SHOT]')
save_path Directory where to store your screenshots (default '~/Pictures')
screenshot_command the command used to generate the screenshot (default 'gnome-screenshot -f')
upload_path the remote path where to push the screenshot (default None)
upload_server your server address (default None)
upload_user your ssh user (default None)
Format placeholders:
{basename} generated basename, eg qs60.jpgExamples:
# push screenshots to a server\nscreenshot {\n save_path = \"~/Pictures/\"\n upload_user = \"erol\"\n upload_server = \"puzzledge.org\"\n upload_path = \"/files\"\n\n # scp $HOME/Pictures/$UUID.jpg erol@puzzledge.org:/files\n}\nauthor Amaury Brisou <py3status AT puzzledge.org>
"},{"location":"user-guide/modules/#scroll","title":"scroll","text":"Scroll modules.
Configuration parameters:
cache_timeout refresh interval for this module (default 1)
length specify a length of characters to scroll (default 25)
Format placeholders:
{output} outputauthor farnoy
"},{"location":"user-guide/modules/#selinux","title":"selinux","text":"Display SELinux state.
This module displays the state of SELinux on your machine: Enforcing (good), Permissive (degraded), or Disabled (bad).
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default 'SELinux: {state}')
state_disabled show when no SELinux policy is loaded. (default 'disabled')
state_enforcing show when SELinux security policy is enforced. (default 'enforcing')
state_permissive show when SELinux prints warnings instead of enforcing. (default 'permissive')
Format placeholders:
{state} SELinux stateColor options:
color_bad Enforcing
color_degraded Permissive
color_good Disabled
Requires:
libselinux-python SELinux python bindings for libselinuxauthor bstinsonmhk
license BSD
"},{"location":"user-guide/modules/#spaceapi","title":"spaceapi","text":"Display status of a given hackerspace.
Configuration parameters:
button_url mouse button to open URL sent in space's API (default 3)
cache_timeout refresh interval for this module (default 60)
format display format for this module (default '{state}[ {lastchanged}]')
format_lastchanged display format for time (default 'since %H:%M')
state_closed show when hackerspace is closed (default 'closed')
state_open show when hackerspace is open (default 'open')
url specify JSON URL of a hackerspace to retrieve from (default 'https://status.chaospott.de/status.json')
Format placeholders:
{state} Hackerspace state
{lastchanged} Time
format_lastchanged conversion: '%' Strftime characters to be translated
Color options:
color_closed Space closed, defaults to color_bad
color_open Space open, defaults to color_good
author timmszigat
license WTFPL <http://www.wtfpl.net/txt/copying/>
"},{"location":"user-guide/modules/#speedtest","title":"speedtest","text":"Perform a bandwidth test with speedtest-cli.
Use middle-click to start the speed test.
Configuration parameters:
button_share mouse button to share an URL (default None)
format display format for this module (default \"speedtest[\\?if=elapsed&color=elapsed_time \" \"{elapsed_time}s][ [\\?color=download \u2193{download}Mbps] \" \"[\\?color=upload \u2191{upload}Mbps]]\")
thresholds specify color thresholds to use (default {\"upload\": [(0, \"violet\")], \"ping\": [(0, \"#fff381\")], \"download\": [(0, \"cyan\")], \"elapsed_time\": [(0, \"#1cbfff\")]})
Control placeholders:
{elapsed} elapsed time state, eg False, TrueFormat placeholders:
{bytes_sent} bytes sent during test (in MB), eg 52.45
{bytes_received} bytes received during test (in MB), eg 70.23
{client_country} client country code, eg FR
{client_ip} client ip, eg 78.194.13.7
{client_isp} client isp, eg Free SAS
{client_ispdlavg} client isp download average, eg 0
{client_isprating} client isp rating, eg 3.7
{client_ispulavg} client isp upload average, eg 0
{client_lat} client latitude, eg 48.8534
{client_loggedin} client logged in, eg 0
{client_lon} client longitude, eg 2.3487999999999998
{client_rating} client rating, eg 0
{download} download speed (in MB), eg 20.23
{elapsed_time} elapsed time since speedtest start
{ping} ping time in ms to speedtest server
{server_cc} server country code, eg FR
{server_country} server country, eg France
{server_d} server distance, eg 2.316599376968091
{server_host} server host, eg speedtest.telecom-paristech.fr:8080
{server_id} server id, eg 11977
{share} share, eg share url
{timestamp} timestamp, eg 2018-08-30T16:27:25.318212Z
{server_lat} server latitude, eg 48.8742
{server_latency} server latency, eg 8.265
{server_lon} server longitude, eg 2.3470
{server_name} server name, eg Paris
{server_sponsor} server sponsor, eg T\u00e9l\u00e9com ParisTech
{server_url} server url, eg http://speedtest.telecom-paristech...
{upload} upload speed (in MB), eg 20.23
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
speedtest-cli Command line interface for testing Internet bandwidthExamples:
# show detailed elapsed_time|download/upload\nspeedtest {\n format = \"speedtest[\\?soft ][\\?if=elapsed [\\?color=darkgray [time \"\n format += \"[\\?color=elapsed_time {elapsed_time} s]]]|[\\?color=darkgray \"\n # format += \"ping [\\?color=ping {ping} ms] \"\n format += \"download [\\?color=download {download}Mbps] \"\n format += \"upload [\\?color=upload {upload}Mbps]]]\"\n}\n\n# show everything\nspeedtest {\n format = \"speedtest[\\?soft ][\\?color=darkgray \"\n format += \"[time [\\?color=elapsed_time {elapsed_time} s]][\\?soft ]\"\n format += \"[ping [\\?color=ping {ping} ms] \"\n format += \"download [\\?color=download {download}Mbps] \"\n format += \"upload [\\?color=upload {upload}Mbps]]]\"\n}\n\n# minimal\nspeedtest {\n format = \"speedtest[\\?soft ][\\?if=elapsed \"\n format += \"[\\?color=elapsed_time {elapsed_time}]|\"\n # format += \"[\\?color=ping {ping}] \"\n format += \"[[\\?color=download {download}] [\\?color=upload {upload}]]]\"\n}\n\n# don't hide data on reset\nspeedtest {\n format = \"speedtest[\\?soft ][\\?color=darkgray time \"\n format += \"[\\?color=elapsed_time {elapsed_time} s] \"\n # format += \"ping [\\?color=ping {ping} ms] \"\n format += \"download [\\?color=download {download}Mbps] \"\n format += \"upload [\\?color=upload {upload}Mbps]]\"\n}\n\n# don't hide data on reset, minimal\nspeedtest {\n format = \"speedtest[\\?soft ][[\\?color=elapsed_time {elapsed_time}] \"\n # format += \"[\\?color=ping {ping}] \"\n format += \"[\\?color=download {download}] [\\?color=upload {upload}]]\"\n}\nauthor Cyril Levis (@cyrinux)
"},{"location":"user-guide/modules/#spotify","title":"spotify","text":"Display song currently playing in Spotify.
Configuration parameters:
button_next button to switch to next song (default None)
button_play_pause button to toggle play/pause (default None)
button_previous button to switch to previous song (default None)
cache_timeout how often to update the bar (default 5)
dbus_client Used to override which app is used as a client for spotify. If you use spotifyd as a client, set this to 'org.mpris.MediaPlayer2.spotifyd' (default 'org.mpris.MediaPlayer2.spotify')
format see placeholders below (default '{artist} : {title}')
format_down define output if spotify is not running (default 'Spotify not running')
format_stopped define output if spotify is not playing (default 'Spotify stopped')
replacements specify a list/dict of string placeholders to modify (default None)
Format placeholders:
{album} album name
{artist} artiste name (first one)
{playback} state of the playback: Playing, Paused
{time} time duration of the song
{title} name of the song
Color options:
color_offline Spotify is not running, defaults to color_bad
color_paused Song is stopped or paused, defaults to color_degraded
color_playing Song is playing, defaults to color_good
Requires:
python-dbus to access dbus in python
spotify a proprietary music streaming service
Examples:
spotify {\n button_next = 4\n button_play_pause = 1\n button_previous = 5\n format = \"{title} by {artist} -> {time}\"\n format_down = \"no Spotify\"\n\n # sanitize\n replacements = {\n \"album\": [(\"\\s?[\\(\\[\\-,;/][^)\\],;/]*?(bonus|demo|edit|explicit|extended|feat|mono|remaster|stereo|version)[^)\\],;/]*[\\)\\]]?\", \"\")],\n \"title\": [(\"\\s?[\\(\\[\\-,;/][^)\\],;/]*?(bonus|demo|edit|explicit|extended|feat|mono|remaster|stereo|version)[^)\\],;/]*[\\)\\]]?\", \"\")]\n }\n}\nauthor Pierre Guilbert, Jimmy Garpeh\u00e4ll, sondrele, Andrwe
"},{"location":"user-guide/modules/#sql","title":"sql","text":"Display data stored in MariaDB, MySQL, sqlite3, and hopefully more.
Configuration parameters:
cache_timeout refresh cache_timeout for this module (default 10)
database specify database name to import (default None)
format display format for this module (default '{format_row}')
format_row display format for SQL rows (default None)
format_separator show separator if more than one (default ' ')
parameters specify connection parameters to use (default None)
query specify command to query a database (default None)
thresholds specify color thresholds to use (default [])
Format placeholders:
{row} number of SQL rows
{format_row} format for SQL rows Parameters can be placeholders too, eg {host}, {passd}
Format_row placeholders:
{field} placeholders will have the value returned by the query for the fieldColor thresholds:
format row: print a color based on the number of SQL rows
format_row field: print a color based on the value of field placeholder
Requires:
mariadb fast sql database server, drop-in replacement for mysql
mysql-python mysql support for python
sqlite a c library that implements an sql database engine
Examples:
# specify database name to import\nsql {\n database = 'sqlite3' # from sqlite3 import connect\n database = 'MySQLdb' # from MySQLdb import connect\n database = '...' # from ... import connect\n}\n\n# specify connection parameters to use\nhttp://mysql-python.sourceforge.net/MySQLdb.html#functions-and-attributes\nhttps://docs.python.org/3/library/sqlite3.html#module-functions-and-constants\nsql {\n name = 'MySQLdb'\n format = '{host} {passd} ...'\n parameters = {\n 'host': 'host',\n 'passwd': 'password',\n '...': '...',\n }\n}\n\n# specify command to query a database\nsql {\n query = 'SHOW SLAVE STATUS'\n query = 'SELECT * FROM cal_todos'\n query = '...'\n}\n\n# display number of seconds behind master with MySQLdb\nsql {\n database = 'MySQLdb'\n format_row = '\\?color=seconds_behind_master {host} is '\n format_row += '[{seconds_behind_master}s behind|\\?show master]'\n parameters = {\n 'host': 'localhost',\n 'passwd': '********'\n }\n query = 'SHOW SLAVE STATUS'\n thresholds = [\n (0, 'deepskyblue'), (100, 'good'), (300, 'degraded'), (600, 'bad')\n ]\n}\n\n# display thunderbird tasks with sqlite3\nsql {\n database = 'sqlite3'\n format_row = '{title}'\n format_separator = ', '\n query = 'SELECT * FROM cal_todos'\n parameters = '~/.thunderbird/user.default/calendar-data/local.sqlite'\n}\nauthor cereal2nd
license BSD
"},{"location":"user-guide/modules/#static_string","title":"static_string","text":"Display static text.
Configuration parameters:
format display format for this module (default 'Hello, world!')author frimdo ztracenastopa@centrum.cz
"},{"location":"user-guide/modules/#sway_idle","title":"sway_idle","text":"Display sway inhibit idle status.
This Module shows an indicator, if an idle is inhibited by an inhibitor. For more information about inhibit idle see man 5 sway
Configuration parameters:
cache_timeout How often we refresh this module in seconds (default 1)
format Display format (default 'Inhibit Idle: {inhibit_idle}')
Format placeholders:
{inhibit_idle} Returns 'True' if idle is inhibited, 'False' else.Example:
sway_idle {\n format = \"Inhibit Idle: [\\?if=inhibit_idle=True True]|False\"\n}\nauthor Valentin Weber <valentin+py3status@wv2.ch>
license BSD
"},{"location":"user-guide/modules/#sysdata","title":"sysdata","text":"Display system RAM, SWAP and CPU utilization.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 10)
cpu_freq_unit the unit of CPU frequency to use in report, case insensitive. ['kHz', 'MHz', 'GHz'] (default 'GHz')
cpu_temp_unit specify cpu temperature unit ['C', 'F', 'K'] (default 'C')
cpus specify a list of CPUs to use (default ['cpu?'])*
format output format string (default '[\\?color=cpu_used_percent CPU: {cpu_used_percent}%], ' '[\\?color=mem_used_percent Mem: {mem_used}/{mem_total} ' '{mem_total_unit} ({mem_used_percent}%)]')
format_cpu display format for CPUs (default '\\?color=used_percent {used_percent}%')
format_cpu_separator show separator if more than one (default ' ')
mem_unit the unit of memory to use in report, case insensitive. ['dynamic', 'KiB', 'MiB', 'GiB'] (default 'GiB')
swap_unit the unit of swap to use in report, case insensitive. ['dynamic', 'KiB', 'MiB', 'GiB'] (default 'GiB')
thresholds specify color thresholds to use (default [(0, \"good\"), (40, \"degraded\"), (75, \"bad\")])
Format placeholders:
{cpu_freq_avg} average CPU frequency across all cores
{cpu_freq_max} highest CPU clock frequency
{cpu_freq_unit} unit for frequency
{cpu_temp} cpu temperature
{cpu_temp_unit} cpu temperature unit
{cpu_used_percent} cpu used percentage
{format_cpu} format for CPUs
{load1} load average over the last minute
{load5} load average over the five minutes
{load15} load average over the fifteen minutes
{mem_total} total memory
{mem_total_unit} memory total unit, eg GiB
{mem_used} used memory
{mem_used_unit} memory used unit, eg GiB
{mem_used_percent} used memory percentage
{mem_free} free memory
{mem_free_unit} free memory unit, eg GiB
{mem_free_percent} free memory percentage
{swap_total} total swap
{swap_total_unit} swap total memory unit, eg GiB
{swap_used} used swap
{swap_used_unit} swap used memory unit, eg GiB
{swap_used_percent} used swap percentage
{swap_free} free swap
{swap_free_unit} free swap unit, eg GiB
{swap_free_percent} free swap percentage
format_cpu placeholders:
{name} cpu name, eg cpu, cpu0, cpu1, cpu2, cpu3
{used_percent} cpu used percentage, eg 88.99
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
lm_sensors a tool to read cpu temperatureExamples:
# specify a list of cpus to use. see \"grep cpu /proc/stat\"\nsysdata {\n cpus = [] # avg + all CPUs\n cpus = ['cpu'] # avg # same as {cpu_used_percent}\n cpus = ['cpu0', 'cpu2'] # selective CPUs # full\n cpus = ['cpu?*'] # all CPUs # fnmatch (default)\n}\n\n# display per cpu percents\nsysdata {\n format = \"{format_cpu}\"\n format_cpu = \"{name} [\\?color=used_percent {used_percent}%]\"\n}\n\n# customize per cpu padding, precision, etc\nsysdata {\n format = \"CPU {format_cpu}\"\n format_cpu = \"[\\?min_length=4 [\\?color=used_percent {used_percent:.0f}%]]\"\n}\n\n# display per cpu histogram\nsysdata {\n format = \"CPU Histogram [\\?color=cpu_used_percent {format_cpu}]\"\n format_cpu = \"[\\?if=used_percent>80 \u2847|[\\?if=used_percent>60 \u2846\"\n format_cpu += \"|[\\?if=used_percent>40 \u2844|[\\?if=used_percent>20 \u2840\"\n format_cpu += \"|\u2800]]]]\"\n format_cpu_separator = \"\"\n thresholds = [(0, \"good\"), (60, \"degraded\"), (80, \"bad\")]\n cache_timeout = 1\n}\nauthor Shahin Azad <ishahinism at Gmail>, shrimpza, guiniol, JackDoan <me at jackdoan dot com>, farnoy
"},{"location":"user-guide/modules/#systemd","title":"systemd","text":"Display status of a service on your system.
Configuration parameters:
cache_timeout refresh interval for this module (default 5)
format display format for this module (default '\\?if=!hide {unit}: {status}')
hide_extension suppress extension of the systemd unit (default False)
hide_if_default suppress the output if the systemd unit is in default state 'off' the output is never suppressed 'on' the output is suppressed if the unit is (enabled and active) or (disabled and inactive) 'active' the output is suppressed if the unit is active 'inactive' the output is suppressed if the unit is inactive (default 'off')
unit specify the systemd unit to use (default 'dbus.service')
user specify if this is a user service (default False)
Format placeholders:
{unit} unit name, eg sshd.service
{status} unit status, eg active, inactive, not-found
Color options:
color_good unit active
color_bad unit inactive
color_degraded unit not-found
Requires:
dbus-python to interact with dbus
pygobject which in turn requires libcairo2-dev, libgirepository1.0-dev
Examples:
# show the status of vpn service\n# left click to start, right click to stop\nsystemd vpn {\n unit = 'vpn.service'\n on_click 1 = 'exec sudo systemctl start vpn'\n on_click 3 = 'exec sudo systemctl stop vpn'\n}\nauthor Adrian Lopez <adrianlzt@gmail.com>
license BSD
"},{"location":"user-guide/modules/#systemd_suspend_inhibitor","title":"systemd_suspend_inhibitor","text":"Turn on and off systemd suspend inhibitor.
Configuration parameters:
format display format for this module (default '[\\?color=state SUSPEND [\\?if=state OFF|ON]]')
lock_types specify state to inhibit, comma separated list https://www.freedesktop.org/wiki/Software/systemd/inhibit/ (default ['handle-lid-switch', 'idle', 'sleep'])
thresholds specify color thresholds to use (default [(True, 'bad'), (False, 'good')])
Format placeholders:
{state} systemd suspend inhibitor state, eg True, FalseColor thresholds:
xxx print a color based on the value of xxx placeholderauthor Cyrinux https://github.com/cyrinux
license BSD
"},{"location":"user-guide/modules/#taskwarrior","title":"taskwarrior","text":"Display tasks currently running in taskwarrior.
Configuration parameters:
cache_timeout refresh interval for this module (default 5)
filter specify one or more criteria to use (default 'status:pending')
format display format for this module (default '{descriptions}')
report report to export, for TaskWarrior 2.6.0 and above (default '')
Format placeholders:
{descriptions} descriptions of active tasks
{tasks} number of active tasks
Requires task: https://taskwarrior.org/download/
author James Smith https://jazmit.github.io
license BSD
"},{"location":"user-guide/modules/#thunderbird_todos","title":"thunderbird_todos","text":"Display number of todos and more for Thunderbird.
Configuration parameters:
cache_timeout refresh interval for this module (default 60)
format display format for this module (default '{format_todo}')
format_datetime specify strftime formatting to use (default {})
format_separator show separator if more than one (default ' ')
format_todo display format for todos (default '\\?if=!todo_completed {title}')
profile specify a profile path, otherwise first available profile eg '~/.thunderbird/abcd1234.default' (default None)
sort specify a tuple, eg ('placeholder_name', reverse_boolean) to sort by; excluding placeholder indexes (default ())
thresholds specify color thresholds to use (default [])
Format placeholders:
{todo_total} eg 5
{todo_completed} eg 2
{todo_incompleted} eg 3
{format_todo} format for todos
format_todo placeholders:
{index_total} eg 1, 2, 3
{index_completed} eg 1, 2, 3
{index_incompleted} eg 1, 2, 3
{alarm_last_ack} eg None, 1513291952000000
{cal_id} eg 966bd855-5e71-4168-8072-c98f244ed825
{flags} eg 4, 276
{ical_status} eg None, IN-PROCESS, COMPLETED
{id} eg 87e9bfc9-eaad-4aa6-ad5f-adbf6d7a11a5
{last_modified} eg 1513276147000000
{offline_journal} eg None
{priority} eg None, # None=None, 0=None, 1=High, 5=Normal, 9=Low
{privacy} eg None, CONFIDENTIAL
{recurrence_id} eg None
{recurrence_id_tz} eg None, UTC
{time_created} eg 1513276147000000
{title} eg New Task
{todo_complete} eg None
{todo_completed} eg None, 1513281528000000
{todo_completed_tz} eg None, UTC
{todo_due} eg None, 1513292400000000
{todo_due_tz} eg None, America/Chicago
{todo_entry} eg None, 1513292400000000
{todo_entry_tz} eg None, America/Chicago
{todo_stamp} eg 1513276147000000
format_datetime placeholders: KEY: alarm_last_ack, last_modified, time_created, todo, todo_completed, todo_entry, todo_stamp VALUE: % strftime characters to be translated, eg '%b %d' ----> 'Dec 14' SEE EXAMPLE BELOW: \"show incompleted titles with last modified time\"
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
thunderbird standalone mail and news readerExamples:
# show number of incompleted titles\nthunderbird_todos {\n format = '{todo_incompleted} incompleted todos'\n}\n\n# show rainbow number of incompleted titles\nthunderbird_todos {\n format = '\\?color=todo_incompleted {todo_incompleted} todos'\n thresholds = [\n (1, '#bababa'), (2, '#ffb3ba'), (3, '#ffdfba'), (4, '#ffffba'),\n (5, '#baefba'), (6, '#baffc9'), (7, '#bae1ff'), (8, '#bab3ff')\n ]\n}\n\n# show rainbow incompleted titles\nthunderbird_todos {\n format_todo = '\\?if=!todo_completed&color=index_incompleted {title}'\n thresholds = [\n (1, '#bababa'), (2, '#ffb3ba'), (3, '#ffdfba'), (4, '#ffffba'),\n (5, '#baefba'), (6, '#baffc9'), (7, '#bae1ff'), (8, '#bab3ff')\n ]\n}\n\n# show incompleted titles with last modified time\nthunderbird_todos {\n format_todo = '\\?if=!todo_completed {title} {last_modified}'\n format_datetime = {\n 'last_modified': '\\?color=degraded last modified %-I:%M%P'\n }\n}\n\n# show 'No todos'\nthunderbird_todos {\n format = '{format_todo}|No todos'\n}\n\n# show completed titles and incompleted titles\nthunderbird_todos {\n format_todo = '\\?if=todo_completed&color=good {title}|\\?color=bad {title}'\n}\n\n# make todo blocks\nthunderbird_todos {\n format = 'TODO {format_todo}'\n format_todo = '\\?if=todo_completed&color=good \u25b0|\\?color=bad \u25b0'\n format_separator = ''\n}\n\n# display incompleted titles with any priority\nthunderbird_todos {\n format_todo = '\\?if=!todo_completed [\\?if=priority>0 {title}]'\n}\n\n# colorize titles based on priorities\nthunderbird_todos {\n format_todo = '\\?if=!todo_completed [\\?color=priority {title}]'\n thresholds = [(0, None), (1, 'red'), (5, None), (9, 'deepskyblue')]\n}\n\n# sort todos\nthunderbird_todos {\n sort = ('last_modified', True) # sort by modified time: recent first\n sort = ('priority', True) # sort by priority: high to low\n sort = ('title', False) # sort by title: ABC to abc\n}\n\n# add your snippets here\nthunderbird_todos {\n format = '...'\n}\nauthor mrt-prodz, lasers
"},{"location":"user-guide/modules/#timer","title":"timer","text":"A simple countdown timer.
This is a very basic countdown timer. You can change the timer length as well as pausing, restarting and resetting it. Currently this is more of a demo of a composite.
Each part of the timer can be changed independently hours, minutes, seconds using mouse buttons 4 and 5 (scroll wheel). Button 1 starts/pauses the countdown. Button 2 resets timer.
Configuration parameters:
format display format for this module (default 'Timer {timer}')
sound play sound file path when the timer ends (default None)
time number of seconds to start countdown with (default 60)
Format placeholders:
{timer} display hours:minutes:secondsauthor tobes
"},{"location":"user-guide/modules/#timewarrior","title":"timewarrior","text":"Track your time with Timewarrior.
Timewarrior is a time tracking utility that offers simple stopwatch features as well as sophisticated calendar-base backfill, along with flexible reporting. See https://taskwarrior.org/docs/timewarrior for more information.
Configuration parameters:
cache_timeout refresh interval for this module, otherwise auto (default None)
filter specify interval and/or tag to filter (default '1day')
format display format for this module (default '[Timew {format_time}]|No Timew')
format_datetime specify strftime characters to format (default {})
format_duration display format for time duration (default '\\?not_zero [{days}d ][{hours}:]{minutes}:{seconds}')
format_tag display format for tags (default '\\?color=state_tag {name}')
format_tag_separator show separator if more than one (default ' ')
format_time display format for tracked times (default '[\\?color=state_time [{format_tag} ]{format_duration}]')
format_time_separator show separator if more than one (default ' ')
thresholds specify color thresholds to use (default {'state_tag': [(0, 'darkgray'), (1, 'darkgray')], 'state_time': [(0, 'darkgray'), (1, 'degraded')]})
Format placeholders:
{format_time} format for tracked times
{tracking} time tracking state, eg False, True
format_time placeholders:
{state} time tracking state, eg False, True
{format_tag} format for tags
{format_duration} format for time duration
{start} start date, eg 20171021T010203Z
{end} end date, eg 20171021T010203Z
format_tag placeholders:
{name} tag name, eg gaming, studying, gardeningformat_datetime placeholders:
key start, end
value strftime characters, eg '%b %d' ----> 'Oct 06'
format_duration placeholders:
{days} days
{hours} hours
{minutes} minutes
{seconds} seconds
Color thresholds:
format_time state_time: print color based on the state of time tracking
format_tag state_tag: print color based on the state of time tracking
Requires:
timew feature-rich time tracking utilityRecommendations: We can refresh a module using py3-cmd command. An excellent example of using this command in a function.
```\n~/.{bash,zsh}{rc,_profile}\n---------------------------\nfunction timew () {\n command timew \"$@\" && py3-cmd refresh timewarrior\n}\n```\n\nWith this, you can consider giving `cache_timeout` a much larger number,\neg 3600 (an hour), so the module does not need to be updated that often.\nExamples:
# show times matching the filter, see documentation for more filters\ntimewarrior {\n filter = ':day' # filter times not in 24 hours of current day\n filter = '12hours' # filter times not in 12 hours of current time\n filter = '5min' # filter times not in 5 minutes of current time\n filter = '1sec' # filter times not in 1 second of current time\n filter = '5pm to 11:59pm # filter times not in 5pm to 11:59pm range\n}\n\n# intervals\ntimewarrior {\n # if you are printing other intervals too with '1day' filter or so,\n # then you may want to add this too for better bar readability\n format_time_separator = ', '\n\n # you also can change the thresholds with different colors\n thresholds = {\n 'state_tag': [(0, 'darkgray'), (1, 'degraded')],\n 'state_time': [(0, 'darkgray'), (1, 'degraded')],\n }\n}\n\n# cache_timeout\ntimewarrior {\n # auto refresh every 10 seconds when there is no active time tracking\n # auto refresh every second when there is active time tracking\n cache_timeout = None\n\n # refresh every minute when there is no active time tracking\n # refresh every second when there is active time tracking\n cache_timeout = 60\n\n # explicit refresh every 20 seconds when there is no active time tracking\n # explicit refresh every 5 seconds when there is active time tracking\n cache_timeout = (20, 5)\n}\n\n# add your snippets here\ntimewarrior {\n format = \"...\"\n}\nauthor lasers
"},{"location":"user-guide/modules/#tor_rate","title":"tor_rate","text":"Display transfer rates of a tor instance.
Configuration parameters:
cache_timeout An integer specifying the cache life-time of the modules output in seconds (default 2)
control_address The address on which the Tor daemon listens for control connections (default \"127.0.0.1\")
control_password The password to use for the Tor control connection (default None)
control_port The port on which the Tor daemon listens for control connections (default 9051)
format A string describing the output format for the module (default \"\u2191 {up} \u2193 {down}\")
format_value A string describing how to format the transfer rates (default \"[\\?min_length=12 {rate:.1f} {unit}]\")
hide_socket_errors Hide errors connecting to Tor control socket (default False)
rate_unit The unit to use for the transfer rates (default \"B/s\")
si_units A boolean value selecting whether or not to use SI units (default False)
Format placeholders:
{down} The incoming transfer rate
{up} The outgoing transfer rate
format_value placeholders:
{rate} The current transfer-rate's value
{unit} The current transfer-rate's unit
Requires:
stem python controller library for tor https://pypi.org/project/stemExamples:
tor_rate {\n cache_timeout = 10\n format = \"IN: {down} | OUT: {up}\"\n control_port = 1337\n control_password = \"TertiaryAdjunctOfUnimatrix01\"\n si_units = True\n}\nauthor Felix Morgner <felix.morgner@gmail.com>
license 3-clause-BSD
"},{"location":"user-guide/modules/#transmission","title":"transmission","text":"Display number of torrents and more.
Configuration parameters:
arguments additional arguments for the transmission-remote (default None)
button_next mouse button to switch next torrent (default None)
button_previous mouse button to switch previous torrent (default None)
button_run mouse button to run the command on current torrent (default [(1, '--start'), (2, '--verify'), (3, '--stop')])
cache_timeout refresh interval for this module (default 20)
format display format for this module (default '{format_torrent}')
format_separator show separator if more than one (default ' ')
format_torrent display format for torrents (default '[\\?if=is_focused&color=bad X] {status} {id} {name} {done}%')
thresholds specify color thresholds to use (default [])
Format placeholders:
{torrent} number of torrents
{format_torrent} format for torrents
{up} summary up traffic
{down} summary down traffic
{have} summary download
format_torrent placeholders:
{index} torrent index, eg 1
{id} torrent id, eg 2
{done} torrent percent, eg 100%
{have} torrent download, 253 KB
{eta} torrent estimated time, eg Done, 1 min, etc
{up} torrent up traffic
{down} torrent down traffic
{ratio} torrent seed ratio
{status} torrent status, eg Idle, Downloading, Stopped, Verifying, etc
{name} torrent name, eg py3status-3.8.tar.gz
Color options:
color_bad current torrentColor thresholds:
xxx print a color based on the value of xxx placeholderRequires:
transmission-cli fast, easy, and free bittorrent client (cli tools, daemon, web client)Examples:
# add arguments\ntransmission {\n # We use 'transmission-remote --list'\n # See `transmission-remote --help' for more information.\n # Not all of the arguments will work here.\n arguments = '--auth username:password --port 9091'\n}\n# see 'man transmission-remote' for more buttons\ntransmission {\n button_run = [\n (1, '--start'),\n (2, '--verify'),\n (3, '--stop'),\n (8, '--remove'),\n (9, '--exit'),\n ]\n}\n\n# open web-based transmission client\ntransmission {\n on_click 1 = 'exec xdg-open http://username:password@localhost:9091'\n}\n\n# add buttons\ntransmission {\n button_next = 5\n button_previous = 4\n}\n\n# see 'man transmission-remote' for more buttons\ntransmission {\n # specify a script to run when a torrent finishes\n on_click 9 = 'exec transmission-remote --torrent-done-script ~/file'\n\n # use the alternate limits?\n on_click 9 = 'exec transmission-remote --alt-speed'\n on_click 10 = 'exec transmission-remote --no-alt-speed'\n}\n\n# show summary statistcs - up, down, have\ntransmission {\n format = '{format_torrent}'\n format += '[\\?color=#ffccff [\\?not_zero Up:{up}]'\n format += '[\\?not_zero Down:{down}][\\?not_zero Have:{have}]]'\n}\n\n# add a format that sucks less than the default plain format\ntransmission {\n format_torrent = '[\\?if=is_focused&color=bad X ]'\n format_torrent += '[[\\?if=status=Idle&color=degraded {status}]'\n format_torrent += '|[\\?if=status=Stopped&color=bad {status}]'\n format_torrent += '|[\\?if=status=Downloading&color=good {status}]'\n format_torrent += '|[\\?if=status=Verifying&color=good {status}]'\n format_torrent += '|\\?color=degraded {status}]'\n format_torrent += ' {name} [\\?color=done {done}]'\n}\n\n# show percent thresholds\ntransmission {\n format_torrent = '{name} [\\?color=done {done}]'\n thresholds = [(0, 'bad'), (1, 'degraded'), (100, 'good')]\n}\n\n# download the rainbow\ntransmission {\n format_torrent = '[\\?if=is_focused&color=bad X ]'\n format_torrent += '{status} [\\?color=index {name}] [\\?color=done {done}%]'\n thresholds = {\n 'done': [(0, '#ffb3ba'), (1, '#ffffba'), (100, '#baefba')],\n 'index': [\n (1, '#ffb3ba'), (2, '#ffdfba'), (3, '#ffffba'),\n (4, '#baefba'), (5, '#baffc9'), (6, '#bae1ff'),\n (7, '#bab3ff')\n ]\n }\n}\nauthor lasers
"},{"location":"user-guide/modules/#twitch","title":"twitch","text":"Display if a Twitch channel is currently streaming or not.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 60)
client_id Your client id. Create your own key at https://dev.twitch.tv (default None)
client_secret Your client secret. (default None)
format Display format when online (default \"{display_name} is live!\")
format_offline Display format when offline (default \"{display_name} is offline.\")
format_tag Tag formatting (default \"{name}\")
locales List of locales to try for tag translations, eg. [\"cs-cz\", \"en-uk\", \"en-us\"]. If none is specified, auto-detect from environment, with a fallback to \"en-us\". (default [])
stream_name name of streamer(twitch.tv/<stream_name>) (default None)
tag_delimiter string to write between tags (default \" \")
trace enable trace level debugging (default False)
Stream format placeholders:
{display_name} User's display name., eg Ultrabug
{is_streaming} (bool) True if streaming, fields prefixed with stream_ are available.
{tags} List of tags
{user_id} User's id
{user_login} User's login name, eg xisumavoid
{user_display_name} (same as {display_name})
{user_type} \"staff\", \"admin\", \"global_mod\", or \"\"
{user_broadcaster_type} \"partner\", \"affiliate\", or \"\".
{user_description} User's channel description.
{user_profile_image_url} URL of the user's profile image.
{user_offline_image_url} URL of the user's offline image.
{user_view_count} Total number of views of the user's channel.
{user_created_at} Date when the user was created.
{stream_id} Stream ID.
{stream_game_id} ID of the game being played on the stream.
{stream_game_name} Name of the game being played.
{stream_title} Stream title.
{stream_viewer_count} Number of viewers watching the stream at the time of last update.
{stream_started_at} Stream start UTC timestamp.
{stream_language} Stream language. A language value is either the ISO 639-1 two-letter code or \u201cother\u201d.
{stream_thumbnail_url} Thumbnail URL of the stream. All image URLs have variable width and height. You can replace {width} and {height} with any values to get that size image
{stream_is_mature} Indicates if the broadcaster has specified their channel contains mature content that may be inappropriate for younger audiences.
{stream_runtime} (string) Stream runtime as a human readable, non-localized string. eg \"3h 5m\"
{stream_runtime_seconds} (int) Stream runtime in seconds.
Tag format placeholders: (see locales) {name} The tag name {desc} The tag description
Color options:
color_bad Stream offline
color_good Stream is live
Client ID: Example settings when creating your app at https://dev.twitch.tv
Name: <your_name>_py3status\nOAuth Redirect URI: https://localhost\nApplication Category: Application Integration\nauthor Alex Caswell horatioesf@virginmedia.com
author Julian Picht julian.picht@gmail.com
license BSD
"},{"location":"user-guide/modules/#uname","title":"uname","text":"Display system information.
Configuration parameters:
format display format for this module (default '{system} {release}')Format placeholders:
{system} system/OS name, e.g. 'Linux', 'Windows', or 'Java'
{node} computer\u2019s network name (may not be fully qualified!)
{release} system\u2019s release, e.g. '2.2.0' or 'NT'
{version} system\u2019s release version, e.g. '#3 on degas'
{machine} machine type, e.g. 'x86_64'
{processor} the (real) processor name, e.g. 'amdk6'
author ultrabug (inspired by ndalliard)
"},{"location":"user-guide/modules/#uptime","title":"uptime","text":"Display system uptime.
Configuration parameters:
format display format for this module (default 'up {days} days {hours} hours {minutes} minutes')Format placeholders:
{decades} decades
{years} years
{weeks} weeks
{days} days
{hours} hours
{minutes} minutes
{seconds} seconds
If you don't use a placeholder, its value will be carried over to the next placeholder. For example, an uptime of 1 hour 30 minutes will give you 90 if {minutes} or 1:30 if {hours}:{minutes}.
You also can specify strftime characters to print system up since with or without placeholders. See man strftime for more information.
Examples:
# show uptime without zeroes\nuptime {\n format = 'up [\\?if=weeks {weeks} weeks ][\\?if=days {days} days ]\n [\\?if=hours {hours} hours ][\\?if=minutes {minutes} minutes ]'\n}\n\n# show uptime in multiple formats using group module\ngroup uptime {\n format = \"up {output}\"\n uptime {\n format = '[\\?if=weeks {weeks} weeks ][\\?if=days {days} days ]\n [\\?if=hours {hours} hours ][\\?if=minutes {minutes} minutes]'\n }\n uptime {\n format = '[\\?if=weeks {weeks}w ][\\?if=days {days}d ]\n [\\?if=hours {hours}h ][\\?if=minutes {minutes}m]'\n }\n uptime {\n format = '[\\?if=days {days}, ][\\?if=hours {hours}:]\n [\\?if=minutes {minutes:02d}]'\n }\n}\n\n# specify strftime characters to display system up since\nuptime {\n format = \"{days}d {hours}:{minutes:02d}:{seconds:02d}\"\n format += \", up since %Y-%m-%d %H:%M:%S\"\n}\nauthor Alexis \"Horgix\" Chotard <alexis.horgix.chotard@gmail.com>, Volkov \"BabyWolf\" Semjon <Volkov.BabyWolf.Semjon@gmail.com>
license BSD
"},{"location":"user-guide/modules/#usbguard","title":"usbguard","text":"Allow or Reject newly plugged USB devices using USBGuard.
Configuration parameters:
format display format for this module (default '{format_device}')
format_button_allow display format for allow button filter (default '[Allow]')
format_button_reject display format for reject button filter (default '[Reject]')
format_device display format for USB devices (default '{format_button_reject} [{name}|{usb_id}] {format_button_allow}')
format_device_separator show separator if more than one (default ' ')
Format placeholders:
{device} number of USB devices
{format_device} format for USB devices
format_device:
{format_button_allow} button to allow the device
{format_button_reject} button to reject the device
{id} eg 1, 2, 5, 6, 7, 22, 23, 33
{policy} eg allow, block, reject
{usb_id} eg 054c:0268
{name} eg Poker II, PLAYSTATION(R)3 Controller
{serial} eg 0000:00:00.0
{port} eg usb1, usb2, usb3, 1-1, 4-1.2.1
{interface} eg 00:00:00:00 00:00:00 00:00:00
{hash} eg ihYz60+8pxZBi/cm+Q/4Ibrsyyzq/iZ9xtMDAh53sng
{parent_hash} eg npSDT1xuEIOSLNt2RT2EbFrE8XRZoV29t1n7kg6GxXg
Requires:
python-gobject Python Bindings for GLib/GObject/GIO/GTK+
usbguard USB device authorization policy framework
author @cyrinux, @maximbaz
license BSD
"},{"location":"user-guide/modules/#vnstat","title":"vnstat","text":"Display vnstat statistics.
Configuration parameters:
cache_timeout refresh interval for this module (default 180)
format display format for this module (default '{total}')
initial_multi set to 1 to disable first bytes (default 1024)
left_align (default 0)
multiplier_top if value is greater, divide it with unit_multi and get next unit from units (default 1024)
precision (default 1)
statistics_type d for daily, m for monthly (default 'd')
thresholds thresholds to use for color changes (default [])
unit_multi value to divide if rate is greater than multiplier_top (default 1024)
Format placeholders:
{down} download
{total} total
{up} upload
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
vnstat a console-based network traffic monitorExamples:
# colorize thresholds\nvnstat {\n format = '[\\?color=total {total}]'\n thresholds = [\n (838860800, \"degraded\"), # 838860800 B -> 800 MiB\n (943718400, \"bad\"), # 943718400 B -> 900 MiB\n ]\n}\nauthor shadowprince
license Eclipse Public License
"},{"location":"user-guide/modules/#volume_status","title":"volume_status","text":"Volume control.
Configuration parameters:
blocks a string, where each character represents a volume level (default \"_\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588\")
button_down button to decrease volume (default 5)
button_mute button to toggle mute (default 1)
button_up button to increase volume (default 4)
cache_timeout how often we refresh this module in seconds. (default 10)
card Card to use. amixer supports this. (default None)
channel channel to track. Default value is backend dependent. (default None)
command Choose between \"amixer\", \"pamixer\" or \"pactl\". If None, try to guess based on available commands. (default None)
device Device to use. Defaults value is backend dependent. \"aplay -L\", \"pactl list sinks short\", \"pamixer --list-sinks\" (default None)
format Format of the output. (default '[\\?if=is_input \ud83d\ude2e|\u266a]: {percentage}%')
format_muted Format of the output when the volume is muted. (default '[\\?if=is_input \ud83d\ude36|\u266a]: muted')
is_input Is this an input device or an output device? (default False)
max_volume Allow the volume to be increased past 100% if available. pactl and pamixer supports this. (default 120)
thresholds Threshold for percent volume. (default [(0, 'bad'), (20, 'degraded'), (50, 'good')])
volume_delta Percentage amount that the volume is increased or decreased by when volume buttons pressed. (default 5)
Format placeholders:
{icon} Character representing the volume level, as defined by the 'blocks'
{percentage} Percentage volume
Color options:
color_muted Volume is muted, if not supplied color_bad is used if set to None then the threshold color will be used.Requires:
alsa-utils an alternative implementation of linux sound support
pamixer pulseaudio command-line mixer like amixer
Notes: If you are changing volume state by external scripts etc and want to refresh the module quicker than the i3status interval, send a USR1 signal to py3status in the keybinding. Example: killall -s USR1 py3status
Examples:
# Set thresholds to rainbow colors\nvolume_status {\n thresholds = [\n (0, \"#FF0000\"),\n (10, \"#E2571E\"),\n (20, \"#FF7F00\"),\n (30, \"#FFFF00\"),\n (40, \"#00FF00\"),\n (50, \"#96BF33\"),\n (60, \"#0000FF\"),\n (70, \"#4B0082\"),\n (80, \"#8B00FF\"),\n (90, \"#FFFFFF\")\n ]\n}\nauthor <Jan T> <jans.tuomi@gmail.com>
license BSD
"},{"location":"user-guide/modules/#vpn_status","title":"vpn_status","text":"Drop-in replacement for i3status run_watch VPN module.
Expands on the i3status module by displaying the name of the connected vpn using pydbus. Asynchronously updates on dbus signals unless check_pid is True.
Configuration parameters:
cache_timeout How often to refresh in seconds when check_pid is True. (default 10)
check_pid If True, act just like the default i3status module. (default False)
format Format of the output. (default 'VPN: {format_vpn}|VPN: no')
format_vpn display format for vpns (default '{name}')
format_vpn_separator show separator if more than one VPN (default ', ')
pidfile Same as i3status pidfile, checked when check_pid is True. (default '/sys/class/net/vpn0/dev_id')
Format placeholders:
{format_vpn} format for VPNsFormat VPN placeholders:
{name} The name and/or status of the VPN.
{ipv4} The IPv4 address of the VPN
{ipv6} The IPv6 address of the VPN
Color options:
color_bad VPN connected
color_good VPN down
Requires:
dbus-python to interact with dbus
pygobject which in turn requires libcairo2-dev, libgirepository1.0-dev
author Nathan Smith <nathan AT praisetopia.org>
"},{"location":"user-guide/modules/#wanda_the_fish","title":"wanda_the_fish","text":"Display a fortune-telling, swimming fish.
Wanda has no use what-so-ever. It only takes up disk space and compilation time, and if loaded, it also takes up precious bar space, memory, and cpu cycles. Anybody found using it should be promptly sent for a psychiatric evaluation.
Configuration parameters:
cache_timeout refresh interval for this module (default 0)
format display format for this module (default '{nomotion}[{fortune} ]{wanda}{motion}')
fortune_timeout refresh interval for fortune (default 60)
Format placeholders:
{fortune} one of many aphorisms or vague prophecies
{wanda} name of one of the most commonly kept freshwater aquarium fish
{motion} biologically propelled motion through a liquid medium
{nomotion} opposite behavior of motion to prevent modules from shifting
Optional:
fortune-mod the fortune cookie program from bsd gamesExamples:
# disable motions when not in use\nwanda_the_fish {\n format = '[\\?if=fortune {nomotion}][{fortune} ]'\n format += '{wanda}[\\?if=fortune {motion}]'\n}\n\n# no updates, no motions, yes fortunes, you click\nwanda_the_fish {\n format = '[{fortune} ]{wanda}'\n cache_timeout = -1\n}\n\n# wanda moves, fortunes stays\nwanda_the_fish {\n format = '[{fortune} ]{nomotion}{wanda}{motion}'\n}\n\n# wanda is swimming too fast, slow down wanda\nwanda_the_fish {\n cache_timeout = 2\n}\nauthor lasers
"},{"location":"user-guide/modules/#watson","title":"watson","text":"Display the current status of the watson time-tracking tool.
Configuration parameters:
cache_timeout Number of seconds before state is re-read (default 10)
format The format for module output. (default 'Project {project}{tag_str} started')
state_file Path to the file which watson uses to track its own state (default '~/.config/watson/state')
Format placeholders:
{project} Name of the active project
{tag_str} String-representation of the list of active tags
Requires:
https://github.com/TailorDev/Watson commandline time tracking toolauthor Markus Sommer (https://github.com/CryptoCopter)
license BSD
"},{"location":"user-guide/modules/#weather_owm","title":"weather_owm","text":"Display ultimately customizable weather.
This module allows you to specify an icon for nearly every weather scenario imaginable. The default configuration options lump many of the icons into a few groups, and due to the limitations of UTF-8, this is really as expressive as it gets.
This module uses OpenWeatherMap API (https://openweathermap.org).
Requires a 3.0 API key for OpenWeatherMap (OWM) with a subscription which this module will try as hard as it can to stay under the free tier limit.
Setting location or city allows you to specify the location for the weather you want displaying.
I would highly suggest you install an additional font, such as the incredible (and free!) Weather Icons font (https://erikflowers.github.io/weather-icons), which has icons for most weather scenarios. But, this will still work with the i3bar default font, Deja Vu Sans Mono font, which has Unicode support. You can see the (limited) weather icon support within Unicode in the defaults.
For more information, see the documentation (https://openweathermap.org/weather-conditions) on what weather conditions are supported. See the configuration options for how to specify each weather icon.
Configuration parameters:
api_key Your OpenWeatherMap API key See https://openweathermap.org/appid. Required! (default None)
cache_timeout The time between API polling in seconds It is recommended to keep this at a higher value to avoid rate limiting with the API's. (default 1800)
city The city to display for location information. If set, implicitly disables the Geo API for determining city name. (default None)
country The country to display for location information. If set, implicitly disables the Geo API for determining country name. (default None)
forecast_days Number of days to include in the forecast, including today (regardless of the 'forecast_include_today' flag) (default 3)
forecast_include_today Include today in the forecast? (Boolean) (default False)
format How to display the weather This also dictates the type of forecast. The placeholders here refer to the format_[...] variables found below. Available placeholders: icon, city, clouds, rain, snow, wind, humidity, pressure, temperature, sunrise, sunset, main, description, forecast (default '{city} {icon} {temperature}[ {rain}], {description} {forecast}')
format_clouds Formatting for cloud coverage (percentage) Available placeholders: icon, coverage (default '{icon} {coverage}%')
format_forecast Formatting for future forecasts Available placeholders: See 'format' This is similar to the 'format' field, but contains information for future weather. Notably, this does not include information about sunrise or sunset times. (default '{icon}')
format_forecast_separator Separator between entries in the forecast (default ' ')
format_humidity Formatting for humidity (percentage) Available placeholders: icon, humidity (default '{icon} {humidity}%')
format_pressure Formatting for atmospheric pressure Available placeholders: icon, pressure, sea_level (default '{icon} {pressure} hPa')
format_rain Formatting for rain volume over the past 3 hours Available placeholders: icon, amount (default '[\\?if=amount {icon} {amount:.0f} {unit}]')
format_snow Formatting for snow volume over the past 3 hours Available placeholders: icon, amount (default '[\\?if=amount {icon} {amount:.0f} {unit}]')
format_sunrise Formatting for sunrise time Note that this format accepts strftime/strptime placeholders to populate the output with the time information. Available placeholders: icon (default '{icon} %-I:%M %p')
format_sunset Formatting for sunset time This format accepts strftime/strptime placeholders to populate the output with the time information. Available placeholders: icon (default '{icon} %-I:%M %p')
format_temperature Formatting for temperature Available placeholders: current, icon, max, min (default '{icon} [\\?color=all {current:.0f}\u00b0{unit}]')
format_wind Formatting for wind degree and speed The 'gust' option represents the speed of wind gusts in the wind unit. Available placeholders: icon, degree, speed, gust, direction (default '[\\?if=speed {icon} {speed:.0f} {unit}]')
icon_atmosphere Icon for atmospheric conditions, like fog, smog, etc. (default '\ud83c\udf2b')
icon_cloud Icon for clouds (default '\u2601')
icon_extreme Icon for extreme weather (default '\u26a0')
icon_humidity Icon for humidity (default '\u25cf')
icon_pressure Icon for pressure (default '\u25cc')
icon_rain Icon for rain (default '\ud83c\udf27')
icon_snow Icon for snow (default '\u2744')
icon_sun Icon for sunshine (default '\u263c')
icon_sunrise Icon for sunrise (default '\u21d1')
icon_sunset Icon for sunset (default '\u21d3')
icon_temperature Icon for temperature (default '\u25cb')
icon_thunderstorm Icon for thunderstorms (default '\u26c8')
icon_wind Icon for wind or breeze (default '\u2634')
icons A dictionary relating weather code to icon See https://openweathermap.org/weather-conditions for a complete list of supported icons. This will fall-back to the listed icon if there is no specific icon present. However, options included here take precedent over the above 'icon_{...}' options. There are multiple ways to specify individual icons based on the id:
lang An ISO 639-1 code for your language (two letters) (default 'en')
location A tuple of floats describing the desired weather location The tuple should follow the form (latitude, longitude), and if set, implicitly disables the Geo API for determining location. (default None)
thresholds Configure temperature colors based on limits The numbers specified inherit the unit of the temperature as configured. The default below is intended for Fahrenheit. If the set value is empty or None, the feature is disabled. You can specify this parameter using a dictionary:
unit_rain Unit for rain fall When specified, a unit may be any combination of upper and lower case, such as 'Ft', and still be considered valid as long as it is in the below options. Options: mm, cm, in (default 'in')
unit_snow Unit for snow fall Options: mm, cm, in (default 'in')
unit_temperature Unit for temperature Options: c, f, k (default 'F')
unit_wind Unit for wind speed Options: fsec, msec, mph, kmh, knot (default 'mph')
Format placeholders:
{icon} The icon associated with a formatting section
format_clouds
{coverage} Cloud coverage percentage
format_humidity
{humidity} Humidity percentage
format_pressure
{pressure} Current atmospheric pressure in Pascals
{sea_level} Sea-level atmospheric pressure in Pascals.
format_rain
{amount} Rainfall in the specified unit
{unit} The unit specified
format_snow
{amount} Snowfall in the specified unit
{unit} The unit specified
format_temperature
{current} Current temperature
{max} Maximum temperature in the configured unit
{min} Minimum temperature
{unit} The unit specified
format_wind
{degree} Current wind heading
{direction} Letter reprents direction e.g. N,NE,E etc
{gust} Wind gusts speed in the specified unit
{speed} Wind speed
{unit} The unit specified format only:
{city} The name of the city where the weather is
{country} The name of the country where the weather is
{forecast} Output of format_forecast format, format_forecast:
{clouds} Output of format_clouds
{description} Natural description of the current weather
{humidity} Output of format_humidity
{main} Short description of the current weather
{pressure} Output of format_pressure
{snow} Output of format_snow
{sunrise} Output of format_sunrise
{sunset} Output of format_sunset
{temperature} Output of format_temperature
{wind} Output of format_wind
Examples:
# change icons\nweather_owm {\n api_key = <my api key>\n icons = {\n '200': \"\u2614\"\n '230_232': \"\ud83c\udf27\"\n }\n}\n\n# set a city\nweather_owm {\n api_key = <my api key>\n city = 'London'\n}\n\n# set a location\nweather_owm {\n api_key = <my api key>\n location = (48.9342, 2.3548) # Saint-Denis\n}\nauthor alexoneill
@licence MIT
"},{"location":"user-guide/modules/#whatismyip","title":"whatismyip","text":"Display public IP address and online status.
Configuration parameters:
button_refresh mouse button to refresh this module (default 2)
button_toggle mouse button to toggle between states (default 1)
cache_timeout how often we refresh this module in seconds (default 60)
expected define expected values for format placeholders, and use color_degraded to show the output of this module if any of them does not match the actual value. This should be a dict eg {'country': 'France'} (default None)
format available placeholders are {ip} and {country}, as well as any other key in JSON fetched from url_geo (default '{ip}')
hide_when_offline hide the module output when offline (default False)
icon_off what to display when offline (default '\u25a0')
icon_on what to display when online (default '\u25cf')
mode default mode to display is 'ip' or 'status' (click to toggle) (default 'ip')
url_geo IP to check for geo location (must output json) (default 'https://ifconfig.co/json')
Format placeholders:
{icon} eg \u25cf, \u25a0
{country} eg France
{country_iso} eg FR
{ip} eg 123.45.67.890
{ip_decimal} eg 1234567890
{city} eg Paris any other key in JSON fetched from url_geo
Color options:
color_bad Offline
color_degraded Output is unexpected (IP/country mismatch, etc.)
color_good Online
Examples:
# ip choices\nwhatismyip {\n url_geo = \"https://ifconfig.co/json\"\n # url_geo = \"https://api.ip2location.io\"\n # url_geo = \"https://ipinfo.io/json\"\n # url_geo = \"http://ip-api.com/json\"\n}\nauthor ultrabug, Cyril Levis (@cyrinux)
"},{"location":"user-guide/modules/#whoami","title":"whoami","text":"Display logged-in username.
Configuration parameters:
format display format for this module (default '{username}')Format placeholders:
{hostname} display current hostname
{username} display current username
Inspired by i3 FAQ: https://faq.i3wm.org/question/1618/add-user-name-to-status-bar.1.html
author ultrabug
"},{"location":"user-guide/modules/#wifi","title":"wifi","text":"Display WiFi bit rate, quality, signal and SSID using iw.
Configuration parameters:
bitrate_bad Bad bit rate in Mbit/s (default 26)
bitrate_degraded Degraded bit rate in Mbit/s (default 53)
blocks a string, where each character represents quality level (default \"_\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588\")
cache_timeout Update interval in seconds (default 10)
device specify name or MAC address of device to use, otherwise auto (default None)
down_color Output color when disconnected, possible values: \"good\", \"degraded\", \"bad\" (default \"bad\")
format Display format for this module (default 'W: {bitrate} {bitrate_unit} {signal_percent}% {ssid}|W: down')
signal_bad Bad signal strength in percent (default 29)
signal_degraded Degraded signal strength in percent (default 49)
thresholds specify color thresholds to use (default [])
Format placeholders:
{bitrate} Display bitrate
{bitrate_unit} Display bitrate unit
{device} Display device name
{freq_ghz} Network frequency in Ghz
{freq_mhz} Network frequency in Mhz
{icon} Character representing the quality based on bitrate, as defined by the 'blocks'
{ip} Display IP address
{signal_dbm} Display signal in dBm
{signal_percent} Display signal in percent
{ssid} Display SSID
Color options:
color_bad Signal strength signal_bad or lower
color_degraded Signal strength signal_degraded or lower
color_good Signal strength above signal_degraded
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
iw cli configuration utility for wireless devices
ip only for {ip}. may be part of iproute2: ip routing utilities
Notes: Some distributions require commands to be run with privileges. You can give commands some root rights to run without a password by editing sudoers file, i.e., sudo visudo, and add a line that requires sudo. '<user> ALL=(ALL) NOPASSWD:/sbin/iw dev,/sbin/iw dev [a-z] link' '<user> ALL=(ALL) NOPASSWD:/sbin/ip addr list [a-z]'
author Markus Weimar <mail@markusweimar.de>
license BSD
"},{"location":"user-guide/modules/#window","title":"window","text":"Display window properties (i.e. title, class, instance).
Configuration parameters:
cache_timeout refresh interval for i3-msg or swaymsg (default 0.5)
format display format for this module (default \"{title}\")
hide_title hide title on containers with window title (default False)
max_width specify width to truncate title with ellipsis (default None)
Format placeholders:
{class} window class
{instance} window instance
{title} window title
Requires:
i3ipc an improved python library to control i3wm and swayExamples:
# show alternative instead of empty title\nwindow_title {\n format = '{title}|\u2665'\n}\nauthor shadowprince (counter), Anon1234 (async)
license Eclipse Public License (counter), BSD (async)
"},{"location":"user-guide/modules/#wwan","title":"wwan","text":"Display WWANs, IP addresses, signals, properties and sms.
Configuration parameters:
cache_timeout refresh interval for this module (default 5)
format display format for this module (default '\\?color=state WW: [\\?if=state_name=connected ' '({signal_quality_0}% at {m3gpp_operator_name}) ' '[{format_ipv4}[\\?soft ]{format_ipv6}]|{state_name}]' '[ SMS {messages} [{format_message}]]')
format_ipv4 display format for ipv4 network (default '[{address}]')
format_ipv6 display format for ipv6 network (default '[{address}]')
format_message display format for SMS messages (default '\\?if=index<2 {number} [\\?max_length=10 {text}...]')
format_message_separator show separator if more than one (default ' ')
format_notification specify notification to use (default None)
format_stats display format for statistics (default '{duration_hms}')
modem specify a modem device to use, otherwise auto (default None)
thresholds specify color thresholds to use (default [(0, 'bad'), (11, 'good')])
Format placeholders:
{access_technologies} network speed, in bit, eg 192
{access_technologies_name} network speed names, eg LTE
{current_bands} modem band, eg 1
{current_bands_name} modem band name, eg GSM/GPRS/EDGE 900 MHz
{format_ipv4} format for ipv4 network config
{format_ipv6} format for ipv6 network config
{format_message} format for SMS messages
{format_stats} format for network connection statistics
{interface_name} network interface name, eg wwp0s20f0u2i12
{m3gpp_registration_state_name} network registration state name, eg HOME
{m3gpp_registration_state} network registration state, eg 1
{m3gpp_operator_code} network operator code, eg 496
{m3gpp_operator_name} network operator name, eg Py3status Telecom
{message} number of messages, eg 2
{messages} total number of messages, eg 30
{signal_quality_0} signal quality percentage, eg 88
{signal_quality_1} signal quality refreshed, eg True/False
{state} network state, eg 0, 7, 11
{state_name} network state name, eg searching, connected
format_ipv4 placeholders:
{address} ip address
{dns1} dns1
{dns2} dns2
{gateway} gateway
{mtu} mtu
{prefix} netmask prefix
format_ipv6 placeholders:
{address} ip address
{dns1} dns1
{dns2} dns2
{gateway} gateway
{mtu} mtu
{prefix} netmask prefix
format_message placeholders:
{index} message index
{text} text received, eg: 'hello how are you?'
{number} contact number, eg: '+33601020304'
format_stats placeholders:
{duration} time since connected, in seconds, eg 171
{duration_hms} time since connected, in [hh:]mm:ss, eg 02:51
{tx_bytes} transmit bytes
{rx_bytes} receive bytes
Color thresholds:
format xxx: print a color based on the value of xxx placeholderRequires:
modemmanager mobile broadband modem management service
networkmanager network connection manager and user applications
dbus-python Python bindings for dbus
Examples:
# show state names, eg initializing, searching, registered, connecting.\nwwan {\n format = '\\?color=state WWAN: {state_name}'\n}\n\n# show state names, and when connected, show network information too.\nwwan {\n format = 'WWAN:[\\?color=state [ {format_ipv4}]'\n format += '[ {format_ipv6}] {state_name}]'\n}\n\n# show internet access technologies name with up/down state.\nwwan {\n format = 'WWAN: [\\?color=state [{access_technologies_name}]'\n format += '[\\?soft ][\\?if=state_name=connected up|down]]'\n}\n\n# show SMS messages only\nwwan {\n format = '[SMS: {format_message}]'\n}\n\n# SMS counter\nwwan {\n format = 'SMS: {message}/{messages}'\n}\n\n\n# add starter pack thresholds. you do not need to add them all.\nwwan {\n thresholds = {\n 'access_technologies': [\n (2, 'bad'), (32, 'orange'), (512, 'degraded'), (16384, 'good')\n ],\n 'signal_quality_0': [\n (0, 'bad'), (10, 'orange'), (30, 'degraded'), (50, 'good')\n ],\n 'signal_quality_1': [\n (False, 'darkgrey'), (True, 'degraded')\n ],\n 'state': [\n (-1, 'bad'), (4, 'orange'), (5, 'degraded'), (11, 'good')\n ]\n }\n}\n\n# customize WWAN format\nwwan {\n format = 'WWAN: [\\?color=state {state_name}] '\n format += '[\\?if=m3gpp_registration_state_name=HOME {m3gpp_operator_name} ] '\n format += '[\\?if=m3gpp_registration_state_name=ROAMING {m3gpp_operator_name} ]'\n format += '[\\?color=access_technologies {access_technologies_name} ]'\n format += '[([\\?color=signal_quality_0 {signal_quality_0}]]'\n format += '[\\?if=!signal_quality_1&color=signal_quality_1 \\[!\\]|] '\n format += '[\\?if=state_name=connected [{format_ipv4}] [{format_stats}]]')\n}\n\n# notify users when an event occur... such as new messages, change in state,\n# disconnected, etc. you need to specify formatting correctly so it does not\n# return anything. otherwise, you always get notifications.\nwwan {\n # notify users on low signal percent 25%\n format_notification = '\\?if=signal_quality_0<25 Low signal'\n\n # notify users on connected state\n format_notification = '[\\?if=state_name=connected Connected.]'\n format_notification += '[\\?if=state_name=disconnected Disconnected.]'\n\n # message notification\n format_message = '[\\?if=index=1 [{number}] [{text}]]'\n format_notification = '[\\?if=message>0 {format_message}]'\n}\nauthor Cyril Levis (@cyrinux), girst (https://gir.st/)
"},{"location":"user-guide/modules/#wwan_status","title":"wwan_status","text":"Display network and IP address for newer Huwei modems.
It is tested for Huawei E3276 (usb-id 12d1:1506) aka Telekom Speed Stick LTE III but may work on other devices too.
Configuration parameters:
baudrate There should be no need to configure this, but feel free to experiment. (default 115200)
cache_timeout How often we refresh this module in seconds. (default 5)
consider_3G_degraded If set to True, only 4G-networks will be considered 'good'; 3G connections are shown as 'degraded', which is yellow by default. Mostly useful if you want to keep track of where there is a 4G connection. (default False)
format_down What to display when the modem is not plugged in (default 'WWAN: down')
format_error What to display when modem can't be accessed. (default 'WWAN: {error}')
format_no_service What to display when the modem does not have a network connection. This allows to omit the (then meaningless) network generation. (default 'WWAN: {status} {ip}')
format_up What to display upon regular connection (default 'WWAN: {status} ({netgen}) {ip}')
interface The default interface to obtain the IP address from. For wvdial this is most likely ppp0. For netctl it can be different. (default 'ppp0')
modem The device to send commands to. (default '/dev/ttyUSB1')
modem_timeout The timespan between querying the modem and collecting the response. (default 0.4)
Color options:
color_bad Error or no connection
color_degraded Low generation connection eg 2G
color_good Good connection
Requires:
netifaces portable module to access network interface information
pyserial multiplatform serial port module for python
author Timo Kohorst timo@kohorst-online.com
PGP: B383 6AE6 6B46 5C45 E594 96AB 89D2 209D DBF3 2BB5
"},{"location":"user-guide/modules/#xkb_input","title":"xkb_input","text":"Switch inputs.
Configuration parameters:
button_next mouse button to cycle next layout (default 4)
button_prev mouse button to cycle previous layout (default 5)
cache_timeout refresh interval for this module; xkb-switch and swaymsg will listen for new updates instead (default 10)
format display format for this module (default '{format_input}')
format_input display format for inputs (default '[{alias}][\\?soft ][\\?color=s {s}[ {v}]]')
format_input_separator show separator if more than one (default ' ')
inputs specify a list of inputs to use in swaymsg (default [])
switcher specify xkb-switch, xkblayout-state, xkbgroup, or swaymsg to use, otherwise auto (default None)
thresholds specify color thresholds to use (default [(\"fr\", \"lightgreen\"), (\"ru\", \"lightcoral\"), (\"ua\", \"khaki\"), (\"us\", \"lightskyblue\")])
Format placeholders:
{format_input} format for inputs
{input} number of inputs, eg 1
{switcher} eg, xkb-switch, xkblayout-state, xkbgroup, swaymsg
format_input placeholders:
xkb-switch
xkblayout-state
xkbgroup
swaymsg
{c} layout number, eg, 0
{n} layout name, eg, English (US)
{s} layout symbol, eg, us
{v} layout variant, eg, basic
{e} layout variant, {v} or {s}, eg, dvorak
{C} layout count, eg, 2
swaymsg
{alias} custom string or {name}
{identifier} eg, 162:253 USB-HID Keyboard
{name} eg, Trackball, Keyboard, etc
{vendor} eg, 320
{product} eg, 556
{type} eg, pointer, keyboard, touchpad, etc
{xkb_layout_names} eg, English (US), French, Russian
{xkb_active_layout_index} eg, 0, 1, 2, etc
{xkb_active_layout_name} eg, English (US)
{send_events} eg, True
{accel_speed} eg, 0.0
{accel_profile} eg, adaptive
{natural_scroll} eg, adaptive
{left_handed} eg, False
{middle_emulation} eg, False
{scroll_method} eg, None
{scroll_button} eg, 274
Use `swaymsg -r -t get_inputs` to get a list of current sway inputs\nand for a list of placeholders. Not all of placeholders will be usable.\nColor thresholds:
xxx print a color based on the value of xxx placeholderRequires:
xkb-switch program that allows to query and change the xkb layout state
xkblayout-state a command-line program to get/set the current keyboard layout
xkbgroup query and change xkb layout state
swaymsg send messages to sway window manager
Examples:
# sway users: for best results, add switcher to avoid false positives with `pgrep i3`\n# because sway users can be using scripts, tools, et cetera with `i3` in its name.\nxkb_input {\n switcher = \"swaymsg\"\n}\n\n# sway users: specify inputs to fnmatch\nxkb_input {\n # display logitech identifiers\n inputs = [{\"identifier\": \"*Logitech*\"}]\n\n # display logi* keyboards only\n inputs = [{\"name\": \"Logi*\", \"type\": \"keyb*\"}]\n\n # display pointers only\n inputs = [{\"type\": \"pointer\"}]\n}\n\n# sway users: display inputs, optional aliases, et cetera\nxkb_input {\n inputs = [\n {\"identifier\": \"1625:3192:Heng_Yu_Technology_Poker_II\", \"alias\": \"Poker 2\"},\n {\"identifier\": \"0012:021:USB-HID_Keyboard\", \"alias\": \"Race 3\"},\n {\"identifier\": \"0123:45678:Logitech_MX_Ergo\", \"alias\": \"MX Ergo\", \"type\": \"pointer\"},\n ]\n}\n\n# i3 users: display inputs - see https://wiki.archlinux.org/index.php/X_keyboard_extension\n# $ setxkbmap -layout \"us,fr,ru\" # install xkb-group to enable a listener thread\nauthor lasers, saengowp, javiertury
"},{"location":"user-guide/modules/#xrandr","title":"xrandr","text":"Control screen layout.
This modules allows you to handle your screens outputs directly from your bar! - Detect and propose every possible screen combinations - Switch between combinations using click events and mouse scroll - Activate the screen or screen combination on a single click - It will detect any newly connected or removed screen automatically
For convenience, this module also proposes some added features: - Dynamic parameters for POSITION and WORKSPACES assignment (see below) - Automatic fallback to a given screen or screen combination when no more screen is available (handy for laptops) - Automatically apply this screen combination on start: no need for xorg! - Automatically move workspaces to screens when they are available - Define your own subset of output combinations to use
Configuration parameters:
cache_timeout how often to (re)detect the outputs (default 10)
command a custom command to be run after display configuration changes (default None)
fallback when the current output layout is not available anymore, fallback to this layout if available. This is very handy if you have a laptop and switched to an external screen for presentation and want to automatically fallback to your laptop screen when you disconnect the external screen. (default True)
fixed_width show output as fixed width (default True)
force_on_change switch display layout to the leftmost combination mode of the given list whenever it is available. The combination modes are checked from left (high priority) to right (less priority) until one matches. Example: We have a laptop with internal screen and we are often moving from our desk where another screen is available. We want the layout to follow our changes so that we do not have to switch manually. So whenever we plug at our desk, we want the second monitor to be used, and whenever we go away we want everything back on the laptop screen automatically: force_on_change = [\"eDP1+DP1\", \"eDP1\"] NOTES: Click controls will override force_on_change until the layout changes in the background so you can still manually control your layout changes on the bar. Use the force_on_start to handle initial layout setup on module startup along with this feature to benefit from fully dynamic and automated changes of screen layouts. (default [])
force_on_start switch to the given combination mode if available when the module starts (saves you from having to configure xorg) (default None)
format display format for xrandr (default '{output}')
hide_if_single_combination hide if only one combination is available (default False)
icon_clone icon used to display a 'clone' combination (default '=')
icon_extend icon used to display a 'extend' combination (default '+')
on_udev_drm dynamic variable to watch for drm udev subsystem events to trigger specified action. (default 'refresh_and_freeze')
output_combinations string used to define your own subset of output combinations to use, instead of generating every possible combination automatically. Provide the values in the format that this module uses, splitting the combinations using '|' character. The combinations will be rotated in the exact order as you listed them. When an output layout is not available any more, the configurations are automatically filtered out. Example: Assuming the default values for icon_clone and icon_extend are used, and assuming you have two screens 'eDP1' and 'DP1', the following setup will reduce the number of output combinations from four (every possible one) down to two. output_combinations = \"eDP1|eDP1+DP1\" (default None)
Dynamic configuration parameters:
<OUTPUT>_icon use this icon instead of OUTPUT name as text Example: DP1_icon = \"\ud83d\uddb5\"
<OUTPUT>_pos apply the given position to the OUTPUT Example: DP1_pos = \"-2560x0\" Example: DP1_pos = \"above eDP1\" Example: DP1_pos = \"below eDP1\" Example: DP1_pos = \"left-of LVDS1\" Example: DP1_pos = \"right-of eDP1\"
<OUTPUT>_workspaces comma separated list of workspaces to move to the given OUTPUT when it is activated Example: DP1_workspaces = \"1,2,3\"
<OUTPUT>_rotate rotate the output as told Example: DP1_rotate = \"left\"
<OUTPUT>_mode define the mode (resolution) for the output if not specified use --auto : preferred mode Example: eDP1_mode = \"2560x1440\"
<OUTPUT>_primary apply the primary to the OUTPUT Example: DP1_primary = True
Format placeholders:
{output} xrandr outputColor options:
color_bad Displayed layout unavailable
color_degraded Using a fallback layout
color_good Displayed layout active
Notes: Some days are just bad days. Running xrandr --query command can cause unexplainable brief screen freezes due to an overall combination of computer hardware, installed software, your choice of linux distribution, and/or some other unknown factors such as recent system updates.
Configuring `cache_timeout` with a different number, eg `3600` (an hour)\nor `-1` (runs once) can be used to remedy this issue. See issue #580.\nExamples:
# start with a preferable setup\nxrandr {\n force_on_start = \"eDP1+DP1\"\n DP1_pos = \"left-of eDP1\"\n VGA_workspaces = \"7\"\n}\nauthor ultrabug
"},{"location":"user-guide/modules/#xrandr_rotate","title":"xrandr_rotate","text":"Control screen rotation.
Configuration parameters:
cache_timeout how often to refresh this module. (default 10)
format a string that formats the output, can include placeholders. (default '{icon}')
hide_if_disconnected a boolean flag to hide icon when screen is disconnected. It has no effect unless screen option is also configured. (default False)
horizontal_icon a character to represent horizontal rotation. (default 'H')
horizontal_rotation a horizontal rotation for xrandr to use. Available options: 'normal' or 'inverted'. (default 'normal')
screen display output name to rotate, as detected by xrandr. If not provided, all enabled screens will be rotated. (default None)
vertical_icon a character to represent vertical rotation. (default 'V')
vertical_rotation a vertical rotation for xrandr to use. Available options: 'left' or 'right'. (default 'left')
Format placeholders:
{icon} a rotation icon, specified by horizontal_icon or vertical_icon.
{screen} a screen name, specified by screen option or detected automatically if only one screen is connected, otherwise 'ALL'.
Color options:
color_degraded Screen is disconnected
color_good Displayed rotation is active
author Maxim Baz (https://github.com/maximbaz)
license BSD
"},{"location":"user-guide/modules/#xscreensaver","title":"xscreensaver","text":"Control Xscreensaver.
This script is useful for people who let Xscreensaver manage DPMS settings. Xscreensaver has its own DPMS variables separate from xset. DPMS can be safely turned off in xset as long as Xscreensaver is running. Settings can be managed using \"xscreensaver-demo\".
Configuration parameters:
button_activate mouse button to activate Xscreensaver (default 3)
button_toggle mouse button to toggle Xscreensaver (default 1)
cache_timeout refresh interval for this module (default 15)
format display format for this module (default '{icon}')
icon_off show when Xscreensaver is not running (default 'XSCR')
icon_on show when Xscreensaver is running (default 'XSCR')
Format placeholders:
{icon} Xscreensaver iconColor options:
color_on Enabled, defaults to color_good
color_off Disabled, defaults to color_bad
author neutronst4r, lasers
"},{"location":"user-guide/modules/#xsel","title":"xsel","text":"Display X selection.
Configuration parameters:
cache_timeout refresh interval for this module (default 0.5)
command the clipboard command to run (default 'xsel --output')
format display format for this module (default '{selection}')
log_file specify the clipboard log to use (default None)
max_size strip the selection to this value (default 15)
symmetric show beginning and end of the selection string with respect to configured max_size. (default True)
Format placeholders:
{selection} output from clipboard commandRequires:
xsel a command-line program to retrieve/set the X selectionExamples:
xsel {\n max_size = 50\n command = \"xsel --clipboard --output\"\n on_click 1 = \"exec xsel --clear --clipboard\"\n log_file = \"~/.local/share/xsel/clipboard_log\"\n}\nauthor Sublim3 umbsublime@gamil.com
license BSD
"},{"location":"user-guide/modules/#yandexdisk_status","title":"yandexdisk_status","text":"Display Yandex.Disk status.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default 'Yandex.Disk: {status}')
status_busy show when Yandex.Disk is busy (default None)
status_off show when Yandex.Disk isn't running (default 'Not started')
status_on show when Yandex.Disk is idling (default 'Idle')
Format placeholders:
{status} Yandex.Disk statusColor options:
color_bad Not started
color_degraded Idle
color_good Busy
Requires:
yandex-disk command line interface for Yandex.Diskauthor Vladimir Potapev (github:vpotapev)
license BSD
"},{"location":"user-guide/modules/#yubikey","title":"yubikey","text":"Show an indicator when YubiKey is waiting for a touch.
Configuration parameters:
format Display format for the module. (default '[YubiKey[\\?if=is_gpg ][\\?if=is_u2f ]]')
socket_path A path to the yubikey-touch-detector socket file. (default '$XDG_RUNTIME_DIR/yubikey-touch-detector.socket')
Control placeholders:
{is_gpg} a boolean, True if YubiKey is waiting for a touch due to a gpg operation.
{is_u2f} a boolean, True if YubiKey is waiting for a touch due to a pam-u2f request.
Requires:
github.com/maximbaz/yubikey-touch-detector tool to detect when YubiKey is waiting for a touchauthor Maxim Baz (https://github.com/maximbaz)
license BSD
"},{"location":"user-guide/modules/#zypper_updates","title":"zypper_updates","text":"Display number of pending updates for OpenSUSE Linux.
Configuration parameters:
cache_timeout How often we refresh this module in seconds (default 600)
format Display format to use (default 'zypper: [\\?color=update {update}]')
thresholds specify color thresholds to use (default [(0, 'good'), (50, 'degraded'), (100, 'bad')])
Format placeholders:
{updates} number of pending zypper updatesColor thresholds:
xxx print a color based on the value of xxx placeholderauthor Ioannis Bonatakis <ybonatakis@suse.com>
license BSD
"},{"location":"user-guide/remote-control/","title":"Controlling py3status remotely","text":"Just like i3status, you can force an update of your i3bar by sending a SIGUSR1 signal to py3status. Note that this will also send a SIGUSR1 signal to i3status.
$ killall -USR1 py3status\npy3status can be controlled remotely via the py3-cmd cli utility.
This utility allows you to run a number of commands.
# button numbers\n1 = left click\n2 = middle click\n3 = right click\n4 = scroll up\n5 = scroll down\nSend a click event to a module as though it had been clicked on. You can specify the button to simulate.
# send a left/middle/right click\n$ py3-cmd click --button 1 dpms # left\n$ py3-cmd click --button 2 sysdata # middle\n$ py3-cmd click --button 3 pomodoro # right\n\n# send a up/down click\n$ py3-cmd click --button 4 volume_status # up\n$ py3-cmd click --button 5 volume_status # down\n# toggle button in frame module\n$ py3-cmd click --button 1 --index button frame # left\n\n# change modules in group module\n$ py3-cmd click --button 5 --index button group # down\n\n# change time units in timer module\n$ py3-cmd click --button 4 --index hours timer # up\n$ py3-cmd click --button 4 --index minutes timer # up\n$ py3-cmd click --button 4 --index seconds timer # up\nPrint a list of modules or module docstrings.
# list one or more modules\n$ py3-cmd list clock loadavg xrandr # full\n$ py3-cmd list coin* git* window* # fnmatch\n$ py3-cmd list [a-e]* # abcde\n\n# list all modules\n$ py3-cmd list --all\n\n# show full (i.e. docstrings)\n$ py3-cmd list vnstat uname -f\nCause named module(s) to have their output refreshed.
# refresh all instances of the wifi module\n$ py3-cmd refresh wifi\n\n# refresh multiple modules\n$ py3-cmd refresh coin_market github weather_yahoo\n\n# refresh module with instance name\n$ py3-cmd refresh \"weather_yahoo chicago\"\n\n# refresh all modules\n$ py3-cmd refresh --all\npy3-cmd can be used in your i3 configuration file.
To send a click event to the whatismyip module when Mod+x is pressed
bindsym $mod+x exec py3-cmd click whatismyip\nThis example shows how volume control keys can be bound to change the volume and then cause the volume_status module to be updated.
bindsym XF86AudioRaiseVolume exec \"amixer -q sset Master 5%+ unmute; py3-cmd refresh volume_status\"\nbindsym XF86AudioLowerVolume exec \"amixer -q sset Master 5%- unmute; py3-cmd refresh volume_status\"\nbindsym XF86AudioMute exec \"amixer -q sset Master toggle; py3-cmd refresh volume_status\"\nHere you can find community contributed configuration examples to help you get started with some modules or benefit from the tricks of other hackers!
"},{"location":"user-guide/user-contributed-conf-examples/#ultrabugs-configuration-examples","title":"Ultrabug's configuration examples","text":"# one button for bluetooth on/off\nbluetooth {\n format = \"\uf519\"\n on_click 1 = \"exec bluetoothctl power on\"\n on_click 3 = \"exec bluetoothctl power off\"\n}\n\n# I use pulseausio and I like to control the sinks and sources \n# directly from my bar!\n#\n# These modules allow me to not only control the volume of the given\n# devices but to also switch the sound output from one to another\n\n# This is the speakers from my laptop, I can switch sound to it\n# on middle click\nvolume_status speakers {\n command = \"pactl\"\n device = \"alsa_output.pci-0000_00_1f.3.analog-stereo\"\n format = \"\ud83d\udcbb{percentage}%\"\n format_muted = \"\ud83d\udcbb{percentage}%\"\n on_click 2 = \"exec pactl set-default-sink alsa_output.pci-0000_00_1f.3.analog-stereo\"\n thresholds = [(0, 'bad'), (5, 'degraded'), (10, 'good')]\n}\n\n# I plugin a USB headset, it appears, I can switch default sound to\n# it while controlling its volume output. When disconnected, it\n# disappears from the bar\nvolume_status sennheiser {\n command = \"pactl\"\n device = \"alsa_output.usb-Sennheiser_\"\n format = \"[\\?if=!percentage=? \ud83c\udfa7{percentage}%]\"\n format_muted = '\ud83c\udfa7{percentage}%'\n on_click 2 = \"exec pactl set-default-sink alsa_output.usb-Sennheiser_Sennheiser_SC_160_USB_A002430203100377-00.analog-stereo\"\n thresholds = [(0, 'bad'), (5, 'degraded'), (10, 'good')]\n}\n\n# I also can activate a remote bluetooth speaker by clicking on this,\n# when it connects the sound percentage appears, I can switch output\n# to it by middle clicking or disconnect it by right clicking\nvolume_status bose {\n command = \"pactl\"\n device = \"bluez_sink..+.a2dp_sink\"\n format = \"[\\?if=!percentage=? \ud83d\udcfb{percentage}%][\\?if=percentage=? \ud83d\udcfb]\"\n format_muted = '\ud83d\udcfb{percentage}%'\n on_click 2 = \"exec pactl set-default-sink bluez_sink.2C_41_A1_Z7_FA_C2.a2dp_sink\"\n on_click 1 = \"exec bluetoothctl connect 2C:41:A1:Z7:FA:C2\"\n on_click 3 = \"exec bluetoothctl disconnect 2C:41:A1:Z7:FA:C2\"\n thresholds = [(0, 'bad'), (5, 'degraded'), (10, 'good')]\n max_volume = 200\n}\n\n# I also control the default microphone volume from the bar\n# and can mute it\nvolume_status mic {\n format = '\ud83c\udf99\ufe0f{percentage}%'\n format_muted = '\ud83c\udf99\ufe0f{percentage}%'\n button_down = 5\n button_mute = 1\n button_up = 4\n is_input = true\n thresholds = [(0, 'bad'), (10, 'degraded'), (20, 'good')]\n}\n\n# DMPS status shows as a red/green screen\ndpms {\n icon_off = \"\uf108\"\n icon_on = \"\uf108\"\n}\n\n# cycling time in meaningful cities\ngroup tz {\n cycle = 10\n format = \"{output}\"\n #click_mode = \"button\"\n\n tztime la {\n format = \"\ud83c\udf09%H:%M\"\n timezone = \"America/Los_Angeles\"\n }\n\n tztime ny {\n format = \"\ud83d\uddfd%H:%M\"\n timezone = \"America/New_York\"\n }\n\n tztime du {\n format = \"\ud83d\udd4c%H:%M\"\n timezone = \"Asia/Dubai\"\n }\n\n tztime tw {\n format = \"\u26e9\ufe0f%H:%M\"\n timezone = \"Asia/Taipei\"\n }\n\n tztime in {\n format = \"\ud83d\uded5%H:%M\"\n timezone = \"Asia/Kolkata\"\n }\n}\n# If I had time, I would make these proper modules. Free feel to make them\n# if you got time.\n\n# weather without needing an API key\ngetjson wttr {\n url = \"https://wttr.in/Paris?format=j1\"\n format = \"{current_condition-0-FeelsLikeC}\u00b0 {current_condition-0-weatherDesc-0-value}\"\n cache_timeout = 3600\n}\n\n# example output\n# 6\u00b0 Partly cloudy\n\n# SABnzbd status\ngetjson sabnzbd {\n url = \"https://sabnzbd.example.com/api?mode=queue&apikey=000000000&output=json\"\n format = \"SABnzbd: {queue-status}\"\n cache_timeout = 60\n}\n# example output\n# SABnzbd: Idle\nUsing py3status, you can take control of your i3bar easily by:
No extra configuration file needed, just install & enjoy!
"},{"location":"#about","title":"About","text":"You will love py3status if you're using i3wm (or sway) and are frustrated by the i3status limitations on your i3bar such as:
We apply the zen to improve this project and encourage everyone to read it!
"},{"location":"#need-help","title":"Need help?","text":"Get help, share ideas or feedback, join community, report bugs, or others, see:
"},{"location":"#github","title":"GitHub","text":"Join us on #py3status at oftc.net
"},{"location":"getting-started/","title":"Getting Started","text":"Install py3status then in your i3 config file, simply switch from i3status to py3status in your status_command option:
status_command py3status\nUsually you have your own i3status configuration, just point to it:
status_command py3status -c ~/.config/i3status/config\nYou can get a list with short descriptions of all available modules by using the CLI:
$ py3-cmd list --all\nTo get more details about all available modules and their configuration, use:
$ py3-cmd list --all --full\nAll modules shipped with py3status are present as the Python source files in the py3status/modules directory.
Check out the py3status user configuration guide to learn how to add, order and configure modules!
"},{"location":"getting-started/#py3status-options","title":"Py3status options","text":"You can see the help of py3status by issuing py3status --help:
$ py3status --help\n\nusage: py3status [-h] [-b] [-c FILE] [-d] [-g] [-i PATH] [-l FILE] [-s]\n [-t INT] [-m] [-u PATH] [-v] [--wm WINDOW_MANAGER]\n\nThe agile, python-powered, i3status wrapper\n\noptional arguments:\n -h, --help show this help message and exit\n -b, --dbus-notify send notifications via dbus instead of i3-nagbar\n (default: False)\n -c, --config FILE load config (default: /home/alexys/.i3/i3status.conf)\n -d, --debug enable debug logging in syslog and --log-file\n (default: False)\n -i, --include PATH append additional user-defined module paths (default:\n None)\n -l, --log-file FILE enable logging to FILE (default: None)\n -s, --standalone run py3status without i3status (default: False)\n -t, --timeout INT default module cache timeout in seconds (default: 60)\n -m, --disable-click-events\n disable all click events (default: False)\n -u, --i3status PATH specify i3status path (default: /usr/bin/i3status)\n -v, --version show py3status version and exit (default: False)\n --wm WINDOW_MANAGER specify window manager i3 or sway (default: i3)\nPy3status is very open and flexible, check out the complete user guide to get more intimate with it:
Contributions to py3status including documentation, the core code, or for new or existing modules are very welcome.
Please read carefully the zen describing the minimal things to keep in mind when contributing or participating to this project.
Feel free to open an issue to propose your ideas as request for comments [RFC] and to join us on IRC OFTC #py3status channel for a live chat.
To make a contribution please create a pull request.
Any functional change should be done via pull requests, even by people with push access.
Each PR requires at least one approval from project maintainers before a PR can be merged.
"},{"location":"dev-guide/contributing/#zen-of-py3status","title":"Zen of py3status","text":""},{"location":"dev-guide/contributing/#efficient-and-simple-defaults","title":"efficient and simple defaults","text":"We like py3status because it's a drop-in replacement of i3status. i3 users don't expect fancy and magical things, they use i3 because it's simple and efficient. Keep configuration options and default formats as simple as possible
"},{"location":"dev-guide/contributing/#its-not-because-you-can-that-you-should","title":"it's not because you can that you should","text":"On modules, expose things that you WILL use, not things that you COULD use. On core, make features and options as seamless as possible (lazy loading) with sane defaults and no mandatory requirements.
"},{"location":"dev-guide/contributing/#good-enough-is-good-enough","title":"good enough is good enough","text":"Strive for and accept \"good enough\" features / proposals. We shall refrain from refining indefinitely.
"},{"location":"dev-guide/contributing/#one-featureidea-at-a-time","title":"one feature/idea at a time","text":"Trust and foster iteration with your peers by refraining from digressions. Keep discussions focused on the initial topic and easy to get into. Proposals should not contain multiple features or corrections at once.
"},{"location":"dev-guide/contributing/#modules-are-responsible-for-user-information-and-interactions","title":"modules are responsible for user information and interactions","text":"That is what's written in the bar and its behavior on clicks etc.
"},{"location":"dev-guide/contributing/#core-is-responsible-for-user-experience","title":"core is responsible for user experience","text":"Core features and configuration options should focus on user experience. Things that are related to the general output of the bar are handled by core. Smart things overlaying modules (such as standardized options) should also end up in the core.
"},{"location":"dev-guide/contributing/#rely-on-i3status-color-scheme","title":"rely on i3status color scheme","text":"No fancy colors by default, only i3status good/degraded/bad. If we want to provide enhanced coloring, this should be through a core feature such as thresholds.
"},{"location":"dev-guide/contributing/#rely-on-the-i3bar-protocol","title":"rely on the i3bar protocol","text":"what's possible with it, we should support and offer.
"},{"location":"dev-guide/contributing/#what-you-will-need","title":"What you will need","text":"i3status:
pytest pytest-flake8:
black:
tox:
First clone the git repository
# using https\n$ git clone https://github.com/ultrabug/py3status.git\n\n# using ssh (needs github account)\n$ git clone git@github.com:ultrabug/py3status.git\nRun setup.py to install
# cd to the directory containing setup.py\n$ cd py3status\n\n# install you may need to use sudo to have required permissions\n$ pip install -e .\nyou can now run py3status and any changes to the code you make will be available after a reload.
Note
py3status will only be installed for the version of python that you used to run setup.py.
If you wish to have multiple versions available. First run setup.py develop using the required python versions. Next copy the executable eg sudo cp /usr/bin/py3status /usr/bin/py3status2 Then edit the hashbang to point to your chosen python version.
Starting with version 3.26, py3status will only run using python 3.
"},{"location":"dev-guide/contributing/#documentation","title":"Documentation","text":"Documentation pages are located under the docs/ folder.
To run the documentation site locally (useful for previewing changes), use:
# you need to install hatch\n# pip install --user hatch\nhatch -e docs mkdocs serve\nPy3status uses tox for testing. All submissions to the project must pass testing. To install these via pip use
$ pip install pytest\n$ pip install pytest-flake8\n$ pip install tox\n$ pip install black # needs python 3.6+\nThe tests can be run by using tox in the py3status root directory.
Tests are kept in the tests directory.
When you create your Pull Request, checks from the Github Actions CI will automatically run.
If something fails in the CI:
Warning, by default (at least on Archlinux), i3status has cap_net_admin capabilities, which will make it fail with operation not permitted when running inside a Docker container.
$ getcap `which i3status`\n/usr/sbin/i3status = cap_net_admin+ep\nTo allow it to run without these capabilities (hence disabling some of the functionalities), remove it with:
$ sudo setcap -r `which i3status`\nA small tool to measure py3status performance between changes and allows testing of old versions, etc. It's a little clunky but it does the job. https://github.com/tobes/py3status-profiler
# pprofile\nRunning tests for 10 minutes.\n[\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588] 100.00% 10:00 (22.12)\nuser 21.41s\nsystem 0.71s\ntotal 22.12s\n\n# vmprof\nRunning tests for 10 minutes.\n[\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588] 100.00% 10:00 (2.10)\nuser 1.77s\nsystem 0.33s\ntotal 2.1s\n\n# cprofile\nRunning tests for 10 minutes.\n[\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588] 100.00% 10:00 (0.92)\nuser 0.87s\nsystem 0.05s\ntotal 0.92\nThe Py3 module is a special helper object that gets injected into py3status modules, providing extra functionality. A module can access it via the self.py3 instance attribute of its py3status class.
Special constant that when returned for cached_until will cause the module to not update unless externally triggered.
Show as Error
"},{"location":"dev-guide/the-py3-helper/#log_info","title":"LOG_INFO","text":"Show as Informational
"},{"location":"dev-guide/the-py3-helper/#log_warning","title":"LOG_WARNING","text":"Show as Warning
"},{"location":"dev-guide/the-py3-helper/#exceptions","title":"Exceptions","text":""},{"location":"dev-guide/the-py3-helper/#commanderror","title":"CommandError","text":"An error occurred running the given command.
This exception provides some additional attributes
error_code: The error code returned from the call
output: Any output returned by the call
error: Any error output returned by the call
Base Py3 exception class. All custom Py3 exceptions derive from this class.
"},{"location":"dev-guide/the-py3-helper/#requestexception","title":"RequestException","text":"A Py3.request() base exception. This will catch any of the more specific exceptions.
"},{"location":"dev-guide/the-py3-helper/#requestinvalidjson","title":"RequestInvalidJSON","text":"The request has not returned valid JSON
"},{"location":"dev-guide/the-py3-helper/#requesttimeout","title":"RequestTimeout","text":"A timeout has occurred during a request made via Py3.request().
"},{"location":"dev-guide/the-py3-helper/#requesturlerror","title":"RequestURLError","text":"A URL related error has occurred during a request made via Py3.request().
"},{"location":"dev-guide/the-py3-helper/#methods","title":"Methods","text":""},{"location":"dev-guide/the-py3-helper/#check_commandscmd_list","title":"check_commands(cmd_list)","text":"Checks to see if commands in list are available using shutil.which().
returns the first available command.
If a string is passed then that command will be checked for.
"},{"location":"dev-guide/the-py3-helper/#command_outputcommand-shellfalse-capture_stderrfalse-localizedfalse","title":"command_output(command, shell=False, capture_stderr=False, localized=False)","text":"Run a command and return its output as unicode. The command can either be supplied as a sequence or string.
:param command: command to run can be a str or list :param shell: if True then command is run through the shell :param capture_stderr: if True then STDERR is piped to STDOUT :param localized: if False then command is forced to use its default (English) locale
A CommandError is raised if an error occurs
"},{"location":"dev-guide/the-py3-helper/#command_runcommand","title":"command_run(command)","text":"Runs a command and returns the exit code. The command can either be supplied as a sequence or string.
An Exception is raised if an error occurs
"},{"location":"dev-guide/the-py3-helper/#composite_createitem","title":"composite_create(item)","text":"Create and return a Composite.
The item may be a string, dict, list of dicts or a Composite.
"},{"location":"dev-guide/the-py3-helper/#composite_joinseparator-items","title":"composite_join(separator, items)","text":"Join a list of items with a separator. This is used in joining strings, responses and Composites.
A Composite object will be returned.
"},{"location":"dev-guide/the-py3-helper/#composite_updateitem-update_dict-softfalse","title":"composite_update(item, update_dict, soft=False)","text":"Takes a Composite (item) if item is a type that can be converted into a Composite then this is done automatically. Updates all entries it the Composite with values from update_dict. Updates can be soft in which case existing values are not overwritten.
A Composite object will be returned.
"},{"location":"dev-guide/the-py3-helper/#errormsg-timeoutnone","title":"error(msg, timeout=None)","text":"Raise an error for the module.
:param msg: message to be displayed explaining the error :param timeout: how long before we should retry. For permanent errors py3.CACHE_FOREVER should be returned. If not supplied then the modules cache_timeout will be used.
Flatten a dictionary.
Values that are dictionaries are flattened using delimiter in between (eg. parent-child)
Values that are lists are flattened using delimiter followed by the index (eg. parent-0)
example:
{\n 'fish_facts': {\n 'sharks': 'Most will drown if they stop moving',\n 'skates': 'More than 200 species',\n },\n 'fruits': ['apple', 'peach', 'watermelon'],\n 'number': 52\n}\n\n# becomes\n\n{\n 'fish_facts-sharks': 'Most will drown if they stop moving',\n 'fish_facts-skates': 'More than 200 species',\n 'fruits-0': 'apple',\n 'fruits-1': 'peach',\n 'fruits-2': 'watermelon',\n 'number': 52\n}\n\n# if intermediates is True then we also get unflattened elements\n# as well as the flattened ones.\n\n{\n 'fish_facts': {\n 'sharks': 'Most will drown if they stop moving',\n 'skates': 'More than 200 species',\n },\n 'fish_facts-sharks': 'Most will drown if they stop moving',\n 'fish_facts-skates': 'More than 200 species',\n 'fruits': ['apple', 'peach', 'watermelon'],\n 'fruits-0': 'apple',\n 'fruits-1': 'peach',\n 'fruits-2': 'watermelon',\n 'number': 52\n}\nDetermines if format_string contains a placeholder string names or a list of placeholders names.
names is tested against placeholders using fnmatch so the following patterns can be used:
* matches everything\n? matches any single character\n[seq] matches any character in seq\n[!seq] matches any character not in seq\nThis is useful because a simple test like '{placeholder}' in format_string will fail if the format string contains placeholder formatting eg '{placeholder:.2f}'
Takes a value and formats it for user output, we can choose the unit to use eg B, MiB, kbits/second. This is mainly for use with bytes/bits it converts the value into a human readable form. It has various additional options but they are really only for special cases.
The function returns a tuple containing the new value (this is a number so that the user can still format it if required) and a unit that is the units that we have been converted to.
By supplying unit to the function we can force those units to be used eg unit=KiB would force the output to be in Kibibytes. By default we use non-si units but if the unit is si eg kB then we will switch to si units. Units can also be things like Mbit/sec.
If the auto parameter is False then we use the unit provided. This only makes sense when the unit is singular eg 'Bytes' and we want the result in bytes and not say converted to MBytes.
optimal is used to control the size of the output value. We try to provide an output value of that number of characters (including decimal point), it may also be less due to rounding. If a fixed unit is used the output may be more than this number of characters.
"},{"location":"dev-guide/the-py3-helper/#get_color_names_listformat_string-matchesnone","title":"get_color_names_list(format_string, matches=None)","text":"Returns a list of color names in format_string.
If matches is provided then it is used to filter the result using fnmatch so the following patterns can be used:
* matches everything\n? matches any single character\n[seq] matches any character in seq\n[!seq] matches any character not in seq\nReturn a string from a Composite.
"},{"location":"dev-guide/the-py3-helper/#get_outputmodule_name","title":"get_output(module_name)","text":"Return the output of the named module. This will be a list.
"},{"location":"dev-guide/the-py3-helper/#get_placeholder_formats_listformat_string","title":"get_placeholder_formats_list(format_string)","text":"Parses the format_string and returns a list of tuples [(placeholder, format), ...].
eg '{placeholder:.2f}' will give [('placeholder', ':.2f')]
Returns a list of placeholders in format_string.
If matches is provided then it is used to filter the result using fnmatch so the following patterns can be used:
* matches everything\n? matches any single character\n[seq] matches any character in seq\n[!seq] matches any character not in seq\nThis is useful because we just get simple placeholder without any formatting that may be applied to them eg '{placeholder:.2f}' will give ['{placeholder}']
Return the control program of the current window manager.
On i3, will return \"i3-msg\" On sway, will return \"swaymsg\"
"},{"location":"dev-guide/the-py3-helper/#i3s_config","title":"i3s_config()","text":"returns the i3s_config dict.
"},{"location":"dev-guide/the-py3-helper/#is_colorcolor","title":"is_color(color)","text":"Tests to see if a color is defined. Because colors can be set to None in the config and we want this to be respected in an expression like.
color = self.py3.COLOR_MUTED or self.py3.COLOR_BAD\nThe color is treated as True but sometimes we want to know if the color has a value set in which case the color should count as False. This function is a helper for this second case.
"},{"location":"dev-guide/the-py3-helper/#is_compositeitem","title":"is_composite(item)","text":"Check if item is a Composite and return True if it is.
"},{"location":"dev-guide/the-py3-helper/#is_my_eventevent","title":"is_my_event(event)","text":"Checks if an event triggered belongs to the module receiving it. This is mainly for containers who will also receive events from any children they have.
Returns True if the event name and instance match that of the module checking.
"},{"location":"dev-guide/the-py3-helper/#logmessage-levelinfo","title":"log(message, level='info')","text":"Log the message. The level must be one of LOG_ERROR, LOG_INFO or LOG_WARNING
"},{"location":"dev-guide/the-py3-helper/#notify_usermsg-levelinfo-rate_limit5-titlenone-iconnone","title":"notify_user(msg, level='info', rate_limit=5, title=None, icon=None)","text":"Send a notification to the user. level must be 'info', 'error' or 'warning'. rate_limit is the time period in seconds during which this message should not be repeated. icon must be an icon path or icon name.
"},{"location":"dev-guide/the-py3-helper/#play_soundsound_file","title":"play_sound(sound_file)","text":"Plays sound_file if possible.
"},{"location":"dev-guide/the-py3-helper/#prevent_refresh","title":"prevent_refresh()","text":"Calling this function during the on_click() method of a module will request that the module is not refreshed after the event. By default the module is updated after the on_click event has been processed.
"},{"location":"dev-guide/the-py3-helper/#register_functionfunction_name-function","title":"register_function(function_name, function)","text":"Register a function for the module.
The following functions can be registered:
"},{"location":"dev-guide/the-py3-helper/#content_function","title":"content_function()","text":"Called to discover what modules a container is displaying. This is used to determine when updates need passing on to the container and also when modules can be put to sleep.
the function must return a set of module names that are being displayed.
Note
This function should only be used by containers.
"},{"location":"dev-guide/the-py3-helper/#urgent_functionmodule_names","title":"urgent_function(module_names)","text":"This function will be called when one of the contents of a container has changed from a non-urgent to an urgent state. It is used by the group module to switch to displaying the urgent module.
module_names is a list of modules that have become urgent
Note
This function should only be used by containers.
"},{"location":"dev-guide/the-py3-helper/#requesturl-paramsnone-datanone-headersnone-timeoutnone-authnone-cookiejarnone-retry_timesnone-retry_waitnone","title":"request(url, params=None, data=None, headers=None, timeout=None, auth=None, cookiejar=None, retry_times=None, retry_wait=None)","text":"Make a request to a url and retrieve the results.
If the headers parameter does not provide an 'User-Agent' key, one will be added automatically following the convention:
py3status/<version> <per session random uuid>\nhttp://example.com(username, password)returns: HttpResponse
"},{"location":"dev-guide/the-py3-helper/#safe_formatformat_string-param_dictnone-force_compositefalse-attr_getternone-max_widthnone","title":"safe_format(format_string, param_dict=None, force_composite=False, attr_getter=None, max_width=None)","text":"Parser for advanced formatting.
Unknown placeholders will be shown in the output eg {foo}.
Square brackets [] can be used. The content of them will be removed from the output if there is no valid placeholder contained within. They can also be nested.
A pipe (vertical bar) | can be used to divide sections the first valid section only will be shown in the output.
A backslash \\ can be used to escape a character eg \\[ will show [ in the output.
\\? is special and is used to provide extra commands to the format string, example \\?color=#FF00FF. Multiple commands can be given using an ampersand & as a separator, example \\?color=#FF00FF&show.
\\?if=<placeholder> can be used to check if a placeholder exists. An exclamation mark ! after the equals sign = can be used to negate the condition.
\\?if=<placeholder>=<value> can be used to determine if {} would be replaced with . [] in don't need to be escaped.
{<placeholder>} will be converted, or removed if it is None or empty. Formatting can also be applied to the placeholder Eg {number:03.2f}.
example format_string:
\"[[{artist} - ]{title}]|{file}\" This will show artist - title if artist is present, title if title but no artist, and file if file is present but not artist or title.
param_dict is a dictionary of placeholders that will be substituted. If a placeholder is not in the dictionary then if the py3status module has an attribute with the same name then it will be used.
Composites can be included in the param_dict.
The result returned from this function can either be a string in the case of simple parsing or a Composite if more complex.
If force_composite parameter is True a composite will always be returned.
attr_getter is a function that will when called with an attribute name as a parameter will return a value.
max_width lets you to control the total max width of 'full_text' the module is allowed to output on the bar.
"},{"location":"dev-guide/the-py3-helper/#stop_sound","title":"stop_sound()","text":"Stops any currently playing sounds for this module.
"},{"location":"dev-guide/the-py3-helper/#storage_delkeynone","title":"storage_del(key=None)","text":"Remove the value stored with the key from storage. If key is not supplied then all values for the module are removed.
"},{"location":"dev-guide/the-py3-helper/#storage_getkey","title":"storage_get(key)","text":"Retrieve a value for the module.
"},{"location":"dev-guide/the-py3-helper/#storage_items","title":"storage_items()","text":"Return key, value pairs of the stored data for the module.
Keys will contain the following metadata entries: - '_ctime': storage creation timestamp - '_mtime': storage last modification timestamp
"},{"location":"dev-guide/the-py3-helper/#storage_keys","title":"storage_keys()","text":"Return a list of the keys for values stored for the module.
Keys will contain the following metadata entries: - '_ctime': storage creation timestamp - '_mtime': storage last modification timestamp
"},{"location":"dev-guide/the-py3-helper/#storage_setkey-value","title":"storage_set(key, value)","text":"Store a value for the module.
"},{"location":"dev-guide/the-py3-helper/#threshold_get_colorvalue-namenone","title":"threshold_get_color(value, name=None)","text":"Obtain color for a value using thresholds.
The value will be checked against any defined thresholds. These should have been set in the i3status configuration. If more than one threshold is needed for a module then the name can also be supplied. If the user has not supplied a named threshold but has defined a general one that will be used.
If the gradients config parameter is True then rather than sharp thresholds we will use a gradient between the color values.
Returns the time a given number of seconds into the future. Helpful for creating the cached_until value for the module output.
Note
from version 3.1 modules no longer need to explicitly set a cached_until in their response unless they wish to directly control it.
seconds: specifies the number of seconds that should occur before the update is required. Passing a value of CACHE_FOREVER returns CACHE_FOREVER which can be useful for some modules.
sync_to: causes the update to be synchronized to a time period. 1 would cause the update on the second, 60 to the nearest minute. By default we synchronize to the nearest second. 0 will disable this feature.
offset: is used to alter the base time used. A timer that started at a certain time could set that as the offset and any synchronization would then be relative to that time.
Trigger an event on a named module.
"},{"location":"dev-guide/the-py3-helper/#updatemodule_namenone","title":"update(module_name=None)","text":"Update a module. If module_name is supplied the module of that name is updated. Otherwise the module calling is updated.
"},{"location":"dev-guide/the-py3-helper/#update_placeholder_formatsformat_string-formats","title":"update_placeholder_formats(format_string, formats)","text":"Update a format string adding formats if they are not already present. This is useful when for example a placeholder has a floating point value but by default we only want to show it to a certain precision.
"},{"location":"dev-guide/writing-modules/","title":"Writing custom py3status modules","text":"Writing custom modules for py3status is as easy as declaring a Python class. This guide will teach you how.
"},{"location":"dev-guide/writing-modules/#importing-custom-modules","title":"Importing custom modules","text":"First of all, it is important to know that py3status will try to find your custom modules in the following locations:
~/.config/py3status/modules~/.config/i3status/py3status~/.config/i3/py3status~/.i3/py3statuswhich if you are used to XDG_CONFIG paths relates to:
XDG_CONFIG_HOME/py3status/modulesXDG_CONFIG_HOME/i3status/py3statusXDG_CONFIG_HOME/i3/py3status~/.i3/py3statusYou can also specify the modules location using py3status -i <path to custom modules directory> in your i3 configuration file.
Now let's start by looking at a simple example.
Here we start with the most basic module that just outputs a static string to the status bar.
# -*- coding: utf-8 -*-\n\"\"\"\nExample module that says 'Hello World!'\n\nThis demonstrates how to produce a simple custom module.\n\"\"\"\n\n\nclass Py3status:\n\n def hello_world(self):\n return {\n 'full_text': 'Hello World!',\n 'cached_until': self.py3.CACHE_FOREVER\n }\nSave the file as hello_world.py in a directory that py3status will check for modules. By default it will look in $HOME/.i3/py3status/ or you can specify additional directories using --include when you run py3status.
You need to tell py3status about your new module, so in your i3status.conf add:
order += \"hello_world\"\nThen restart i3 by pressing Mod + Shift + R. Your new module should now show up in the status bar.
The Py3status class tells py3status that this is a module. The module gets loaded. py3status then calls any public methods that the class contains to get a response. In our example there is a single method hello_world(). Read more here: module methods.
The response that a method returns must be a python dict. It should contain at least two key / values.
This is the text that will be displayed in the status bar.
"},{"location":"dev-guide/writing-modules/#cached_until","title":"cached_until","text":"This tells py3status how long it should consider your response valid before it should re-run the method to get a fresh response. In our example our response will not need to be updated so we can use the special self.py3.CACHE_FOREVER constant. This tells py3status to consider our response always valid.
cached_until should be generated via the self.py3.time_in() method.
This is a special object that gets injected into py3status modules. It helps provide functionality for the module, such as the CACHE_FOREVER constant. Read more about the py3.
Allow users to supply configuration to a module.
# -*- coding: utf-8 -*-\n\"\"\"\nExample module that says 'Hello World!' that can be customised.\n\nThis demonstrates how to use configuration parameters.\n\nConfiguration parameters:\n format: Display format (default 'Hello World!')\n\"\"\"\n\n\nclass Py3status:\n\n format = 'Hello World!'\n\n def hello_world(self):\n return {\n 'full_text': self.format,\n 'cached_until': self.py3.CACHE_FOREVER\n }\nThis module still outputs 'Hello World' as before but now you can customise the output using your i3status.config for example to show the text in French.
hello_world {\n format = 'Bonjour tout le monde!'\n}\nIn your module self.format will have been set to the value supplied in the config.
Catch click events and perform an action.
# -*- coding: utf-8 -*-\n\"\"\"\nExample module that handles events\n\nThis demonstrates how to use events.\n\"\"\"\n\n\nclass Py3status:\n\n def __init__(self):\n self.full_text = 'Click me'\n\n def click_info(self):\n return {\n 'full_text': self.full_text,\n 'cached_until': self.py3.CACHE_FOREVER\n }\n\n def on_click(self, event):\n \"\"\"\n event will be a dict like\n {'y': 13, 'x': 1737, 'button': 1, 'name': 'example', 'instance': 'first'}\n \"\"\"\n button = event['button']\n # update our output (self.full_text)\n format_string = 'You pressed button {button}'\n data = {'button': button}\n self.full_text = self.py3.safe_format(format_string, data)\n # Our modules update methods will get called automatically.\nThe on_click method of a module is special and will get called when the module is clicked on. The event parameter will be a dict that gives information about the event.
A typical event dict will look like this: {'y': 13, 'x': 1737, 'button': 1, 'name': 'example', 'instance': 'first'}
You should only receive events for the module clicked on, so generally we only care about the button.
The __init__() method is called when our class is instantiated.
Note
init is called before any config parameters have been set.
We use the safe_format() method of py3 for formatting. Read more about the py3.
Status string placeholders allow us to add information to formats.
# -*- coding: utf-8 -*-\n\"\"\"\nExample module that demonstrates status string placeholders\n\nConfiguration parameters:\n format: Initial format to use\n (default 'Click me')\n format_clicked: Display format to use when we are clicked\n (default 'You pressed button {button}')\n\nFormat placeholders:\n {button} The button that was pressed\n\"\"\"\n\n\nclass Py3status:\n format = 'Click me'\n format_clicked = 'You pressed button {button}'\n\n def __init__(self):\n self.button = None\n\n def click_info(self):\n if self.button:\n data = {'button': self.button}\n full_text = self.py3.safe_format(self.format_clicked, data)\n else:\n full_text = self.format\n\n return {\n 'full_text': full_text,\n 'cached_until': self.py3.CACHE_FOREVER\n }\n\n def on_click(self, event):\n \"\"\"\n event will be a dict like\n {'y': 13, 'x': 1737, 'button': 1, 'name': 'example', 'instance': 'first'}\n \"\"\"\n self.button = event['button']\n # Our modules update methods will get called automatically.\nThis works just like the previous example but we can now be customised. The following example assumes that our module has been saved as click_info.py.
click_info {\n format = \"Cliquez ici\"\n format_clicked = \"Vous avez appuy\u00e9 sur le bouton {button}\"\n}\nself.py3 in our module has color constants that we can access, these allow the user to set colors easily in their config.
# -*- coding: utf-8 -*-\n\"\"\"\nExample module that uses colors.\n\nWe generate a random number between and color it depending on its value.\nClicking on the module will update it an a new number will be chosen.\n\nConfiguration parameters:\n format: Initial format to use\n (default 'Number {number}')\n\nFormat placeholders:\n {number} Our random number\n\nColor options:\n color_high: number is 5 or higher\n color_low: number is less than 5\n\"\"\"\n\nfrom random import randint\n\n\nclass Py3status:\n format = 'Number {number}'\n\n def random(self):\n number = randint(0, 9)\n full_text = self.py3.safe_format(self.format, {'number': number})\n\n if number < 5:\n color = self.py3.COLOR_LOW\n else:\n color = self.py3.COLOR_HIGH\n\n return {\n 'full_text': full_text,\n 'color': color,\n 'cached_until': self.py3.CACHE_FOREVER\n }\n\n def on_click(self, event):\n # by defining on_click pressing any mouse button will refresh the\n # module.\n pass\nThe colors can be set in the config in the module or its container or in the general section. The following example assumes that our module has been saved as number.py. Although the constants are capitalized they are defined in the config in lower case.
number {\n color_high = '#FF0000'\n color_low = '#00FF00'\n}\nPy3status will call a method in a module to provide output to the i3bar. Methods that have names starting with an underscore will not be used in this way. Any methods defined as static methods will also not be used.
"},{"location":"dev-guide/writing-modules/#outputs","title":"Outputs","text":"Output methods should provide a response dict.
Example response:
{\n 'full_text': \"This text will be displayed\",\n 'cached_until': 1470922537, # Time in seconds since the epoch\n}\nThe response can include the following keys
cached_until
The time (in seconds since the epoch) that the output will be classed as no longer valid and the output function will be called again.
Since version 3.1, if no cached_until value is provided the output will be cached for cache_timeout seconds by default this is 60 and can be set using the -t or --timeout option when running py3status. To never expire the self.py3.CACHE_FOREVER constant should be used.
cached_until should be generated via the self.py3.time_in() method.
color
The color that the module output will be displayed in.
composite
Used to output more than one item to i3bar from a single output method. If this is provided then full_text should not be.
full_text
This is the text output that will be sent to i3bar.
index
The index of the output. Allows composite output to identify which component of their output had an event triggered.
separator
If False no separator will be shown after the output block (requires i3bar 4.12).
urgent
If True the output will be shown as urgent in i3bar.
Some special method are also defined.
kill()
Called just before a module is destroyed.
on_click(event)
Called when an event is received by a module.
post_config_hook()
Called once an instance of a module has been created and the configuration parameters have been set. This is useful for any work a module must do before its output methods are run for the first time. post_config_hook() introduced in version 3.1
Py3 is a special helper object that gets injected into py3status modules, providing extra functionality. A module can access it via the self.py3 instance attribute of its py3status class. For details see py3.
"},{"location":"dev-guide/writing-modules/#composites","title":"Composites","text":"Whilst most modules return a simple response eg:
{\n 'full_text': <some text>,\n 'cached_until': <cache time>,\n}\nSometimes it is useful to provide a more complex, composite response. A composite is made up of more than one simple response which allows for example a response that has multiple colors. Different parts of the response can also be differentiated between when a click event occurs and so allow clicking on different parts of the response to have different outcomes. The different parts of the composite will not have separators between them in the output so they will appear as a single module to the user.
The format of a composite is as follows:
{\n 'cached_until': <cache time>,\n 'composite': [\n {\n 'full_text': <some text>,\n },\n {\n 'full_text': <some more text>,\n 'index': <some index>\n },\n ]\n}\nThe index key in the response is used to identify the individual block and when the modules on_click() method is called the event will include this. Supplied index values should be strings. If no index is given then it will have an integer value indicating its position in the composite.
Py3status allows modules to maintain state through the use of the storage functions of the Py3 helper.
Currently bool, int, float, None, unicode, dicts, lists, datetimes etc are supported. Basically anything that can be pickled. We do our best to ensure that the resulting pickles are compatible with both python versions 2 and 3.
The following helper functions are defined in the modules py3.
These functions may return None if storage is not available as well as some metadata such as storage creation timestamp _ctime and last modification timestamp _mtime.
Example:
def module_function(self):\n # set some storage\n self.py3.storage_set('my_key', value)\n # get the value or None if key not present\n value = self.py3.storage_get('my_key')\nAll contributed modules should have correct documentation. This documentation is in a specific format and is used to generate user documentation.
The docstring of a module is used. The format is as follows:
(default 7).Here is an example of a docstring.
\"\"\"\nSingle line summary\n\nLonger description of the module. This should help users understand the\nmodules purpose.\n\nConfiguration parameters:\n parameter: Explanation of this parameter (default <value>)\n parameter_other: This parameter has a longer explanation that continues\n onto a second line so it is indented.\n (default <value>)\n\nFormat placeholders:\n {info} Description of the placeholder\n\nColor options:\n color_meaning: what this signifies, defaults to color_good\n color_meaning2: what this signifies\n\nRequires:\n program: Information about the program\n python_lib: Information on the library\n\nExample:\n\nmodule { parameter = \"Example\" parameter_other = 7 }
\n@author <author>\n@license <license>\n\"\"\"\nSometimes it is necessary to deprecate configuration parameters. Modules are able to specify information about deprecation so that it can be done automatically. Deprecation information is specified in the Meta class of a py3status module using the deprecated attribute. The following types of deprecation are supported.
The deprecation types will be performed in the order here.
rename
The parameter has been renamed. We will update the configuration to use the new name.
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'rename': [\n {\n 'param': 'format_available', # parameter name to be renamed\n 'new': 'icon_available', # the parameter that will get the value\n 'msg': 'obsolete parameter use `icon_available`', # message\n },\n ],\n }\nformat_fix_unnamed_param
Some formats used {} as a placeholder this needs to be updated to a named placeholder eg {value}.
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'format_fix_unnamed_param': [\n {\n 'param': 'format', # parameter to be changed\n 'placeholder': 'percent', # the place holder to use\n 'msg': '{} should not be used in format use `{percent}`', # message\n },\n ],\n }\nrename_placeholder
We can use this to rename placeholders in format strings
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'rename_placeholder': [\n {\n 'placeholder': 'cpu', # old placeholder name\n 'new': 'cpu_usage', # new placeholder name\n 'format_strings': ['format'], # config settings to update\n },\n ],\n }\nupdate_placeholder_format
This allows us to update the format of a placeholder in format strings. The key value pairs {placeholder: format} can be supplied as a dict in placeholder_formats or the dict can be provided by function the function will be called with the current config and must return a dict. If both are supplied then placeholder_formats will be updated using the dict supplied by the function.
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'update_placeholder_format': [\n {\n 'function': update_placeholder_format, # function returning dict\n 'placeholder_formats': { # dict of placeholder:format\n 'cpu_usage': ':.2f',\n },\n 'format_strings': ['format'], # config settings to update\n }\n ],\n }\nsubstitute_by_value
This allows one configuration parameter to set the value of another.
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'substitute_by_value': [\n {\n 'param': 'mode', # parameter to be checked for substitution\n 'value': 'ascii_bar', # value that will trigger the substitution\n 'substitute': {\n 'param': 'format', # parameter to be updated\n 'value': '{ascii_bar}', # the value that will be set\n },\n 'msg': 'obsolete parameter use `format = \"{ascii_bar}\"`', #message\n },\n ],\n }\nfunction
For more complex substitutions a function can be defined that will be called with the config as a parameter. This function must return a dict of key value pairs of parameters to update
class Py3status:\n\n class Meta:\n\n # Create a function to be called\n def deprecate_function(config):\n # This function must return a dict\n return {'thresholds': [\n (0, 'bad'),\n (config.get('threshold_bad', 20), 'degraded'),\n (config.get('threshold_degraded', 50), 'good'),\n ],\n }\n\n deprecated = {\n 'function': [\n {\n 'function': deprecate_function, # function to be called\n },\n ],\n }\nremove
The parameters will be removed.
class Py3status:\n\n class Meta:\n\n deprecated = {\n 'remove': [\n {\n 'param': 'threshold_bad', # name of parameter to remove\n 'msg': 'obsolete set using thresholds parameter', #message\n },\n ],\n }\nSometimes it is necessary to update configuration parameters. Modules are able to specify information about updates so that it can be done automatically. Config updating information is specified in the Meta class of a py3status module using the update_config attribute. The following types of updates are supported.
update_placeholder_format
This allows us to update the format of a placeholder in format strings. The key value pairs {placeholder: format} can be supplied as a dict in placeholder_formats or the dict can be provided by function the function will be called with the current config and must return a dict. If both are supplied then placeholder_formats will be updated using the dict supplied by the function.
This is similar to the deprecation method but is to allow default formatting of placeholders to be set.
In a module like sysdata we have placeholders eg {cpu_usage} this ends up having a value something like 20.542317173377157 which is strange as the value to use but gives the user the ability to have as much precision as they want. A module writer may decide that they want this displayed as 20.54 so {cpu_usage:.2f} would do this. Having a default format containing that just looks long/silly and the user setting a custom format just wants to do format = 'CPU: {cpu_usage}%' and get expected results ie not the full precision. If they don't like the default formatting of the number they could still do format = 'CPU: {cpu_usage:d}%' etc.
So using this allows sensible defaults formatting and allows simple placeholders for user configurations.
class Py3status:\n\n class Meta:\n\n update_config = {\n 'update_placeholder_format': [\n {\n 'placeholder_formats': { # dict of placeholder:format\n 'cpu_usage': ':.2f',\n },\n 'format_strings': ['format'], # config settings to update\n }\n ],\n }\nEach module should be able to run independently for testing purposes. This is simply done by adding the following code to the bottom of your module.
if __name__ == \"__main__\":\n \"\"\"\n Run module in test mode.\n \"\"\"\n from py3status.module_test import module_test\n module_test(Py3status)\nIf a specific config should be provided for the module test, this can be done as follows.
if __name__ == \"__main__\":\n \"\"\"\n Run module in test mode.\n \"\"\"\n config = {\n 'always_show': True,\n }\n from py3status.module_test import module_test\n module_test(Py3status, config=config)\nSuch modules can then be tested independently by running python /path/to/module.py.
$ python loadavg.py\n[{'full_text': 'Loadavg ', 'separator': False,\n'separator_block_width': 0, 'cached_until': 1538755796.0},\n{'full_text': '1.87 1.73 1.87', 'color': '#9DD7FB'}]\n^C\nWe also can produce an output similar to i3bar output in terminal with python /path/to/module.py --term.
$ python loadavg.py --term\nLoadavg 1.41 1.61 1.82\nLoadavg 1.41 1.61 1.82\nLoadavg 1.41 1.61 1.82\n^C\nYou can share your custom modules and make them available for py3status users even if they are not directly part of the py3status main project!
All you have to do is to package your module and publish it to PyPI.
py3status will discover custom modules if they are installed in the same host interpreter and if an entry_point in your package setup.py is defined:
setup(\n entry_points={\"py3status\": [\"module = package_name.py3status_module_name\"]},\n)\nThe awesome pewpew module can be taken as an example on how to do it easily:
We will gladly add extra_requires pointing to your modules so that users can require them while installing py3status. Just open an issue to request this or propose a PR.
If you have installed py3status in a virtualenv (maybe because your custom module has dependencies that need to be available) you can also create an installable package from your module and publish it on PyPI.
Note
To clearly identify your py3status package and for others to discover it easily it is recommended to name the PyPI package py3status-<your module name>.
py3status comes with a large range of modules.
Modules in py3status are configured using your usual i3status.conf or your own py3status.conf which follows the exact same format.
py3status will try to find its configuration file in the following locations:
~/.config/py3status/config~/.config/i3status/config~/.config/i3/i3status.conf~/.i3status.conf~/.i3/i3status.conf/etc/xdg/i3status/config/etc/i3status.confwhich if you are used to XDG_CONFIG paths relates to:
XDG_CONFIG_HOME/py3status/configXDG_CONFIG_HOME/i3status/configXDG_CONFIG_HOME/i3/i3status.conf~/.i3status.conf~/.i3/i3status.confXDG_CONFIG_DIRS/i3status/config/etc/i3status.confYou can also specify the config location using py3status -c <path to config file> in your i3 configuration file.
To load a py3status module you just have to list it like any other i3status module using the order += parameter.
Ordering your py3status modules in your i3bar is just the same as i3status modules, just list the order parameter where you want your module to be displayed.
For example you could insert and load the imap module like this:
order += \"disk /home\"\norder += \"disk /\"\norder += \"imap\"\norder += \"time\"\nYour py3status modules are configured the exact same way as i3status modules, directly from your i3status.conf (or your own configuration file), like this :
# configure the py3status imap module\n# and run thunderbird when I left click on it\nimap {\n cache_timeout = 60\n imap_server = 'imap.myprovider.com'\n mailbox = 'INBOX'\n password = 'coconut'\n port = '993'\n user = 'mylogin'\n on_click 1 = \"exec thunderbird\"\n}\nPy3status itself does not handle the possible dependencies of the modules you use. Each module's documentation has a dedicated Requires section allowing you to know which libraries or binaries they depend on. It's up to you to install them on your system.
This special section holds py3status specific configuration. Settings here will affect all py3status modules. Many settings e.g. colors can still be overridden by also defining in the individual module.
stop_signal. Specify a signal number to be used by i3bar to stop/resume the bar refresh. This is useful if you want to prevent i3bar from stopping py3status when the bar is not visible (hidden/fullscreen).# prevent i3bar from stopping py3status when hidden/fullscreen\npy3status {\n stop_signal = 0\n}\nnagbar_font. Specify a font for i3-nagbar -f <font>.py3status {\n nagbar_font = 'pango:Ubuntu Mono 12'\n}\nstorage: Set storage name or path.Store cache in $XDG_CACHE_HOME or ~/.cache:
# default behavior\npy3status {\n storage = 'py3status_cache.data'\n}\nStore per config cache in $XDG_CACHE_HOME or ~/.cache:
# first config\npy3status {\n storage = 'py3status_top.data'\n}\n# second config\npy3status {\n storage = 'py3status_bottom.data'\n}\nStore per config cache in different directories:
# first config\npy3status {\n storage = '~/.config/py3status/cache_top.data'\n}\n# second config\npy3status {\n storage = '~/.config/py3status/cache_bottom.data'\n}\nYou can specify the following options in module configuration.
min_length: Specify a minimum length of characters for modules.position: Specify how modules should be positioned when the min_length is not reached. Either left (default), center, or right.static_string {\n min_length = 15\n position = 'center'\n}\nYou can specify the options in module or py3status configuration section.
The following options will work on i3.
align: Specify how modules should be aligned when the min_width is not reached. Either left (default), center, or right.background: Specify a background color for py3status modules.markup: Specify how modules should be parsed.min_width: Specify a minimum width of pixels for modules.separator: Specify a separator boolean for modules.separator_block_width: Specify a separator block width for modules.The following options will work on i3-gaps.
border: Specify a border color for modules.border_bottom: Specify a border width for modulesborder_left: Specify a border width for modules.border_right: Specify a border width for modules.border_top: Specify a border width for modules.The following options will work on py3status.
min_length: Specify a minimum length of characters for modules.position: Specify how modules should be positioned when the min_length is not reached. Either left (default), center, or right.# customize a theme\npy3status {\n align = 'left'\n markup = 'pango'\n min_width = 20\n separator = True\n separator_block_width = 9\n\n background = '#285577'\n border = '#4c7899'\n border_bottom = 1\n border_left = 1\n border_right = 1\n border_top = 1\n\n min_length = 15\n position = 'right'\n}\nYou can specify the options in module or py3status configuration section.
The following options will work on i3bar and py3status.
urgent_background: Specify urgent background color for modules.urgent_foreground: Specify urgent foreground color for modules.urgent_border: Specify urgent border color for modules.The following options will work on i3bar-gaps and py3status.
urgent_border_bottom: Specify urgent border width for modulesurgent_border_left: Specify urgent border width for modules.urgent_border_right: Specify urgent border width for modules.urgent_border_top: Specify urgent border width for modules.You lose urgent functionality too that can be sometimes utilized by container modules, e.g., frame and group.
# customize urgent\npy3status {\n urgent_background = 'blue'\n urgent_foreground = 'white'\n urgent_border = 'red'\n urgent_border_bottom = 1\n urgent_border_left = 1\n urgent_border_right = 1\n urgent_border_top = 1\n}\nYou can specify the options in module or py3status configuration section.
resources: Specify a list of 3-tuples, e.g., [(option, resource, fallback)], to import resources.# import resources\npy3status {\n resources = [\n ('color_bad', '*color9', 'lightcoral'),\n ('color_good', '*color10', 'lightgreen'),\n ('color_degraded', '*color11', 'khaki'),\n ('nagbar_font', 'py3status.font', 'pango:Ubuntu Mono 12'),\n ]\n}\n# import 16 colors\npy3status {\n resources = [\n ('color_color0', '*color0', 'black'),\n ('color_color1', '*color1', 'black'),\n ('color_color2', '*color2', 'black'),\n ('color_color3', '*color3', 'black'),\n ('color_color4', '*color4', 'black'),\n ('color_color5', '*color5', 'black'),\n ('color_color6', '*color6', 'black'),\n ('color_color7', '*color7', 'black'),\n ('color_color8', '*color8', 'black'),\n ('color_color9', '*color9', 'black'),\n ('color_color10', '*color10', 'black'),\n ('color_color11', '*color11', 'black'),\n ('color_color12', '*color12', 'black'),\n ('color_color13', '*color13', 'black'),\n ('color_color14', '*color14', 'black'),\n ('color_color15', '*color15', 'black'),\n ]\n}\n\n# apply colors\ncoin_market {\n thresholds = [(-100, \"color9\"), (0, \"color10\")]\n}\nPy3status allows you to hide individual configuration parameters so that they do not leak into log files, user notifications or to the i3bar. Additionally they allow you to obfuscate configuration parameters using base64 encoding.
To \"hide\" a value you can use the hide() configuration function. This prevents the module displaying the value as a format placeholder and from appearing in the logs.
# Example of 'hidden' configuration\nimap {\n imap_server = 'imap.myprovider.com'\n password = hide('hunter22')\n user = 'mylogin'\n}\nTo base64 encode a value you can use the base64() configuration function. This also prevents the module displaying the value as a format placeholder and from appearing in the logs.
# Example of obfuscated configuration\nimap {\n imap_server = 'imap.myprovider.com'\n password = base64('Y29jb251dA==')\n user = 'mylogin'\n}\nSince version 3.1 obfuscation options can also be added by the legacy method. Add :hide or :base64 to the name of the parameters. You are advised to use the new hide() and base64() configuration functions.
Note
Legacy obfuscation is only available for string: parameters with :hide or :base64. If you want other types then be sure to use hide() and base64() configuration functions.
# normal_parameter will be shown in log files etc as 'some value'\n# obfuscated_parameter will be shown in log files etc as '***'\nmodule {\n normal_parameter = 'some value'\n obfuscated_parameter:hide = 'some value'\n}\nIn the previous example configuration the users password is in plain text. Users may want to make it less easy to read. Py3status allows strings to be base64 encoded.
To use an encoded string add :base64 to the name of the parameter.
# Example of obfuscated configuration\nimap {\n imap_server = 'imap.myprovider.com'\n password:base64 = 'Y29jb251dA=='\n user = 'mylogin'\n}\nWarning
Base64 encoding is very simple and should not be considered secure in any way.
"},{"location":"user-guide/configuration/#configuring-colors","title":"Configuring colors","text":"Since version 3.1 py3status allows greater color configuration. Colors can be set in the general section of your i3status.conf or in an individual modules configuration. If a color is not in a modules configuration then the values from the general section will be used.
If a module does not specify colors but it is in a container, then the colors of the container will be used if they are set, before using ones defined in the general section.
Generally colors can specified using hex values eg #FF00FF or #F0F. It is also possible to use css3 color names eg red hotpink. Check here for al ist of available color names.
general {\n # These will be used if not supplied by a module\n color = '#FFFFFF'\n color_good = '#00FF00'\n color_bad = '#FF0000'\n color_degraded = '#FFFF00'\n}\n\ntime {\n color = 'FF00FF'\n format = \"%H:%M\"\n}\n\nbattery_level {\n color_good = '#00AA00'\n color_bad = '#AA0000'\n color_degraded = '#AAAA00'\n color_charging = '#FFFF00'\n}\nSome modules allow you to define thresholds in a module. These are used to determine which color to use when displaying the module. Thresholds are defined in the config as a list of tuples. With each tuple containing a value and a color. The color can either be a named color eg good referring to color_good or a hex value.
volume_status {\n thresholds = [\n (0, \"#FF0000\"),\n (20, \"degraded\"),\n (50, \"bad\"),\n ]\n}\nIf the value checked against the threshold is equal to or more than a threshold then that color supplied will be used.
In the above example the logic would be
if 0 >= value < 20 use #FF0000\nelse if 20 >= value < 50 use color_degraded\nelse if 50 >= value use color_good\nSome modules may allow more than one threshold to be defined. If all the thresholds are the same they can be defined as above but if you wish to specify them separately you can by giving a dict of lists.
my_module {\n thresholds = {\n 'threshold_1': [\n (0, \"#FF0000\"),\n (20, \"degraded\"),\n (50, \"bad\"),\n ],\n 'threshold_2': [\n (0, \"good\"),\n (30, \"bad\"),\n ],\n }\n}\nYou can specify hidden color to hide a block.
# hide a block when ``1avg`` (i.e., 12.4) is less than 20 percent\nformat = \"[\\?color=1avg [\\?color=darkgray&show 1min] {1min}]\"\nloadavg {\n thresholds = [\n (0, \"hidden\"),\n (20, \"good\"),\n (40, \"degraded\"),\n (60, \"#ffa500\"),\n (80, \"bad\"),\n ]\n}\n\n# hide cpu block when ``cpu_used_percent`` is less than 50 percent\n# hide mem block when ``mem_used_percent`` is less than 50 percent\nsysdata {\n thresholds = [\n (50, \"hidden\"),\n (75, \"bad\"),\n ]\n}\nAll modules allow you to define the format of their output. This is done with the format option. You can:
mpd_status {\n format = \"MPD:\"\n}\n\\ to escape a character (\\[ will show [).mpd_status {\n format = \"MPD: {state} {artist} {title}\"\n}\n- Unknown placeholders act as if they were static text and\n placeholders that are empty or None will be removed.\n- Formatting can also be applied to the placeholder Eg\n `{number:03.2f}`.\n[]. The following example will show artist - title if artist is present and title if title but no artist is present.mpd_status {\n format = \"MPD: {state} [[{artist} - ]{title}]\"\n}\n|. The following example will show the filename if neither artist nor title are present.mpd_status {\n format = \"MPD: {state} [[{artist} - ]{title}]|{file}\"\n}\n\\? can be used to provide extra commands to the format string. Multiple commands can be given using an ampersand & as a separator.my_module {\n format = \"\\?color=#FF00FF&show blue\"\n}\n\\? with a an if statement. Multiple conditions or commands can be combined by using an ampersand & as a separator. Here are some examples:\\?if=online green | red checks if the placeholder exists and would display green in that case. A condition that evaluates to false invalidates a section and the section can be hidden with [] or skipped with |\\?if=!online red | green this dose the same as the above condition, the only difference is that the exclamation mark ! negates the condition.\\?if=state=play PLAYING! | not playing checks if the placeholder contains play and displays PLAYING! if not it will display not playing.A format string using nearly all of the above options could look like this:
mpd_status {\n format = \"MPD: {state} [\\?if=![stop] [[{artist} - ]{title}]|[{file}]]\"\n}\nThis will show MPD: [state] if the state of the MPD is [stop] or MPD: [state] artist - title if it is [play] or [pause] and artist and title are present, MPD: [state] title if artist is missing and MPD: [state] file if artist and title are missing.
Some modules use i3bar's urgent feature to indicate that something important has occurred. The allow_urgent configuration parameter can be used to allow/prevent a module from setting itself as urgent.
# prevent modules showing as urgent, except github\npy3status {\n allow_urgent = false\n}\n\ngithub {\n allow_urgent = true\n}\nWhen a module error has occurred, it will be reported on the bar. The on_error configuration parameter allows users to choose what to do instead.
Supported values:
show (default): report the error on the bar (click to view)hide: hide the module on the bar# hide errors on all modules by default (still reported on logs)\npy3status {\n on_error = \"hide\"\n}\n\n# hide errors on non-NVIDIA hardwares\nnvidia_smi {\n on_error = \"hide\"\n}\n\n# hide errors on sway where xrandr does not work\nxrandr {\n on_error = \"hide\"\n}\nThe module_group module allows you to group several modules together. Only one of the modules are displayed at a time. The displayed module can either be cycled through automatically or by user action (the default, on mouse scroll).
This module is very powerful and allows you to save a lot of space on your bar.
order += \"group tz\"\n\n# cycle through different timezone hours every 10s\ngroup tz {\n cycle = 10\n format = \"{output}\"\n\n tztime la {\n format = \"LA %H:%M\"\n timezone = \"America/Los_Angeles\"\n }\n\n tztime ny {\n format = \"NY %H:%M\"\n timezone = \"America/New_York\"\n }\n\n tztime du {\n format = \"DU %H:%M\"\n timezone = \"Asia/Dubai\"\n }\n}\nThe module_frame module also allows you to group several modules together, however in a frame all the modules are shown. This allows you to have more than one module shown in a group.
order += \"group frames\"\n\n# group showing disk space or times using button to change what is shown.\ngroup frames {\n click_mode = \"button\"\n\n frame time {\n tztime la {\n format = \"LA %H:%M\"\n timezone = \"America/Los_Angeles\"\n }\n\n tztime ny {\n format = \"NY %H:%M\"\n timezone = \"America/New_York\"\n }\n\n tztime du {\n format = \"DU %H:%M\"\n timezone = \"Asia/Dubai\"\n }\n }\n\n frame disks {\n disk \"/\" {\n format = \"/ %avail\"\n }\n\n disk \"/home\" {\n format = \"/home %avail\"\n }\n }\n}\nFrames can also have a toggle button to hide/show the content
# A frame showing times in different cities.\n# We also have a button to hide/show the content\n\nframe time {\n format = '{output}{button}'\n format_separator = ' ' # have space instead of usual i3bar separator\n\n tztime la {\n format = \"LA %H:%M\"\n timezone = \"America/Los_Angeles\"\n }\n\n tztime ny {\n format = \"NY %H:%M\"\n timezone = \"America/New_York\"\n }\n\n tztime du {\n format = \"DU %H:%M\"\n timezone = \"Asia/Dubai\"\n }\n}\npy3status allows you to easily add click events to modules in your i3bar. These modules can be both i3status or py3status modules. This is done in your i3status.config using the on_click parameter.
Just add a new configuration parameter named on_click [button number] to your module config and py3status will then execute the given i3 command (using i3-msg).
This means you can run simple tasks like executing a program or execute any other i3 specific command.
As an added feature and in order to get your i3bar more responsive, every on_click command will also trigger a module refresh. This works for both py3status modules and i3status modules as described in the refresh command below.
# button numbers\n1 = left click\n2 = middle click\n3 = right click\n4 = scroll up\n5 = scroll down\n# reload the i3 config when I left click on the i3status time module\n# and restart i3 when I middle click on it\ntime {\n on_click 1 = \"reload\"\n on_click 2 = \"restart\"\n}\n\n# control the volume with your mouse (need >i3-4.8)\n# launch alsamixer when I left click\n# kill it when I right click\n# toggle mute/unmute when I middle click\n# increase the volume when I scroll the mouse wheel up\n# decrease the volume when I scroll the mouse wheel down\nvolume master {\n format = \"\u266a: %volume\"\n device = \"default\"\n mixer = \"Master\"\n mixer_idx = 0\n on_click 1 = \"exec i3-sensible-terminal -e alsamixer\"\n on_click 2 = \"exec amixer set Master toggle\"\n on_click 3 = \"exec killall alsamixer\"\n on_click 4 = \"exec amixer set Master 1+\"\n on_click 5 = \"exec amixer set Master 1-\"\n}\n\n# run wicd-gtk GUI when I left click on the i3status ethernet module\n# and kill it when I right click on it\nethernet eth0 {\n # if you use %speed, i3status requires root privileges\n format_up = \"E: %ip\"\n format_down = \"\"\n on_click 1 = \"exec wicd-gtk\"\n on_click 3 = \"exec killall wicd-gtk\"\n}\n\n# run thunar when I left click on the / disk info module\ndisk \"/\" {\n format = \"/ %free\"\n on_click 1 = \"exec thunar /\"\n}\n\n# this is a py3status module configuration\n# open an URL on opera when I left click on the weather_yahoo module\nweather_yahoo paris {\n cache_timeout = 1800\n woeid = 615702\n forecast_days = 2\n on_click 1 = \"exec opera http://www.meteo.fr\"\n request_timeout = 10\n}\nThere are two commands you can pass to the on_click parameter that have a special meaning to py3status :
refresh : This will refresh (expire the cache) of the clicked module. This also works for i3status modules (it will send a SIGUSR1 to i3status for you).refresh_all : This will refresh all the modules from your i3bar (i3status included). This has the same effect has sending a SIGUSR1 to py3status.Since version 3.3 it is possible to use the output text of a module in the on_click command. To do this $OUTPUT can be used in command and it will be substituted by the modules text output when the command is run.
# copy module output to the clipboard using xclip\nmy_module {\n on_click 1 = 'exec echo $OUTPUT | xclip -i'\n}\nIf the output of a module is a composite then the output of the part clicked on can be accessed using $OUTPUT_PART.
You may use the value of an environment variable in your configuration with the env(...) directive. These values are captured at startup and may be converted to the needed datatype (only str, int, float, bool and auto are currently supported).
Note, the auto conversion will try to guess the type of the contents and automatically convert to that type. Without an explicit conversion function, it defaults to auto.
This is primarily designed to obfuscate sensitive information when sharing your configuration file, such as usernames, passwords, API keys, etc.
The env(...) expression can be used anywhere a normal constant would be used. Note, you cannot use the directive in place of a dictionary key, i.e {..., env(KEY): 'val', ...}.
See the examples below!
order += \"my_module\"\norder += env(ORDER_MODULE)\n\nmodule {\n normal_parameter = 'some value'\n env_parameter = env(SOME_ENVIRONMENT_PARAM)\n sensitive_api_key = env(API_KEY)\n\n complex_parameter = {\n 'key': env(VAL)\n }\n\n equivalent1 = env(MY_VAL)\n equivalent2 = env(MY_VAL, auto)\n\n list_of_tuples = [\n (env(APPLE_NUM, int), 'apple'),\n (2, env(ORANGE))\n ]\n\n float_param = env(MY_NUM, float)\n}\nYou can use the standard output of a shell script in your configuration with the shell(...) directive. These values are captured at startup and may be converted to the needed datatype (only str, int, float, bool and auto (default) are currently supported).
The shell script executed must return a single line of text on stdout and then terminate. If the type is explicitly declared bool, the exit status of the script is respected (a non-zero exit status being interpreted falsey). In any other case if the script exits with a non-zero exit status an error will be thrown.
The shell(...) expression can be used anywhere a constant or an env(...) directive can be used (see the section \"Environment Variables\").
Usage example:
my_module {\n password = shell(pass show myPasswd | head -n1)\n some_string = shell(/opt/mydaemon/get_api_key.sh, str)\n pid = shell(cat /var/run/mydaemon/pidfile, int)\n my_bool = shell(pgrep thttpd, bool)\n}\nDue to the way the config is parsed you need to to escape any closing parenthesis ) using a backslash \\).
static_string {\n # note we need to explicitly cast the result to str\n # because we are using it as the format which must be a\n # string\n format = shell(echo $((6 + 2\\)\\), str)\n}\nRefreshing of modules can be triggered when an udev event is detected on a specific subsystem using the on_udev_<subsystem> configuration parameter and an associated action.
Possible actions:
refresh: immediately refresh the module and keep on updating it as usualrefresh_and_freeze: module is ONLY refreshed when said udev subsystem emits an event# refresh xrandr only when udev 'drm' events are triggered\nxrandr {\n on_udev_drm = \"refresh_and_freeze\"\n}\nNote
This feature will only activate when pyudev is installed on the system. This is an optional dependency of py3status and is therefore not enforced by all package managers.
Timeouts are handled thanks to the global request_timeout setting.
Request Timeout for URL request based modules can be specified in the module configuration. To find out if your module supports that, look for self.py3.request in the code. Otherwise, we will use 10.
# stop waiting for a response after 10 seconds\nexchange_rate {\n request_timeout = 10\n}\nRetries are handled thanks to the global request_retry_times and request_retry_wait settings.
Requests failing due to network unavailability or remote server timeouts are retried automatically request_retry_times times (default 3) at a request_retry_wait (default 2) seconds interval.
This allows to be more graceful to i3 startup when network is not up yet or to short network disruptions and not display an error on the bar in that case.
To find out if your module supports that, look for self.py3.request in the code.
# try to contact the OWM API 10 times every 5 seconds before displaying\n# an error on the bar for the module\n# that is equivalent to 50 seconds of retrying before an error occurs\nweather_owm {\n request_retry_times = 10\n request_retry_wait = 5\n}\nWant Py3status in your beloved tmux? Sure!
While Py3status is by default running using the i3bar output format, you can change the output_format of the general section of the configuration file to get your favorite status bar in the following programs:
Stable updates, official releases:
$ pacman -S py3status\nReal-time updates from master branch:
$ yay -S py3status-git\nStable updates. In testing and unstable, and soon in stable backports:
$ apt-get install py3status\nBuster users might want to check out issue #1916 and use pip3 instead or the alternative method proposed until this debian bug is handled and stable.
Note
If you want to use pip, you should consider using pypi-install from the python-stdeb package (which will create a .deb out from a python package) instead of directly calling pip.
$ pip3 install py3status\n$ dnf install py3status\nCheck available USE flags if you need them!
$ emerge -a py3status\nIn community repository since Alpine Linux 3.17.
$ apk add py3status\n$ pip install py3status\nThere are optional requirements that you could find useful:
py3status[udev] for udev support.Or if you want everything:
py3status[all] to install all core extra requirements and features.$ xbps-install -S py3status\nTo have py3status globally persistent add to your NixOS configuration file py3status as a Python 3 package with:
(python3Packages.py3status.overrideAttrs (oldAttrs: {\n propagatedBuildInputs = with python3Packages;[ pytz tzlocal ] ++ oldAttrs.propagatedBuildInputs;\n}))\nIf you are, and you probably are, using i3 you might want a section in your /etc/nixos/configuration.nix that looks like this:
{\n services.xserver.windowManager.i3 = {\n enable = true;\n extraPackages = with pkgs; [\n dmenu\n i3status\n i3lock\n (python3Packages.py3status.overrideAttrs (oldAttrs: {\n propagatedBuildInputs = with python3Packages; [ pytz tzlocal ] ++ oldAttrs.propagatedBuildInputs;\n }))\n ];\n };\n}\nIn this example I included the python packages pytz and tzlocal which are necessary for the py3status module clock. The default packages that come with i3 (dmenu, i3status, i3lock) have to be mentioned if they should still be there.
$ nix-env -i python3.6-py3status\nDisplay air quality polluting in a given location.
An air quality index (AQI) is a number used by government agencies to communicate to the public how polluted the air currently is or how polluted it is forecast to become. As the AQI increases, an increasingly large percentage of the population is likely to experience increasingly severe adverse health effects. Different countries have their own air quality indices, corresponding to different national air quality standards.
Configuration parameters:
auth_token Personal token required. See https://aqicn.org/data-platform/token for more information. (default 'demo')
cache_timeout refresh interval for this module. A message from the site: The default quota is max 1000 requests per minute (~16RPS) and with burst up to 60 requests. See https://aqicn.org/api/ for more information. (default 3600)
format display format for this module (default '[\\?color=aqi {city_name}: {aqi} {category}]')
format_datetime specify strftime characters to format (default {})
location location or uid to query. To search for nearby stations in Krak\u00f3w, try https://api.waqi.info/search/?token=YOUR_TOKEN&keyword=krak\u00f3w For best results, use uid instead of name in location, eg @8691. (default 'Shanghai')
quality_thresholds specify a list of tuples, eg (number, 'color', 'name') (default [(0, '#009966', 'Good'), (51, '#FFDE33', 'Moderate'), (101, '#FF9933', 'Sensitively Unhealthy'), (151, '#CC0033', 'Unhealthy'), (201, '#660099', 'Very Unhealthy'), (301, '#7E0023', 'Hazardous')])
thresholds specify color thresholds to use (default {'aqi': True})
Notes: Your station may have individual scores for pollutants not listed below. See https://api.waqi.info/feed/@UID/?token=TOKEN (Replace UID and TOKEN) for a full list of placeholders to use.
Format placeholders:
{aqi} air quality index
{attributions_0_name} attribution name, there maybe more, change the 0
{attributions_0_url} attribution url, there maybe more, change the 0
{category} health risk category, eg Good, Moderate, Unhealthy, etc
{city_geo_0} monitoring station latitude
{city_geo_1} monitoring station longitude
{city_name} monitoring station name
{city_url} monitoring station url
{dominentpol} dominant pollutant, eg pm25
{idx} Unique ID for the city monitoring station, eg 7396
{time} epoch timestamp, eg 1510246800
{time_s} local timestamp, eg 2017-11-09 17:00:00
{time_tz} local timezone, eg -06:00
{iaqi_co} individual score for pollutant carbon monoxide
{iaqi_h} individual score for pollutant h (?)
{iaqi_no2} individual score for pollutant nitrogen dioxide
{iaqi_o3} individual score for pollutant ozone
{iaqi_pm25} individual score for pollutant particulates smaller than 2.5 \u03bcm in aerodynamic diameter
{iaqi_pm10} individual score for pollutant particulates smaller than 10 \u03bcm in aerodynamic diameter
{iaqi_pm15} individual score for pollutant particulates smaller than than 15 \u03bcm in aerodynamic diameter
{iaqi_p} individual score for pollutant particulates
{iaqi_so2} individual score for pollutant sulfur dioxide
{iaqi_t} individual score for pollutant t (?)
{iaqi_w} individual score for pollutant w (?)
AQI denotes an air quality index. IQAI denotes an individual AQI score. Try https://en.wikipedia.org/wiki/Air_pollution#Pollutants for more information on the pollutants retrieved from your monitoring station.
format_datetime placeholders:
key epoch_placeholder, eg time, vtime
value % strftime characters to be translated, eg '%b %d' ----> 'Nov 11'
Color options:
color_bad print a color for error (if any) from the siteColor thresholds:
xxx print a color based on the value of xxx placeholderExamples:
# show last updated time\nair_quality {\n format = '{city_name}: {aqi} {category} - {time}'\n format_datetime = {'time': '%-I%P'}\n}\nauthor beetleman, lasers
license BSD
"},{"location":"user-guide/modules/#apt_updates","title":"apt_updates","text":"Display number of pending updates for Debian based Distros.
Thanks to Iain Tatch <iain.tatch@gmail.com> for the script that this is based on. This will display a count of how many 'apt' updates are waiting to be installed.
Configuration parameters:
cache_timeout How often we refresh this module in seconds (default 600)
format Display format to use (default 'UPD[\\?not_zero : {apt}]')
Format placeholders:
{apt} Number of pending apt updatesRequires:
apt Needed to display pending 'apt' updatesauthor Joshua Pratt <jp10010101010000@gmail.com>
license BSD
"},{"location":"user-guide/modules/#arch_updates","title":"arch_updates","text":"Display number of pending updates for Arch Linux.
Configuration parameters:
cache_timeout refresh interval for this module (default 3600)
format display format for this module, otherwise auto (default None)
hide_if_zero don't show on bar if True (default False)
Format placeholders:
{aur} Number of pending aur updates
{pacman} Number of pending pacman updates
{total} Total updates pending
Requires:
pacman-contrib contributed scripts and tools for pacman systems
auracle a flexible command line client for arch linux's user repository
trizen lightweight pacman wrapper and AUR helper
yay yet another yogurt. pacman wrapper and aur helper written in go
paru feature packed AUR helper
pikaur pacman wrapper and AUR helper written in python
Note: py3status for Arch-based distributions should include an alpm hook to refresh this module after packages and/or files being modified.
author Iain Tatch <iain.tatch@gmail.com>
license BSD
"},{"location":"user-guide/modules/#async_script","title":"async_script","text":"Display output of a given script asynchronously.
Always displays the last line of output from a given script, set by script_path. If a line contains only a color (/^#[0-F]{6}$/), it is used as such (set force_nocolor to disable). The script may have parameters.
Configuration parameters:
force_nocolor if true, won't check if a line contains color (default False)
format see placeholders below (default '{output}')
script_path script you want to show output of (compulsory) (default None)
strip_output shall we strip leading and trailing spaces from output (default False)
Format placeholders:
{output} output of script given by \"script_path\"Examples:
async_script {\n format = \"{output}\"\n script_path = \"ping 127.0.0.1\"\n}\nauthor frimdo ztracenastopa@centrum.cz, girst
"},{"location":"user-guide/modules/#audiosink","title":"audiosink","text":"Display and toggle default audiosink.
Configuration parameters:
cache_timeout How often we refresh this module in seconds (default 10)
display_name_mapping dictionary mapping devices names to display names (default {})
format display format for this module (default '{audiosink}')
sinks_to_ignore list of devices names to ignore (default [])
Format placeholders:
{audiosink} comma seperated list of (display) names of default sink(s)Requires:
pulseaudio networked sound serverExamples:
audiosink {\n display_name_mapping = {\"Family 17h/19h HD Audio Controller Analog Stereo\": \"Int\", \"ThinkPad Dock USB Audio Analog Stereo\": \"Dock\"}\n format = r\"{audiosink}\"\n sinks_to_ignore = [\"Renoir Radeon High Definition Audio Controller Digital Stereo (HDMI)\"]\n}\nauthor Jens Brandt <py3status@brandt-george.de>
license BSD
"},{"location":"user-guide/modules/#aws_bill","title":"aws_bill","text":"Display bill for Amazon Web Services.
WARNING: This module generate some costs on the AWS bill. Take care about the cache_timeout to limit these fees!
Configuration parameters:
aws_access_key_id Your AWS access key (default '')
aws_account_id The root ID of the AWS account Can be found here` https://console.aws.amazon.com/billing/home#/account (default '')
aws_secret_access_key Your AWS secret key (default '')
billing_file Csv file location (default '/tmp/.aws_billing.csv')
cache_timeout How often we refresh this module in seconds (default 3600)
format string that formats the output. See placeholders below. (default '{bill_amount}$')
s3_bucket_name The bucket where billing files are sent by AWS. Follow this article to activate this feature: https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-reports.html (default '')
Format placeholders:
{bill_amount} AWS bill amountColor options:
color_good Balance available
color_bad An error has occurred
Requires:
boto a python interface to amazon web services (aws)author nawadanp
"},{"location":"user-guide/modules/#backlight","title":"backlight","text":"Adjust screen backlight brightness.
Configuration parameters:
brightness_delta Change the brightness by this step. (default 8)
brightness_initial Set brightness to this value on start. (default None)
brightness_minimal Don't go below this brightness to avoid black screen (default 1)
button_down Button to click to decrease brightness. Setting to 0 disables. (default 5)
button_up Button to click to increase brightness. Setting to 0 disables. (default 4)
cache_timeout How often we refresh this module in seconds (default 10)
command The program to use to change the backlight. Currently xbacklight, light and brightnessctl are supported. The program needs to be installed and on your path. If no program is installed, this module will attempt to use logind support instead (default 'xbacklight')
device Device name or full path to use, eg, acpi_video0 or /sys/class/backlight/acpi_video0, otherwise automatic (default None)
format Display brightness, see placeholders below (default '\u263c: {level}%')
hide_when_unavailable Hide if no backlight is found (default False)
low_tune_threshold If current brightness value is below this threshold, the value is changed by a minimal value instead of the brightness_delta. (default 0)
Format placeholders:
{level} brightnessRequires: one of xbacklight: need for changing brightness, not detection light: program to easily change brightness on backlight-controllers brightnessctl: change brightness wayland compatible dbus-python + logind v243: logind to change brightness without X
author Tjaart van der Walt (github:tjaartvdwalt), J\u00e9r\u00e9my Rosen (github:boucman)
license BSD
"},{"location":"user-guide/modules/#battery_level","title":"battery_level","text":"Display battery information.
Configuration parameters:
battery_id id of the battery to be displayed set to 'all' for combined display of all batteries (default 0)
blocks a string, where each character represents battery level especially useful when using icon fonts (e.g. FontAwesome) (default \"_\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588\")
cache_timeout a timeout to refresh the battery state (default 60)
charging_character a character to represent charging battery especially useful when using icon fonts (e.g. FontAwesome) set to 'None' if you want to hide the charging state of your battery (default \"\u26a1\")
format string that formats the output. See placeholders below. (default \"{icon}\")
format_notify_charging format of the notification received when you click on the module while your computer is plugged in (default 'Charging ({percent}%)')
format_notify_discharging format of the notification received when you click on the module while your computer is not plugged in (default \"{time_remaining}\")
format_status_bad a string to put in {status} when bad (default \"CRIT\")
format_status_charging a string to put in {status} when charging (default \"CHG\")
format_status_degraded a string to put in {status} when degraded (default \"LOW\")
format_status_discharging a string to put in {status} when discharging (default \"BAT\")
format_status_full a string to put in {status} when full (default \"FULL\")
hide_seconds hide seconds in remaining time (default False)
hide_when_full hide any information when battery is fully charged (when the battery level is greater than or equal to 'threshold_full') (default False)
measurement_mode either 'acpi' or 'sys', or None to autodetect. 'sys' should be more robust and does not have any extra requirements, however the time measurement may not work in some cases (default None)
notification show current battery state as notification on click (default False)
notify_low_level display notification when battery is running low (when the battery level is less than 'threshold_degraded') (default False)
on_udev_power_supply dynamic variable to watch for power_supply udev subsystem events to trigger specified action. (default \"refresh\")
sys_battery_path set the path to your battery(ies), without including its number (default \"/sys/class/power_supply/\")
threshold_bad a percentage below which the battery level should be considered bad (default 10)
threshold_degraded a percentage below which the battery level should be considered degraded (default 30)
threshold_full a percentage at or above which the battery level should should be considered full (default 100)
Format placeholders:
{ascii_bar} - a string of ascii characters representing the battery level, an alternative visualization to '{icon}' option
{icon} - a character representing the battery level, as defined by the 'blocks' and 'charging_character' parameters
{percent} - the remaining battery percentage (previously '{}')
{time_remaining} - the remaining time until the battery is empty
{power} - the current power consumption in Watts. Not working with acpi.
{status} - the current battery status string as defined by 'format_status_*'
Color options:
color_bad Battery level is below threshold_bad
color_charging Battery is charging (default \"#FCE94F\")
color_degraded Battery level is below threshold_degraded
color_good Battery level is above thresholds
Requires: - the acpi the acpi command line utility (only if measurement_mode='acpi')
author shadowprince, AdamBSteele, maximbaz, 4iar, m45t3r
license Eclipse Public License
"},{"location":"user-guide/modules/#bluetooth","title":"bluetooth","text":"Display bluetooth status.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default \"{format_adapter}\")
format_adapter display format for adapters (default \"{format_device}\")
format_adapter_separator show separator if more than one (default \" \")
format_device display format for devices (default \"\\?if=connected&color=connected {alias}\")
format_device_separator show separator if more than one (default \" \")
thresholds specify color thresholds to use (default [(False, \"bad\"), (True, \"good\")])
Format placeholders:
{format_adapter} format for adapters
{adapter} number of adapters, eg 1
format_adapter placeholders:
{format_device} format for devices
{device} number of devices, eg 5
{address} eg, 00:00:00:00:00:00
{addresstype} eg, public
{alias} eg, thinkpad
{class} eg, 123456
{discoverable} eg, False
{discoverabletimeout} eg, 0
{discovering} eg, False
{modalias} eg, usb:v1D68234ABCDEF5
{name} eg, z420
{pairable} eg, True
{pairabletimeout} eg, 0
{path} eg, /org/bluez/hci0
{powered} eg, True
{uuids} eg, []
format_device placeholders:
{adapter} eg, /org/bluez/hci0
{address} eg, 00:00:00:00:00:00
{addresstype} eg, public
{alias} eg, MSFT Mouse
{battery} eg, 95
{class} eg, 1234
{connected} eg, False
{icon} eg, input-mouse
{legacypairing} eg, False
{modalias} eg, usb:v1D68234ABCDEF5
{name} eg, Microsoft Bluetooth Notebook Mouse 5000
{paired} eg, True
{servicesresolved} eg, False
{trusted} eg, True
{uuids} eg, []
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
pygobject Python bindings for GObject IntrospectionExamples:
# always display devices\nbluetooth {\n format_device = \"\\?color=connected {alias}\"\n}\n\n# set an alias via blueman-manager or bluetoothctl\n# $ bluetoothctl\n# [bluetooth] # devices\n# [bluetooth] # connect 00:00:00:00:00:00\n# [bluetooth] # set-alias \"MSFT Mouse\"\n\n# display missing adapter (feat. request)\nbluetooth {\n format = \"\\?if=adapter {format_adapter}|\\?color=darkgray No Adapter\"\n}\n\n# legacy default\nbluetooth {\n format = \"\\?color=good BT: {format_adapter}|\\?color=bad BT\"\n format_device_separator = \"\\|\"\n}\nauthor jmdana, lasers
license BSD
"},{"location":"user-guide/modules/#check_tcp","title":"check_tcp","text":"Display status of a TCP port on a given host.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{host}:{port} {state}')
host name of host to check for (default 'localhost')
icon_off show this when unavailable (default 'DOWN')
icon_on show this when available (default 'UP')
port number of port to check for (default 22)
Format placeholders:
{state} port stateColor options:
color_down Closed, default to color_bad
color_up Open, default to color_good
author obb, Moritz L\u00fcdecke
"},{"location":"user-guide/modules/#clock","title":"clock","text":"Display date and time.
This module allows one or more datetimes to be displayed. All datetimes share the same format_time but can set their own timezones. Timezones are defined in the format using the TZ name in squiggly brackets eg {GMT}, {Portugal}, {Europe/Paris}, {America/Argentina/Buenos_Aires}.
See https://docs.python.org/3/library/zoneinfo.html for supported formats.
{Local} can be used for the local settings of your computer.
Note: Timezones are case sensitive!
A full list of timezones can be found at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
Configuration parameters:
block_hours length of time period for all blocks in hours (default 12)
blocks a string, where each character represents time period from the start of a time period. (default '\ud83d\udd5b\ud83d\udd67\ud83d\udd50\ud83d\udd5c\ud83d\udd51\ud83d\udd5d\ud83d\udd52\ud83d\udd5e\ud83d\udd53\ud83d\udd5f\ud83d\udd54\ud83d\udd60\ud83d\udd55\ud83d\udd61\ud83d\udd56\ud83d\udd62\ud83d\udd57\ud83d\udd63\ud83d\udd58\ud83d\udd64\ud83d\udd59\ud83d\udd65\ud83d\udd5a\ud83d\udd66')
button_change_format button that switches format used setting to None disables (default 1)
button_change_time_format button that switches format_time used. Setting to None disables (default 2)
button_reset button that switches display to the first timezone. Setting to None disables (default 3)
cycle If more than one display then how many seconds between changing the display (default 0)
format defines the timezones displayed. This can be a single string or a list. If a list is supplied then the formats can be cycled through using cycle or by button click. (default '{Local}')
format_time format to use for the time, strftime directives such as %H can be used this can be either a string or to allow multiple formats as a list. The one used can be changed by button click. (default ['[{name_unclear} ]%c', '[{name_unclear} ]%x %X', '[{name_unclear} ]%a %H:%M', '[{name_unclear} ]{icon}'])
locale Override the system locale. Examples: when set to 'fr_FR' %a on Tuesday is 'mar.'. (default None)
round_to_nearest_block defines how a block icon is chosen. Examples: when set to True, '13:14' is '\ud83d\udd50', '13:16' is '\ud83d\udd5c' and '13:31' is '\ud83d\udd5c'; when set to False, '13:14' is '\ud83d\udd50', '13:16' is '\ud83d\udd50' and '13:31' is '\ud83d\udd5c'. (default True)
Format placeholders:
{icon} a character representing the time from blocks
{name} friendly timezone name eg Buenos Aires
{name_unclear} friendly timezone name eg Buenos Aires but is empty if only one timezone is provided
{timezone} full timezone name eg America/Argentina/Buenos_Aires
{timezone_unclear} full timezone name eg America/Argentina/Buenos_Aires but is empty if only one timezone is provided
Examples:
# cycling through London, Warsaw, Tokyo\nclock {\n cycle = 30\n format = [\"{Europe/London}\", \"{Europe/Warsaw}\", \"{Asia/Tokyo}\"]\n format_time = \"{name} %H:%M\"\n}\n\n# Show the time and date in New York\nclock {\n format = \"Big Apple {America/New_York}\"\n format_time = \"%Y-%m-%d %H:%M:%S\"\n}\n\n# wall clocks\nclock {\n format = \"{Asia/Calcutta} {Africa/Nairobi} {Asia/Bangkok}\"\n format_time = \"{name} {icon}\"\n}\nauthor tobes ultrabug
license BSD
"},{"location":"user-guide/modules/#cmus","title":"cmus","text":"Display song currently playing in cmus.
cmus (C* Music Player) is a small, fast and powerful console audio player which supports most major audio formats. Various features include gapless playback, ReplayGain support, MP3 and Ogg streaming, live filtering, instant startup, customizable key-bindings, and vi-style default key-bindings.
Configuration parameters:
button_next mouse button to skip next track (default None)
button_pause mouse button to pause/play the playback (default 1)
button_previous mouse button to skip previous track (default None)
button_stop mouse button to stop the playback (default 3)
cache_timeout refresh interval for this module (default 5)
format display format for this module (default '[\\?if=is_started [\\?if=is_playing > ][\\?if=is_paused || ]' '[\\?if=is_stopped .. ][[{artist}][\\?soft - ][{title}]' '|\\?show cmus: waiting for user input]]')
replacements specify a list/dict of string placeholders to modify (default None)
sleep_timeout sleep interval for this module. when cmus is not running, this interval will be used. this allows some flexible timing where one might want to refresh constantly with some placeholders... or to refresh only once every minute rather than every few seconds. (default 20)
Control placeholders:
{is_paused} a boolean based on cmus status
{is_playing} a boolean based on cmus status
{is_started} a boolean based on cmus status
{is_stopped} a boolean based on cmus status
{continue} a boolean based on data status
{play_library} a boolean based on data status
{play_sorted} a boolean based on data status
{repeat} a boolean based on data status
{repeat_current} a boolean based on data status
{replaygain} a boolean based on data status
{replaygain_limit} a boolean based on data status
{shuffle} a boolean based on data status
{softvol} a boolean based on data status
{stream} a boolean based on data status
Format placeholders:
{aaa_mode} shuffle mode, eg artist, album, all
{albumartist} album artist, eg (new output here)
{album} album name, eg (new output here)
{artist} artist name, eg (new output here)
{bitrate} audio bitrate, eg 229
{comment} comment, eg URL
{date} year number, eg 2015
{duration} length time in seconds, eg 171
{durationtime} length time in [HH:]MM:SS, eg 02:51
{file} file location, eg /home/user/Music...
{position} elapsed time in seconds, eg 17
{positiontime} elapsed time in [HH:]MM:SS, eg 00:17
{replaygain_preamp} replay gain preamp, eg 0.000000
{status} playback status, eg playing, paused, stopped
{title} track title, eg (new output here)
{tracknumber} track number, eg 0
{vol_left} left volume number, eg 90
{vol_right} right volume number, eg 90
Placeholders are retrieved directly from cmus-remote --query command. The list was harvested only once and should not represent a full list.
Color options:
color_paused Paused, defaults to color_degraded
color_playing Playing, defaults to color_good
color_stopped Stopped, defaults to color_bad
Requires:
cmus a small feature-rich ncurses-based music playerauthor lasers
"},{"location":"user-guide/modules/#coin_balance","title":"coin_balance","text":"Display balances of diverse crypto-currencies.
This module grabs your current balance of different crypto-currents from a wallet server. The server must conform to the bitcoin RPC specification. Currently Bitcoin, Dogecoin, and Litecoin are supported.
Configuration parameters:
cache_timeout An integer specifying the cache life-time of the output in seconds (default 30)
coin_password A string containing the password for the server for 'coin'. The 'coin' part must be replaced by a supported coin identifier (see below for a list of identifiers). If no value is supplied, the value of 'password' (see below) will be used. If 'password' too is not set, the value will be retrieved from the standard 'coin' daemon configuration file. (default None)
coin_username A string containing the username for the server for 'coin'. The 'coin' part must be replaced by a supported coin identifier (see below for a list of identifiers). If no value is supplied, the value of 'username' (see below) will be used. If 'username' too is not set, the value will be retrieved from the standard 'coin' daemon configuration file. (default None)
credentials (default None)
format A string describing the output format for the module. The {<coin>} placeholder (see below) will be used to determine how to fetch the coin balance. Multiple placeholders are allowed, but all balances will be fetched from the same host. (default 'LTC: {litecoin}')
host The coin-server hostname. Note that all coins will use the same host for their queries. (default 'localhost')
password A string containing the password for all coin-servers. If neither this setting, nor a specific coin_password (see above) is specified, the password for each coin will be read from the respective standard daemon configuration file. (default None)
protocol A string to select the server communication protocol. (default 'http')
username A string containing the username for all coin-servers. If neither this setting, nor a specific coin_username (see above) is specified, the username for each coin will be read from the respective standard daemon configuration file. (default None)
Format placeholders:
{<coin>} Your balance for the coin <coin> where <coin> is one of:Requires:
requests python module from pypi https://pypi.python.org/pypi/requests At least version 2.4.2 is required.Examples:
# Get your Bitcoin balance using automatic credential detection\ncoin_balance {\n cache_timeout = 45\n format = \"My BTC: {bitcoin}\"\n host = \"localhost\"\n protocol = \"http\"\n}\n\n# Get your Bitcoin, Dogecoin and Litecoin balances using specific credentials\n# for Bitcoin and automatic detection for Dogecoin and Litecoin\ncoin_balance {\n # ...\n format = \"{bitcoin} BTC {dogecoin} XDG {litecoin} LTC\"\n bitcoin_username = \"lcdata\"\n bitcoin_password = \"omikron-theta\"\n # ...\n}\n\n# Get your Dogecoin and Litecoin balances using 'global' credentials\ncoin_balance {\n # ...\n format = \"XDG: {dogecoin} LTC: {litecoin}\"\n username = \"crusher_b\"\n password = \"WezRulez\"\n # ...\n}\n\n# Get you Dogecoin, Litecoin, and Bitcoin balances by using 'global'\n# credentials for Bitcoin and Dogecoin but specific credentials for\n# Litecoin.\ncoin_balance {\n # ...\n format = \"XDG: {dogecoin} LTC: {litecoin} BTC: {bitcoin}\"\n username = \"zcochrane\"\n password = \"sunny_islands\"\n litecoin_username = 'locutus'\n litecoin_password = 'NCC-1791-D'\n # ...\n}\nauthor Felix Morgner <felix.morgner@gmail.com>
license 3-clause-BSD
"},{"location":"user-guide/modules/#coin_market","title":"coin_market","text":"Display cryptocurrency coins.
The site offer various types of data such as name, symbol, price, volume, total supply, et cetera for a wide range of cryptocurrencies in various currencies. For more information, visit https://coinmarketcap.com
Configuration parameters:
api_key specify CoinMarketCap api key (default None)
cache_timeout refresh interval for this module. a message from the site: please limit requests to no more than 30 calls per minute. (default 600)
format display format for this module (default '{format_coin}')
format_coin display format for coins (default '{name} ${usd_price:.2f} ' '[\\?color=usd_percent_change_24h {usd_percent_change_24h:.1f}%]')
format_coin_separator show separator if more than one (default ' ')
markets specify a list of markets (default ['btc', 'eth'])
thresholds specify color thresholds to use (default [(-100, 'bad'), (0, 'good')])
Format placeholders:
{format_coin} format for cryptocurrency coinsformat_coin placeholders:
{circulating_supply} eg 17906012
{cmc_rank} eg 1
{date_added} eg 2013-04-28T00:00:00.000Z
{id} eg 1
{is_active} eg 1
{is_fiat} eg 0
{is_market_cap_included_in_calc} eg 1
{last_updated} eg 2019-08-30T18:51:28.000Z
{max_supply} eg 21000000
{name} eg Bitcoin
{num_market_pairs} eg 7919
{platform} eg None
{slug} eg bitcoin
{symbol} eg BTC
{tags} eg ['mineable']
{total_supply} eg 17906012
Placeholders are retrieved directly from the URL. The list was harvested once and should not represent a full list.
To print coins in different currencies, replicate the placeholders below with valid options (eg '{gbp_price:.2f}'):
{xxx_last_updated} eg 2019-08-30T18:51:28.000Z' {xxx_market_cap} eg 171155540318.86005 {xxx_percent_change_1h} eg -0.127291 {xxx_percent_change_24h} eg 0.328918 {xxx_percent_change_7d} eg -8.00576 {xxx_price} eg 9558.55163723 {xxx_volume_24h} eg 13728947008.2722
See https://coinmarketcap.com/api/documentation/v1/#section/Standards-and-Conventions for valid options, otherwise USD... in lowercase.
Color thresholds:
xxx print a color based on the value of xxx placeholderExamples:
# view coins in GBP and EUR\ncoin_market {\n format_coin = \"{name} \u00a3{gbp_price:.2f} \u20ac{eur_price:.2f}\"\n}\n\n# colorize market names + symbols\ncoin_market {\n format_coin = \"[\\?color=name {name}] \"\n format_coin += \"[\\?color=symbol {symbol}] ${usd_price:.2f} \"\n format_coin += \"[\\?color=usd_percent_change_24h {usd_percent_change_24h}%]\"\n markets = [\"btc\", \"eth\", \"ltc\", \"doge\"]\n thresholds = {\n \"name\": [\n (\"Bitcoin\", \"greenyellow\"),\n (\"Ethereum\", \"deepskyblue\"),\n (\"Litecoin\", \"crimson\"),\n (\"Dogecoin\", \"orange\"),\n ],\n \"symbol\": [\n (\"BTC\", \"darkgray\"),\n (\"ETH\", \"darkgray\"),\n (\"LTC\", \"darkgray\"),\n (\"DOGE\", \"darkgray\"),\n ],\n \"usd_percent_change_24h\": [(-100, \"bad\"), (0, \"good\")],\n }\n}\nauthor lasers, x86kernel
"},{"location":"user-guide/modules/#conky","title":"conky","text":"Display Conky objects/variables on the bar.
Configuration parameters:
config specify configuration settings for conky (default {})
format display format for this module (default None)
thresholds specify color thresholds to use (default [])
Format placeholders: According to man page, Conky has more than 250 built-in objects/variables.
See `man -P 'less -p OBJECTS/VARIABLES' conky` for a full list of Conky\nobjects/variables to use. Not all of Conky objects/variables will be\nsupported or usable.\nColor thresholds:
xxx print a color based on the value of xxx placeholder Replace spaces with periods.Examples:
# add conky config options\n# See `man -P \"less -p 'CONFIGURATION SETTINGS'\" conky` for a full list\n# of Conky configuration options. Not all of Conky configuration options\n# will be supported or usable.\nconky {\n config = {\n 'update_interval': 10 # update interval for conky\n 'update_interval_on_battery': 60 # update interval when on battery\n 'format_human_readable': True, # if False, print in bytes\n 'short_units': True, # shortens units, eg kiB->k, GiB->G\n 'uppercase': True, # upper placeholders\n }\n}\n\n# display ip address\norder += \"conky addr\"\nconky addr {\n format = 'IP [\\?color=orange {addr eno1}]'\n}\n\n# display load averages\norder += \"conky loadavg\"\nconky loadavg {\n format = 'Loadavg '\n format += '[\\?color=lightgreen {loadavg 1} ]'\n format += '[\\?color=lightgreen {loadavg 2} ]'\n format += '[\\?color=lightgreen {loadavg 3}]'\n}\n\n# exec commands at different intervals, eg 5s, 60s, and 3600s\norder += \"conky date\"\nconky date {\n format = 'Exec '\n format += '[\\?color=good {execi 5 \"date\"}] '\n format += '[\\?color=degraded {execi 60 \"uptime -p\"}] '\n format += '[\\?color=bad {execi 3600 \"uptime -s\"}]'\n}\n\n# display diskio read, write, etc\norder += \"conky diskio\"\nconky diskio {\n format = 'Disk IO [\\?color=darkgray&show sda] '\n format += '[\\?color=lightskyblue '\n format += '{diskio_read sda}/{diskio_write sda} '\n format += '({diskio sda})]'\n\n # format += ' '\n # format += '[\\?color=darkgray&show sdb] '\n # format += '[\\?color=lightskyblue '\n # format += '{diskio_read sdb}/{diskio_write sdb} '\n # format += '({diskio sdb})]'\n config = {'short_units': True}\n}\n\n# display total number of processes and running processes\norder += \"conky proc\"\nconky proc {\n format = 'Processes [\\?color=cyan {processes}/{running_processes}]'\n}\n\n# display top 3 cpu (+mem_res) processes\norder += \"conky top_cpu\" {\nconky top_cpu {\n format = 'Top [\\?color=darkgray '\n format += '{top name 1} '\n format += '[\\?color=deepskyblue {top mem_res 1}] '\n format += '[\\?color=lightskyblue {top cpu 1}%] '\n\n format += '{top name 2} '\n format += '[\\?color=deepskyblue {top mem_res 2}] '\n format += '[\\?color=lightskyblue {top cpu 2}%] '\n\n format += '{top name 3} '\n format += '[\\?color=deepskyblue {top mem_res 3}] '\n format += '[\\?color=lightskyblue {top cpu 3}%]]'\n config = {'short_units': True}\n}\n\n# display top 3 memory processes\norder += \"conky top_mem\"\nconky top_mem {\n format = 'Top Mem [\\?color=darkgray '\n format += '{top_mem name 1} '\n format += '[\\?color=yellowgreen {top_mem mem_res 1}] '\n format += '[\\?color=lightgreen {top_mem mem 1}%] '\n\n format += '{top_mem name 2} '\n format += '[\\?color=yellowgreen {top_mem mem_res 2}] '\n format += '[\\?color=lightgreen {top_mem mem 2}%] '\n\n format += '{top_mem name 3} '\n format += '[\\?color=yellowgreen {top_mem mem_res 3}] '\n format += '[\\?color=lightgreen {top_mem mem 3}%]]'\n config = {'short_units': True}\n}\n\n# display memory, memperc, membar + thresholds\norder += \"conky memory\"\nconky memory {\n format = 'Memory [\\?color=lightskyblue {mem}/{memmax}] '\n format += '[\\?color=memperc {memperc}% \\[{membar}\\]]'\n thresholds = [\n (0, 'darkgray'), (0.001, 'good'), (50, 'degraded'),\n (75, 'orange'), (85, 'bad')\n ]\n}\n\n# display swap, swapperc, swapbar + thresholds\norder += \"conky swap\"\nconky swap {\n format = 'Swap [\\?color=lightcoral {swap}/{swapmax}] '\n format += '[\\?color=swapperc {swapperc}% \\[{swapbar}\\]]'\n thresholds = [\n (0, 'darkgray'), (0.001, 'good'), (50, 'degraded'),\n (75, 'orange'), (85, 'bad')\n ]\n}\n\n# display up/down speed and up/down total\norder += \"conky network\"\nconky network {\n format = 'Speed [\\?color=title {upspeed eno1}/{downspeed eno1}] '\n format += 'Total [\\?color=title {totalup eno1}/{totaldown eno1}]'\n color_title = '#ff6699'\n}\n\n# display file systems + thresholds\norder += \"conky filesystem\"\nconky filesystem {\n # home filesystem\n format = 'Home [\\?color=violet {fs_used /home}/{fs_size /home} '\n format += '[\\?color=fs_used_perc./home '\n format += '{fs_used_perc /home}% \\[{fs_bar /home}\\]]]'\n\n # hdd filesystem\n # format += ' HDD [\\?color=violet {fs_used '\n # format += '/run/media/user/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\n # format += '}/{fs_size '\n # format += '/run/media/user/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\n # format += '}[\\?color=fs_used_perc.'\n # format += '/run/media/user/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\n # format += ' {fs_used_perc '\n # format += '/run/media/user/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\n # format += '}% \\[{fs_bar '\n # format += '/run/media/user/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\n # format += '}\\]]]'\n\n thresholds = [\n (0, 'darkgray'), (0.001, 'good'), (50, 'degraded'),\n (75, 'orange'), (85, 'bad')\n ]\n}\n\n# show cpu percents/bars + thresholds\norder += \"conky cpu\"\nconky cpu {\n format = 'CPU '\n format += '[\\?color=cpu.cpu0 {cpu cpu0}% {cpubar cpu0}] '\n format += '[\\?color=cpu.cpu1 {cpu cpu1}% {cpubar cpu1}] '\n format += '[\\?color=cpu.cpu2 {cpu cpu2}% {cpubar cpu2}] '\n format += '[\\?color=cpu.cpu3 {cpu cpu3}% {cpubar cpu3}]'\n\n thresholds = [\n (0, 'darkgray'), (0.001, 'good'), (50, 'degraded'),\n (75, 'orange'), (85, 'bad')\n ]\n}\n\n# show more examples, many outputs\norder += \"conky info\"\nconky info {\n format = '[\\?color=title&show OS] [\\?color=output {distribution}] '\n format += '[\\?color=title&show CPU] [\\?color=output {cpu cpu0}%] '\n format += '[\\?color=title&show MEM] '\n format += '[\\?color=output {mem}/{memmax} ({memperc}%)] '\n format += '[\\?color=title&show HDD] [\\?color=output {fs_used_perc}%] '\n format += '[\\?color=title&show Kernel] [\\?color=output {kernel}] '\n format += '[\\?color=title&show Loadavg] [\\?color=output {loadavg 1}] '\n format += '[\\?color=title&show Uptime] [\\?color=output {uptime}] '\n format += '[\\?color=title&show Freq GHZ] [\\?color=output {freq_g}]'\n color_title = '#ffffff'\n color_output = '#00bfff'\n}\n\n# change console bars - shoutout to su8 for adding this\nconky {\n config = {\n 'console_bar_fill': \"'#'\",\n 'console_bar_unfill': \"'_'\",\n 'default_bar_width': 10,\n }\n}\n\n# display nvidia stats - shoutout to brndnmtthws for fixing this\n# See `man -P 'less -p nvidia\\ argument' conky` for more nvidia variables.\norder += \"conky nvidia\"\nconky nvidia {\n format = 'GPU Temp [\\?color=greenyellow {nvidia temp}] '\n format += 'GPU Freq [\\?color=greenyellow {nvidia gpufreq}] '\n format += 'Mem Freq [\\?color=greenyellow {nvidia memfreq}] '\n format += 'MTR Freq [\\?color=greenyellow {nvidia mtrfreq}] '\n format += 'Perf [\\?color=greenyellow {nvidia perflevel}] '\n format += 'Mem Perc [\\?color=greenyellow {nvidia memperc}]'\n config = {\n 'nvidia_display': \"':0'\"\n }\n}\nauthor lasers
"},{"location":"user-guide/modules/#deadbeef","title":"deadbeef","text":"Display songs currently playing in DeaDBeeF.
Configuration parameters:
cache_timeout refresh interval for this module (default 5)
format display format for this module (default '[{artist} - ][{title}]')
replacements specify a list/dict of string placeholders to modify (default None)
sleep_timeout when deadbeef is not running, this interval will be used to allow faster refreshes with time-related placeholders and/or to refresh few times per minute rather than every few seconds (default 20)
Format placeholders:
{album} name of the album
{artist} name of the artist
{length} length time in [HH:]MM:SS
{playback_time} elapsed time in [HH:]MM:SS
{title} title of the track
{tracknumber} track number in two digits
{year} year in four digits
For more placeholders, see title formatting 2.0 in 'deadbeef --help' or https://github.com/DeaDBeeF-Player/deadbeef/wiki/Title-formatting-2.0 Not all of Foobar2000 remapped metadata fields will work with deadbeef and a quick reminder about using {placeholders} here instead of %placeholder%.
Color options:
color_paused Paused, defaults to color_degraded
color_playing Playing, defaults to color_good
color_stopped Stopped, defaults to color_bad
Requires:
deadbeef a GTK+ audio player for GNU/LinuxExamples:
# see 'deadbeef --help' for more buttons\ndeadbeef {\n on_click 1 = 'exec deadbeef --play-pause'\n on_click 8 = 'exec deadbeef --random'\n}\nauthor mrt-prodz
"},{"location":"user-guide/modules/#dexcom","title":"dexcom","text":"Display glucose readings from your Dexcom CGM system.
Dexcom CGM systems provide glucose readings up to every five minutes. Designed to help diabetes patients keep track of their blood glucose levels with ease.
Configuration parameters:
format display format for this module (default \"Dexcom [\\?color=mg_dl {mg_dl} mg/dL {trend_arrow}] [\\?color=darkgrey {datetime}]\")
format_datetime specify strftime characters to format (default {\"datetime\": \"%-I:%M %p\"})
ous specify whether if the Dexcom Share user is outside of the US (default False)
password specify password for the Dexcom Share user (default None)
thresholds specify color thresholds to use (default { \"mg_dl\": [(55, \"bad\"), (70, \"degraded\"), (80, \"good\"), (130, \"degraded\"), (180, \"bad\")], \"mmol_l\": [(3.1, \"bad\"), (3.9, \"degraded\"), (4.4, \"good\"), (7.2, \"degraded\"), (10.0, \"bad\")], })
username specify username for the Dexcom Share user, not follower (default None)
Format placeholders:
{mg_dl} blood glucose value in mg/dL, eg 80
{mmol_l} blood glucose value in mmol/L, eg 4.4
{trend} blood glucose trend information, eg 4
{trend_direction} blood glucose trend direction, eg Flat
{trend_description} blood glucose trend information description, eg steady
{trend_arrow} blood glucose trend as unicode arrow, eg \u2192
{datetime} glucose reading recorded time as datetime
format_datetime placeholders:
key epoch_placeholder, eg {datetime}
value % strftime characters to be translated, eg '%b %d' ----> 'Jan 1'
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
pydexcom A simple Python API to interact with Dexcom Share serviceNotes: IF GLUCOSE ALERTS AND CGM READINGS DO NOT MATCH SYMPTOMS OR EXPECTATIONS, USE A BLOOD GLUCOSE METER TO MAKE DIABETES TREATMENT DECISIONS.
Examples:
# compact\ndexcom {\n format = \"[\\?color=mg_dl {mg_dl} {trend_arrow}][\\?color=darkgrey {datetime}]\"\n format_datetime = {\"datetime\": \"%-I:%M\"}\n}\nauthor lasers
"},{"location":"user-guide/modules/#diskdata","title":"diskdata","text":"Display disk information.
Configuration parameters:
cache_timeout refresh interval for this module. (default 10)
disk show stats for disk or partition, i.e. sda1. None for all disks. (default None)
format display format for this module. (default \"{disk}: {used_percent}%[ ({total})]\")
format_rate display format for rates value (default \"[\\?min_length=11 {value:.1f} {unit}]\")
format_space display format for disk space values (default \"[\\?min_length=5 {value:.1f}]\")
sector_size size of the disk's sectors. (default 512)
si_units use SI units (default False)
thresholds specify color thresholds to use (default {'free': [(0, 'bad'), (10, 'degraded'), (100, 'good')], 'total': [(0, 'good'), (1024, 'degraded'), (1024 * 1024, 'bad')], 'used_percent': [(0, 'good'), (40, 'degraded'), (75, 'bad')]})
unit unit to use. If the unit contains a multiplier prefix, only this exact unit will ever be used (default \"B/s\")
Format placeholders:
{disk} the selected disk
{free} free space on disk in GB
{used} used space on disk in GB
{total_space} total space on disk in GB
{used_percent} used space on disk in %
{read} reading rate
{total} total IO rate
{write} writing rate
format_rate placeholders:
{unit} name of the unit
{value} numeric value of the rate
format_space placeholders:
{value} numeric value of the free/used space on the deviceColor thresholds:
{free} Change color based on the value of free
{used} Change color based on the value of used
{used_percent} Change color based on the value of used_percent
{read} Change color based on the value of read
{total} Change color based on the value of total
{write} Change color based on the value of write
author guiniol
license BSD
"},{"location":"user-guide/modules/#do_not_disturb","title":"do_not_disturb","text":"Turn on and off desktop notifications.
Configuration parameters:
cache_timeout refresh interval for this module; for xfce4-notifyd (default 30)
format display format for this module (default '{name} [\\?color=state&show DND]')
pause specify whether to pause or kill processes; for dunst see Dunst Miscellaneous section for more information (default True)
server specify server to use, eg mako, dunst or xfce4-notifyd, otherwise auto (default None)
state specify state to use on startup, otherwise last False: disable Do Not Disturb on startup True: enable Do Not Disturb on startup last: toggle last known state on startup None: query current state from notification manager (doesn't work on dunst<1.5.0) (default 'last')
thresholds specify color thresholds to use (default [(0, 'bad'), (1, 'good')])
Format placeholders:
{name} name, eg Mako, Dunst, Xfce4-notifyd
{state} do not disturb state, eg 0, 1
Color thresholds:
xxx print a color based on the value of xxx placeholderDunst Miscellaneous: When paused, dunst will not display any notifications but keep all notifications in a queue. This can for example be wrapped around a screen locker (i3lock, slock) to prevent flickering of notifications through the lock and to read all missed notifications after returning to the computer. This means that by default (pause = False), all notifications sent while DND is active will NOT be queued and displayed when DND is deactivated.
Mako Miscellaneous: Mako requires that you manually create a 'do-not-disturb' mode as shown in https://man.voidlinux.org/mako.5#MODES. This module expects this mode to be configured by the user as suggested by the mako documentation: [mode=do-not-disturb] invisible=1
Examples:
# display ON/OFF\ndo_not_disturb {\n format = '{name} [\\?color=state [\\?if=state ON|OFF]]'\n}\n\n# display 1/0\ndo_not_disturb {\n format = '{name} [\\?color=state {state}]'\n}\n\n# display DO NOT DISTURB/DISTURB\ndo_not_disturb {\n format = '[\\?color=state [\\?if=state DO NOT DISTURB|DISTURB]]'\n thresholds = [(0, \"darkgray\"), (1, \"good\")]\n}\nauthor Maxim Baz https://github.com/maximbaz (dunst)
author Robert Ricci https://github.com/ricci (xfce4-notifyd)
author Cyrinux https://github.com/cyrinux (mako)
license BSD
"},{"location":"user-guide/modules/#dpms","title":"dpms","text":"Turn on and off DPMS and screen saver blanking.
Configuration parameters:
button_off mouse button to turn off screen (default None)
button_toggle mouse button to toggle DPMS (default 1)
cache_timeout refresh interval for this module (default 15)
format display format for this module (default '{icon}')
icon_off show when DPMS is disabled (default 'DPMS')
icon_on show when DPMS is enabled (default 'DPMS')
Format placeholders:
{icon} DPMS iconColor options:
color_on Enabled, defaults to color_good
color_off Disabled, defaults to color_bad
author Andre Doser <dosera AT tf.uni-freiburg.de>
"},{"location":"user-guide/modules/#dropboxd_status","title":"dropboxd_status","text":"Display status of Dropbox daemon.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default \"Dropbox: {status}\")
status_busy text for placeholder {status} when Dropbox is busy (default None)
status_off text for placeholder {status} when Dropbox isn't running (default \"isn't running\")
status_on text for placeholder {status} when Dropbox is up to date (default \"Up to date\")
Value for status_off if not set: - Dropbox isn't running!
Value for status_on if not set: - Up to date
Values for status_busy if not set: - Connecting... - Starting... - Downloading file list... - Syncing \"filename\"
Format placeholders:
{status} Dropbox statusColor options:
color_bad Not running
color_degraded Busy
color_good Up to date
Requires:
dropbox-cli command line interface for dropboxNotes: Some distributions offer an option to install dropbox-cli. If you don't see one for your distribution, then you need to download CLI Python script, https://www.dropbox.com/help/desktop-web/linux-commands#commands, rename it to dropbox-cli, make the script executable and available in your PATH.
author Tjaart van der Walt (github:tjaartvdwalt)
license BSD
"},{"location":"user-guide/modules/#emerge_status","title":"emerge_status","text":"Display information about the currently running emerge process.
Configuration parameters:
cache_timeout how often we refresh this module in second. NOTE: when emerge is running, we will refresh this module every second. (default 30)
emerge_log_file path to the emerge log file. (default '/var/log/emerge.log')
format display format for this module (default '{prefix}[\\?if=is_running : [\\?if=!total=0 ' '[{current}/{total} {action} {category}/{pkg}]' '|calculating...]|: stopped 0/0]')
prefix prefix in statusbar (default \"emrg\")
Format placeholders:
{action} current emerge action
{category} category of the currently emerged package
{current} number of package that is currently emerged
{pkg} name of the currently emerged packaged
{total} total number of packages that will be emerged
Examples:
# Hide if not running\nemerge_status {\n format = \"[\\?if=is_running {prefix}: [\\?if=!total=0 \"\n format += \"{current}/{total} {action} {category}/{pkg}\"\n format += \"|calculating...]]\"\n}\n\n# Minimalistic\nemerge_status {\n format = \"[\\?if=is_running [\\?if=!total=0 {current}/{total}]]\"\n}\n\n# Minimalistic II\nemerge_status {\n format = \"[\\?if=is_running {current}/{total}]\"\n}\nauthor AnwariasEu
"},{"location":"user-guide/modules/#exchange_rate","title":"exchange_rate","text":"Display foreign exchange rates.
Configuration parameters:
api_key the exchangeratesapi.io API access key (default None)
base specify base currency to use for exchange rates (default 'EUR')
cache_timeout refresh interval for this module (default 600)
format display format for this module (default '${USD} \u00a3{GBP} \u00a5{JPY}')
Format placeholders: See https://api.exchangeratesapi.io/latest for a full list of foreign exchange rates published by the European Central Bank. Not all of exchange rates will be available. Also, see https://en.wikipedia.org/wiki/ISO_4217
author tobes
license BSD
"},{"location":"user-guide/modules/#external_script","title":"external_script","text":"Display output of a given script.
Display output of any executable script set by script_path. Only the first two lines of output will be used. The first line is used as the displayed text. If the output has two or more lines, the second line contains additional information as whitespace separated tokens. Valid tokens are: #rrggbb: the text color as a hex color code (eg. #FF0000 for red) urgent: the word urgent to set the urgent flag The script should not have any parameters, but it could work.
Configuration parameters:
button_show_notification button to show notification with full output (default None)
cache_timeout how often we refresh this module in seconds (default 15)
convert_numbers convert decimal numbers to a numeric type (default True)
format see placeholders below (default '{output}')
localize should script output be localized (if available) (default True)
script_path script you want to show output of (compulsory) (default None)
strip_output shall we strip leading and trailing spaces from output (default False)
Format placeholders:
{lines} number of lines in the output
{output} output of script given by \"script_path\"
{composite} composite output of script given by \"script_path\"
Examples:
external_script {\n format = \"my name is {output}\"\n script_path = \"/usr/bin/whoami\"\n}\nauthor frimdo ztracenastopa@centrum.cz
"},{"location":"user-guide/modules/#fedora_updates","title":"fedora_updates","text":"Display number of pending updates for Fedora Linux.
This will display a count of how many dnf updates are waiting to be installed. Additionally check for update security notices.
Configuration parameters:
cache_timeout How often we refresh this module in seconds (default 600)
check_security Check for security updates (default True)
format Display format to use (default 'DNF: {updates}')
Format placeholders:
{updates} number of pending dnf updatesColor options:
color_bad Security notice
color_degraded Upgrade available
color_good No upgrades needed
author tobes
license BSD
"},{"location":"user-guide/modules/#file_status","title":"file_status","text":"Display if files or directories exists.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '\\?color=path [\\?if=path \u25cf|\u25a0]')
format_path format for paths (default '{basename}')
format_path_separator show separator if more than one (default ' ')
paths specify a string or a list of paths to check (default None)
thresholds specify color thresholds to use (default [(0, 'bad'), (1, 'good')])
Format placeholders:
{format_path} format for paths
{path} number of paths, eg 1, 2, 3
format_path placeholders:
{basename} basename of pathname
{pathname} pathname
Color options:
color_bad files or directories does not exist
color_good files or directories exists
Color thresholds:
format path: print a color based on the number of pathsExamples:
# add multiple paths with wildcard or with pathnames\nfile_status {\n paths = ['/tmp/test*', '~user/test1', '~/Videos/*.mp4']\n}\n\n# colorize basenames\nfile_status {\n paths = ['~/.config/i3/modules/*.py']\n format = '{format_path}'\n format_path = '\\?color=good {basename}'\n format_path_separator = ', '\n}\nauthor obb, Moritz L\u00fcdecke, Cyril Levis (@cyrinux)
"},{"location":"user-guide/modules/#frame","title":"frame","text":"Group modules and treat them as a single one.
This can be useful for example when adding modules to a group and you wish two modules to be shown at the same time.
By adding the {button} placeholder in the format you can enable a toggle button to hide or show the content.
Configuration parameters:
button_toggle Button used to toggle if one in format. Setting to None disables (default 1)
format Display format to use (default '{output}')
format_button_closed Format for the button when frame open (default '+')
format_button_open Format for the button when frame closed (default '-')
format_separator Specify separator between contents. If this is None then the default i3bar separator will be used (default None)
open If button then the frame can be set to be open or close (default True)
Format placeholders:
{button} If used a button will be used that can be clicked to hide/show the contents of the frame.
{output} The output of the modules in the frame
{output_xxx} The output of the module xxx (even if the button is currently toggled off).
Examples:
# A frame showing times in different cities.\n# We also have a button to hide/show the content\nframe time {\n format = '{output}{button}'\n format_separator = ' ' # have space instead of usual i3bar separator\n\n tztime la {\n format = \"LA %H:%M\"\n timezone = \"America/Los_Angeles\"\n }\n tztime ny {\n format = \"NY %H:%M\"\n timezone = \"America/New_York\"\n }\n tztime du {\n format = \"DU %H:%M\"\n timezone = \"Asia/Dubai\"\n }\n}\n\n# Define a group which shows volume and battery info or the current time.\n# The frame, volume_status and battery_level modules are named to prevent\n# them clashing with any other defined modules of the same type.\ngroup {\n frame {\n volume_status {}\n battery_level {}\n }\n time {}\n}\n\n# Define a group where the button is colored only if sub module has some output\nframe ipv6 {\n format = \"[\\?if=output_ipv6 {output}{button}|\\?color=#bad {output}{button}]\"\n open = false\n\n ipv6 {\n format_up = \"%ip\"\n format_down = \"\"\n }\n}\nauthor tobes
"},{"location":"user-guide/modules/#getjson","title":"getjson","text":"Display JSON data fetched from a URL.
This module gets the given url configuration parameter and assumes the response is a JSON object. The keys of the JSON object are used as the format placeholders. The format placeholders are replaced by the value. Objects that are nested can be accessed by using the delimiter configuration parameter in between.
Configuration parameters:
cache_timeout refresh interval for this module (default 30)
delimiter the delimiter between parent and child objects (default '-')
format display format for this module (default None)
password basic auth password information (default None)
url specify URL to fetch JSON from (default None)
username basic auth user information (default None)
Format placeholders: Placeholders will be replaced by the JSON keys.
Placeholders for objects with sub-objects are flattened using 'delimiter'\nin between (eg. {'parent': {'child': 'value'}} will use placeholder\n{parent-child}).\n\nPlaceholders for list elements have 'delimiter' followed by the index\n(eg. {'parent': ['this', 'that']) will use placeholders {parent-0}\nfor 'this' and {parent-1} for 'that'.\nExamples:
# straightforward key replacement\ngetjson {\n url = \"https://ifconfig.co/json\"\n format = \"{latitude}, {longitude}\"\n}\n\n# access child objects\ngetjson {\n url = 'https://api.icndb.com/jokes/random'\n format = '{value-joke}'\n}\n\n# access title from 0th element of articles list\ngetjson {\n url = 'https://newsapi.org/v1/articles?source=bbc-news&sortBy=top&apiKey={KEY}'\n format = '{articles-0-title}'\n}\n\n# access if top-level object is a list\ngetjson {\n url = 'https://jsonplaceholder.typicode.com/posts/1/comments'\n format = '{0-name}'\n}\nauthor vicyap
"},{"location":"user-guide/modules/#github","title":"github","text":"Display Github notifications and issue/pull requests for a repo.
To check notifications a Github username and personal access token are required. You can create a personal access token at https://github.com/settings/tokens/new?scopes=notifications&description=py3status The only scope needed is notifications is selected automatically for you, which provides readonly access to notifications.
The Github API is rate limited so setting cache_timeout too small may cause issues see https://developer.github.com/v3/#rate-limiting for details
Configuration parameters:
auth_token Github personal access token, needed to check notifications see above. (default None)
button_action Button that when clicked opens the Github notification page if notifications, else the project page for the repository if there is one (otherwise the github home page). Setting to None disables. (default 3)
button_refresh Button that when clicked refreshes module. Setting to None disables. (default 2)
cache_timeout How often we refresh this module in seconds (default 60)
format display format for this module, see Examples below (default None)
format_notifications Format of {notification} status placeholder. (default ' N{notifications_count}')
notifications Type of notifications can be all for all notifications or repo to only get notifications for the repo specified. If repo is not provided then all notifications will be checked. (default 'all')
repo Github repo to check (default 'ultrabug/py3status')
url_api Change only if using Enterprise Github, example https://github.domain.com/api/v3. (default 'https://api.github.com')
url_base Change only if using Enterprise Github, example https://github.domain.com. (default 'https://github.com')
username Github username, needed to check notifications. (default None)
Format placeholders:
{issues} Number of open issues.
{notifications} Notifications. If no notifications this will be empty.
{notifications_count} Number of notifications. This is also the Only placeholder available to format_notifications.
{pull_requests} Number of open pull requests
{repo} short name of the repository being checked. eg py3status
{repo_full} full name of the repository being checked. eg ultrabug/py3status
Examples:
# default formats\ngithub {\n # with username and auth_token, this will be used\n format = '{repo} {issues}/{pull_requests}{notifications}'\n\n # otherwise, this will be used\n format '{repo} {issues}/{pull_requests}'\n}\n\n# set github access credentials\ngithub {\n auth_token = '40_char_hex_access_token'\n username = 'my_username'\n}\n\n# just check for any notifications\ngithub {\n auth_token = '40_char_hex_access_token'\n username = 'my_username'\n format = 'Github {notifications_count}'\n}\nauthor tobes
"},{"location":"user-guide/modules/#gitlab","title":"gitlab","text":"Display number of issues, requests and more from a GitLab project.
A token is required. See https://gitlab.com/profile/personal_access_tokens to make one. Make a name, eg py3status, and enable api in scopes. Save.
Configuration parameters:
auth_token specify a personal access token to use (default None)
button_open mouse button to open project url (default 1)
button_refresh mouse button to refresh this module (default 2)
cache_timeout refresh interval for this module (default 900)
format display format for this module (default '[{name} ][[{open_issues_count}][\\?soft /]' '[{open_merge_requests_count}]]')
project specify a project to use (default 'gitlab-org/gitlab-ce')
thresholds specify color thresholds to use (default [])
Format placeholders: See sp below for a full list of supported GitLab placeholders to use. Not all of GitLab placeholders will be usable.
single_project:\n {name} project name, eg py3status\n {star_count} number of stars, eg 2\n {forks_count} number of forks, eg 3\n {open_issues_count} number of open issues, eg 4\n {statistics_commit_count} number of commits, eg 5678\nmerge_requests:\n {open_merge_requests_count} number of open merge requests, eg 9\ntodos:\n {todos_count} number of todos, eg 4\npipelines:\n {pipelines_status} project status of pipelines, eg success\nNotes:
sp https://docs.gitlab.com/ee/api/projects.html#get-single-project
mr https://docs.gitlab.com/ee/api/merge_requests.html
td https://docs.gitlab.com/ee/api/todos.html
pipe https://docs.gitlab.com/ee/api/pipelines.html
Color thresholds:
xxx print a color based on the value of xxx placeholderExamples:
# follow a fictional project, add an icon\ngitlab {\n auth_token = 'abcdefghijklmnopq-a4'\n project = 'https://gitlab.com/ultrabug/py3status'\n\n format = '[\\?if=name [\\?color=orangered&show \uf296] {name} ]'\n format += '[[{open_issues_count}][\\?soft /]'\n format += '[{open_merge_requests_count}][\\?soft /]'\n format += '[{pipelines_status}]]'\n}\nauthor lasers, Cyril Levis (@cyrinux)
"},{"location":"user-guide/modules/#glpi","title":"glpi","text":"Display number of open tickets from GLPI.
It features thresholds to colorize the output and forces a low timeout to limit the impact of a server connectivity problem on your i3bar freshness.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 300)
critical set bad color above this threshold (default 20)
db database to use (default '')
format format of the module output (default '{tickets_open} tickets')
host database host to connect to (default '')
password login password (default '')
timeout timeout for database connection (default 5)
user login user (default '')
warning set degraded color above this threshold (default 15)
Format placeholders:
{tickets_open} The number of open ticketsColor options:
color_bad Open ticket above critical threshold
color_degraded Open ticket above warning threshold
Requires: MySQL-python: https://pypi.org/project/MySQL-python/
author ultrabug
"},{"location":"user-guide/modules/#google_calendar","title":"google_calendar","text":"Display upcoming Google Calendar events.
This module will display information about upcoming Google Calendar events in one of two formats which can be toggled with a button press. The event URL may also be opened in a web browser with a button press.
Some events details can be retreived in the Google Calendar API Documentation. https://developers.google.com/calendar/v3/reference/events
Configuration parameters:
auth_token The path to where the access/refresh token will be saved after successful credential authorization. (default '~/.config/py3status/google_calendar.auth_token')
blacklist_events Event names in this list will not be shown in the module (case insensitive). (default [])
browser_invocation Command to run to open browser. Curly braces stands for URL opened. (default \"xdg-open {}\")
button_open Opens the event URL in the default web browser. (default 3)
button_refresh Refreshes the module and updates the list of events. (default 2)
button_toggle Toggles a boolean to hide/show the data for each event. (default 1)
cache_timeout How often the module is refreshed in seconds (default 60)
calendar_id The ID of the calendar to display. (default \"primary\")
client_secret the path to your client_secret file which contains your OAuth 2.0 credentials. (default '~/.config/py3status/google_calendar.client_secret')
events_within_hours Select events within the next given hours. (default 12)
force_lowercase Sets whether to force all event output to lower case. (default False)
format The format for module output. (default '{events}|\\?color=event \u2687')
format_date The format for date related format placeholders. May be any Python strftime directives for dates. (default '%a %d-%m')
format_event The format for each event. The information can be toggled with 'button_toggle' based on the value of 'is_toggled'. (default '[\\?color=event {summary}][\\?if=is_toggled ({start_time}' ' - {end_time}, {start_date})|[ ({location})][ {format_timer}]]')
format_notification The format for event warning notifications. (default '{summary} {start_time} - {end_time}')
format_separator The string used to separate individual events. (default ' | ')
format_time The format for time-related placeholders except {format_timer}. May use any Python strftime directives for times. (default '%I:%M %p')
format_timer The format used for the {format_timer} placeholder to display time until an event starts or time until an event in progress is over. (default '\\?color=time ([\\?if=days {days}d ][\\?if=hours {hours}h ]' '[\\?if=minutes {minutes}m])[\\?if=is_current left]')
ignore_all_day_events Sets whether to display all day events or not. (default False)
num_events The maximum number of events to display. (default 3)
preferred_event_link link to open in the browser. accepted values : hangoutLink (open the VC room associated with the event), htmlLink (open the event's details in Google Calendar) fallback to htmlLink if the preferred_event_link does not exist it the event. (default \"htmlLink\")
response Only display events for which the response status is on the list. Available values in the Google Calendar API's documentation, look for the attendees[].responseStatus. (default ['accepted'])
thresholds Thresholds for events. The first entry is the color for event 1, the second for event 2, and so on. (default [])
time_to_max Threshold (in minutes) for when to display the {format_timer} string; e.g. if time_to_max is 60, {format_timer} will only be displayed for events starting in 60 minutes or less. (default 180)
warn_threshold The number of minutes until an event starts before a warning is displayed to notify the user; e.g. if warn_threshold is 30 and an event is starting in 30 minutes or less, a notification will be displayed. disabled by default. (default 0)
warn_timeout The number of seconds before a warning should be issued again. (default 300)
Control placeholders:
{is_toggled} a boolean toggled by button_toggleFormat placeholders:
{events} All the events to display.format_event and format_notification placeholders:
{description} The description for the calendar event.
{end_date} The end date for the event.
{end_time} The end time for the event.
{location} The location for the event.
{start_date} The start date for the event.
{start_time} The start time for the event.
{summary} The summary (i.e. title) for the event.
{format_timer} The time until the event starts (or until it is over if already in progress).
format_timer placeholders:
{days} The number of days until the event.
{hours} The number of hours until the event.
{minutes} The number of minutes until the event.
Color options:
color_event Color for a single event.
color_time Color for the time associated with each event.
Requires: 1. Python library google-api-python-client. 2. Python library python-dateutil. 3. OAuth 2.0 credentials for the Google Calendar api.
Follow Step 1 of the guide here to obtain your OAuth 2.0 credentials:\nhttps://developers.google.com/google-apps/calendar/quickstart/python\n\nDownload the client_secret.json file which contains your client ID and\nclient secret. In your config file, set configuration parameter\nclient_secret to the path to your client_secret.json file.\n\nThe first time you run the module, a browser window will open asking you\nto authorize access to your calendar. After authorization is complete,\nan access/refresh token will be saved to the path configured in\nauth_token, and i3status will be restarted. This restart will\noccur only once after the first time you successfully authorize.\nExamples:
# add color gradients for events and dates/times\ngoogle_calendar {\n thresholds = {\n 'event': [(1, '#d0e6ff'), (2, '#bbdaff'), (3, '#99c7ff'),\n (4, '#86bcff'), (5, '#62a9ff'), (6, '#8c8cff'), (7, '#7979ff')],\n 'time': [(1, '#ffcece'), (2, '#ffbfbf'), (3, '#ff9f9f'),\n (4, '#ff7f7f'), (5, '#ff5f5f'), (6, '#ff3f3f'), (7, '#ff1f1f')]\n }\n}\nauthor Igor Grebenkov
license BSD
"},{"location":"user-guide/modules/#graphite","title":"graphite","text":"Display Graphite metrics.
Configuration parameters:
cache_timeout how often we refresh this module in seconds. (default 120)
datapoint_selection when multiple data points are returned, use \"max\" or \"min\" to determine which one to display. (default \"max\")
format you MUST use placeholders here to display data, see below. (default '')
graphite_url URL to your graphite server. (default '')
http_timeout HTTP query timeout to graphite. (default 10)
proxy You can configure the proxy with HTTP or HTTPS. examples: proxy = 'https://myproxy.example.com:1234/' proxy = 'http://user:passwd@myproxy.example.com/' proxy = 'socks5://user:passwd@host:port' (proxy_socks is available after an 'pip install requests[socks]') (default None)
targets semicolon separated list of targets to query graphite for. (default '')
threshold_bad numerical threshold, if set will send a notification and colorize the output. (default None)
threshold_degraded numerical threshold, if set will send a notification and colorize the output. (default None)
timespan time range to query graphite for. (default \"-2minutes\")
value_comparator choose between \"max\" and \"min\" to compare thresholds to the data point value. (default \"max\")
value_format pretty format long numbers with \"K\", \"M\" etc. (default True)
value_round round values so they're not displayed as floats. (default True)
Dynamic format placeholders: The \"format\" parameter placeholders are dynamically based on the data points names returned by the \"targets\" query to graphite.
For example if your target is `\"carbon.agents.localhost-a.memUsage\"`,\nyou'd get a JSON result like this:\n\n ```\n {\n \"target\": \"carbon.agents.localhost-a.memUsage\",\n \"datapoints\": [[19693568.0, 1463663040]]\n }\n ```\n\nSo the placeholder you could use on your \"format\" config is:\n `format = \"{carbon.agents.localhost-a.memUsage}\"`\n\nTIP: use aliases !\n ```\n targets = \"alias(carbon.agents.localhost-a.memUsage, 'local_memuse')\"\n format = \"local carbon mem usage: {local_memuse} bytes\"\n ```\nColor options:
color_bad threshold_bad has been exceeded
color_degraded threshold_degraded has been exceeded
author ultrabug
"},{"location":"user-guide/modules/#group","title":"group","text":"Group modules and switch between them.
Groups can be configured in your config. The active one of these groups is shown in the i3bar. The active group can be changed by a user click. If the click is not used by the group module then it will be passed down to the displayed module.
Modules can be i3status core modules or py3status modules. The active group can be cycled through automatically.
The group can handle clicks by reacting to any that are made on it or its content or it can use a button and only respond to clicks on that. The way it does this is selected via the click_mode option.
Configuration parameters:
align Text alignment when fixed_width is set can be 'left', 'center' or 'right' (default 'center')
button_next Button that when clicked will switch to display next module. Setting to 0 will disable this action. (default 5)
button_prev Button that when clicked will switch to display previous module. Setting to 0 will disable this action. (default 4)
button_toggle Button that when clicked toggles the group content being displayed between open and closed. This action is ignored if {button} is not in the format. Setting to 0 will disable this action (default 1)
click_mode This defines how clicks are handled by the group. If set to all then the group will respond to all click events. This may cause issues with contained modules that use the same clicks that the group captures. If set to button then only clicks that are directly on the {button} are acted on. The group will need {button} in its format. (default 'all')
cycle Time in seconds till changing to next module to display. Setting to 0 will disable cycling. (default 0)
fixed_width Reduce the size changes when switching to new group (default False)
format display format for this module, see Examples below (default None)
format_button_closed Format for the button when group open (default '+')
format_button_open Format for the button when group closed (default '-')
format_closed Format for module output when closed. (default \"{button}\")
open Is the group open and displaying its content. Has no effect if {button} not in format (default True)
Format placeholders:
{button} The button to open/close or change the displayed group
{output} Output of current active module
Examples:
# default formats\ngroup {\n format = '{output}' # if click_mode is 'all'\n format = '{output} {button}' # if click_mode is 'button'\n}\n\n# Create a disks group that will show space on '/' and '/home'\n# Change between disk modules every 30 seconds\norder += \"group disks\"\ngroup disks {\n cycle = 30\n format = \"Disks: {output} {button}\"\n click_mode = \"button\"\n\n disk \"/\" {\n format = \"/ %avail\"\n }\n disk \"/home\" {\n format = \"/home %avail\"\n }\n}\nauthor tobes
"},{"location":"user-guide/modules/#hamster","title":"hamster","text":"Display time tracking activities from Hamster.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 10)
format see placeholders below (default '{current}')
Format placeholders:
{current} current activityRequires:
hamster time tracking applicationauthor Aaron Fields (spirotot [at] gmail.com)
license BSD
"},{"location":"user-guide/modules/#hddtemp","title":"hddtemp","text":"Display hard drive temperatures.
hddtemp is a small utility with daemon that gives the hard drive temperature via S.M.A.R.T. (Self-Monitoring, Analysis, and Reporting Technology). This module requires the user-defined hddtemp daemon to be running at all times.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{format_hdd}')
format_hdd display format for hard drives (default '{name} [\\?color=temperature {temperature}\u00b0{unit}]')
format_separator show separator if more than one (default ' ')
thresholds specify color thresholds to use (default [(19, 'skyblue'), (24, 'deepskyblue'), (25, 'lime'), (41, 'yellow'), (46, 'orange'), (51, 'red'), (56, 'tomato')])
Format placeholders:
{format_hdd} format for hard drivesformat_hdd placeholders:
{name} name, eg ADATA SP550
{path} path, eg /dev/sda
{temperature} temperature, eg 32
{unit} temperature unit, eg C
Temperatures: Less than 25\u00b0C: Too cold (color deepskyblue) 25\u00b0C to 40\u00b0C: Ideal (color good) 41\u00b0C to 50\u00b0C: Acceptable (color degraded) 46\u00b0C to 50\u00b0C: Almost too hot (color orange) More than 50\u00b0C: Too hot (color bad)
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
hddtemp utility to monitor hard drive temperatures
nc netcat / ncat is command-line utility for reading data from hddtemp telnet interface
Bible of HDD failures: Hard disk temperatures higher than 45\u00b0C led to higher failure rates. Temperatures lower than 25\u00b0C led to higher failure rates as well. Aging hard disk drives (3 years and older) were much more prone to failure when their average temperatures were 40\u00b0C and higher.
Hard disk manufacturers often state the operating temperatures of\ntheir hard disk drives to be between 0\u00b0C to 60\u00b0C. This can be misleading\nbecause what they mean is that your hard disk will function at these\ntemperatures, but it doesn't tell you anything about how long they are\ngoing to survive at this range.\nhttp://www.buildcomputers.net/hdd-temperature.html\nBackblaze: Overall, there is not a correlation between operating temperature and failure rates The one exception is the Seagate Barracuda 1.5TB drives, which fail slightly more when they run warmer. As long as you run drives well within their allowed range of operating temperatures, keeping them cooler doesn\u2019t matter. https://www.backblaze.com/blog/hard-drive-temperature-does-it-matter/
Examples:
# compact the format\nhddtemp {\n format = 'HDD {format_hdd}'\n format_hdd = '\\?color=temperature {temperature}\u00b0C'\n}\n\n# show paths instead of names\nhddtemp {\n format_hdd = '{path} [\\?color=temperature {temperature}\u00b0{unit}]'\n}\n\n# show more colors\nhddtemp {\n gradients = True\n}\nauthor lasers
"},{"location":"user-guide/modules/#hueshift","title":"hueshift","text":"Shift color temperature on the screen.
Configuration parameters:
button_down mouse button to decrease color temperature (default 5)
button_toggle mouse button to toggle color temperature (default 1)
button_up mouse button to increase color temperature (default 4)
command specify blueshift, redshift, or sct to use, otherwise auto (default None)
delta specify interval value to change color temperature (default 100)
format display format for this module (default '{name} [\\?if=enabled&color=darkgray disabled' '|[\\?color=color_temperature {color_temperature}K]]')
maximum specify maximum color temperature to use (default 25000)
minimum specify minimum color temperature to use (default 1000)
thresholds specify color thresholds to use (default [(6499, '#f6c'), (6500, '#ff6'), (6501, '#6cf')])
Control placeholders:
{enabled} a boolean based on pgrep processing data, eg False, TrueFormat placeholders:
{color_temperature} color temperature, eg 6500
{name} name, eg Blueshift, Redshift, Sct
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
blueshift an extensible and highly configurable alternative to redshift
redshift program to adjust the color temperature of your screen
sct set color temperature with about 40 lines of C or so
Suggestions:
campfire 4500 dust storm on mars: 2000 coffee free all nighter: 8000Notes: hueshift can be disabled due to enabled running processes. sct and blueshift shifts only on one monitor, ideal for laptops. redshift shifts more than one, ideal for multi-monitors setups.
Examples:
# different theme\nhueshift {\n format = '\\?color=color_temperature \u263c {color_temperature}K'\n}\n\n# for best results, add some limitations\nhueshift {\n minimum = 3000\n maximum = 10000\n}\nauthor lasers
"},{"location":"user-guide/modules/#i3block","title":"i3block","text":"Support i3blocks blocklets in py3status.
i3blocks, https://github.com/vivien/i3blocks, is a project to allow simple scripts to provide output to the i3bar. This module allows these blocklets to run under py3status. The configuration of the blocklets is similar to how they are configured in i3blocks.
Configuration parameters:
cache_timeout How often the blocklet should be called (in seconds). This is similar to cache_timeout used by standard modules. However it can also take the following values; once the blocklet will be called once, repeat the blocklet will be called constantly, or persist where the command will be expected to keep providing new data. If this is not set or is None then the blocklet will not be called unless clicked on. To simplify i3block compatibility, this configuration parameter can also be provided as interval. (default None)
command Path to blocklet or command (default None)
format What to display on the bar (default '{output}')
instance Will be provided to the blocklet as $BLOCK_INSTANCE (default '')
label Will be prepended to the blocklets output (default '')
name Name of the blocklet - passed as $BLOCK_NAME (default '')
Format placeholders:
{output} The output of the blockletNotes: i3blocks and i3blocklets are subject to their respective licenses.
This support is experimental and done for convenience to users so they\ncan benefit from both worlds, issues or PRs regarding i3blocks related\nblocklets should not be raised.\n\nSome blocklets may return pango markup eg `<span ...` if so set\n`markup = pango` in the config for that module.\n\n`format` configuration parameter is used as is standard in py3status, not\nas in i3blocks configuration. Currently blocklets must provide responses\nin the standard i3blocks manner of one line per value (not as json).\nExamples:
# i3blocks config\n[time]\ncommand=date '+%D %T'\ninterval=5\n\n[wifi]\ninstance=wls1\nlabel='wifi:'\ncommand=~/i3blocks/wifi.sh\ninterval=5\n\n# py3status config\norder += 'i3block time'\ni3block time {\n command = \"date '+%D %T'\"\n interval = 5\n}\n\n# different py3status config\norder += 'i3block wifi'\ni3block wifi {\n instance = wls1\n label = 'wifi:'\n command = '~/i3blocks/wifi.sh'\n interval = 5\n}\nauthor tobes
"},{"location":"user-guide/modules/#i3pystatus","title":"i3pystatus","text":"Support i3pystatus modules in py3status.
i3pystatus, https://github.com/enkore/i3pystatus, is an alternative to py3status and provides a variety of modules. This py3status module allows these modules to run and be display inside py3status.
Configuration parameters:
module specify i3pystatus module to use (default None)Requires:
i3pystatus i3status replacement written in pythonExamples:
# the modules parameters are provided as such\ni3pystatus clock {\n module = 'clock'\n format = [('%a %b %-d %b %X', 'America/New_York'), ('%X', 'Etc/GMT+9')]\n}\n\n# if backend(s) are provided they should be given as a dict with the key being\n# the backend name and the value being a dict of the backend settings\ni3pystatus weather {\n module = 'weather'\n format = '{condition} {current_temp}{temp_unit}[ {icon}]'\n format += '[ Hi: {high_temp}][ Lo: {low_temp}][ {update_error}]'\n backend = {\n 'weathercom.Weathercom': {\n 'location_code': '94107:4:US',\n 'units': 'imperial',\n }\n }\n}\n\n# backends that have no configuration should be defined as shown here\ni3pystatus updates{\n module = 'updates'\n backends = {'dnf.Dnf': {}}\n}\nauthor tobes
"},{"location":"user-guide/modules/#icinga2","title":"icinga2","text":"Display service status for Icinga2.
Configuration parameters:
base_url the base url to the icinga-web2 services list (default '')
ca (default True)
cache_timeout how often the data should be updated (default 60)
disable_acknowledge enable or disable counting of acknowledged service problems (default False)
format define a format string like \"CRITICAL: %d\" (default '{status_name}: {count}')
password password to authenticate against the icinga-web2 interface (default '')
status set the status you want to obtain (0=OK,1=WARNING,2=CRITICAL,3=UNKNOWN) (default 0)
url_parameters (default '?service_state={service_state}&format=json')
user username to authenticate against the icinga-web2 interface (default '')
Format placeholders:
{status_name} status name, eg OK, WARNING, CRITICAL
{count} count, eg 0, 1, 2
author Ben Oswald <ben.oswald@root-space.de>
license BSD License <https://opensource.org/licenses/BSD-2-Clause>
source https://github.com/nazco/i3status-modules
"},{"location":"user-guide/modules/#imap","title":"imap","text":"Display number of unread messages from IMAP account.
Configuration parameters:
allow_urgent display urgency on unread messages (default False)
auth_scope scope to use with OAuth2 (default 'https://mail.google.com/')
auth_token path to where the pickled access/refresh token will be saved after successful credential authorization. (default '~/.config/py3status/imap_auth_token.pickle')
cache_timeout refresh interval for this module (default 60)
client_secret the path to the client secret file with OAuth 2.0 credentials (if None then OAuth not used) (default None)
criterion status of emails to check for (default 'UNSEEN')
debug log warnings (default False)
degraded_when_stale color as degraded when updating failed (default True)
format display format for this module (default 'Mail: {unseen}')
hide_if_zero hide this module when no new mail (default False)
mailbox name of the mailbox to check (default 'INBOX')
password login password (default None)
port number to use (default '993')
read_timeout timeout for read(2) syscalls (default 5)
security login authentication method: 'ssl' or 'starttls' (startssl needs python 3.2 or later) (default 'ssl')
server server to connect (default None)
use_idle use IMAP4 IDLE instead of polling; requires compatible server; uses cache_timeout for IDLE's timeout; will auto detect when set to None (default None)
user login user (default None)
Format placeholders:
{unseen} number of unread emailsColor options:
color_new_mail use color when new mail arrives, default to color_goodOAuth: OAuth2 will be used for authentication instead of a password if the client_secret path is set.
To create a client_secret for your Google account, visit\nhttps://console.developers.google.com/ and create an \"OAuth client ID\" from\nthe credentials tab.\n\nThis client secret enables the app (in this case, the IMAP py3status module)\nto request access to a user's email. Therefore the client secret doesn't\nhave to be for the same Google account as the email account being accessed.\n\nWhen the IMAP module first tries to access your email account a browser\nwindow will open asking for authorization to access your email.\nAfter authorization is complete, an access/refresh token will be saved to\nthe path configured in auth_token.\n\nRequires: Using OAuth requires the google-auth and google-auth-oauthlib\nlibraries to be installed.\n\nNote: the same client secret file can be used as with the py3status Google\nCalendar module.\nauthor obb, girst
"},{"location":"user-guide/modules/#insync","title":"insync","text":"Display Insync status.
Thanks to Iain Tatch <iain.tatch@gmail.com> for the script that this is based on.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{status} {queued}')
status_offline show when Insync is offline (default 'OFFLINE')
status_paused show when Insync is paused (default 'PAUSED')
status_share show when Insync is sharing (default 'SHARE')
status_synced show when Insync has finished syncing (default 'SYNCED')
status_syncing show when Insync is syncing (default 'SYNCING')
Format placeholders:
{status} Insync status
{queued} Number of files queued
Color options:
color_bad Offline
color_degraded Default (e.g. Paused/Syncing)
color_good Synced
Requires:
insync an unofficial Google Drive client with support for various desktopsauthor Joshua Pratt <jp10010101010000@gmail.com>
license BSD
"},{"location":"user-guide/modules/#kdeconnector","title":"kdeconnector","text":"Display information about your smartphone with KDEConnector.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 30)
device the device name, you need this if you have more than one device connected to your PC (default None)
device_id alternatively to the device name you can set your device id here (default None)
format see placeholders below (default '{name}{notif_status} {bat_status} {charge}%')
format_disconnected text if device is disconnected (default 'device disconnected')
low_threshold percentage value when text is twitch to color_bad (default 20)
status_bat text when battery is discharged (default '\u2b07')
status_chr text when device is charged (default '\u2b06')
status_full text when battery is full (default '\u263b')
status_no_notif text when you have no notifications (default '')
status_notif text when notifications are available (default ' \u2709')
Format placeholders:
{bat_status} battery state
{charge} the battery charge
{name} name of the device
{notif_size} number of notifications
{notif_status} shows if a notification is available or not
{net_type} shows cell network type
{net_strength} shows cell network strength
Color options:
color_bad Device unknown, unavailable or battery below low_threshold and not charging
color_degraded Connected and battery not charging
color_good Connected and battery charging
Requires:
kdeconnect adds communication between kde and your smartphone
dbus-python Python bindings for dbus PyGObject: Python bindings for GObject Introspectiom
Examples:
kdeconnector {\n device_id = \"aa0844d33ac6ca03\"\n format = \"{name} {charge} {bat_status}\"\n low_battery = \"10\"\n}\nauthor Moritz L\u00fcdecke, valdur55
"},{"location":"user-guide/modules/#keyboard_layout","title":"keyboard_layout","text":"Display keyboard layout.
Configuration parameters:
button_next mouse button to cycle next layout (default 4)
button_prev mouse button to cycle previous layout (default 5)
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{layout}')
layouts specify a list of layouts to use (default None)
Format placeholders:
{layout} keyboard layoutColor options:
color_<layout> colorize the layout. eg color_fr = '#729FCF'Requires:
xkblayout-state or
setxkbmap and xset (works for the first two predefined layouts. overrides XkbLayout when switching layout.)
Examples:
# define keyboard layouts that can be switched between\nkeyboard_layout {\n layouts = ['gb', 'fr', 'dvorak']\n}\nauthor shadowprince, tuxitop
license Eclipse Public License
"},{"location":"user-guide/modules/#keyboard_locks","title":"keyboard_locks","text":"Display NumLock, CapsLock, and ScrLock keys.
Configuration parameters:
cache_timeout refresh interval for this module (default 1)
format display format for this module (default '[\\?if=num_lock&color=good NUM|\\?color=bad NUM] ' '[\\?if=caps_lock&color=good CAPS|\\?color=bad CAPS] ' '[\\?if=scroll_lock&color=good SCR|\\?color=bad SCR]')
Control placeholders:
{num_lock} a boolean based on xset data
{caps_lock} a boolean based on xset data
{scroll_lock} a boolean based on xset data
Color options:
color_good Lock on
color_bad Lock off
Examples:
# hide NUM, CAPS, SCR\nkeyboard_locks {\n format = '\\?color=good [\\?if=num_lock NUM][\\?soft ]'\n format += '[\\?if=caps_lock CAPS][\\?soft ][\\?if=scroll_lock SCR]'\n}\nauthor lasers
"},{"location":"user-guide/modules/#khal_calendar","title":"khal_calendar","text":"Displays upcoming khal events.
Configuration parameters:
cache_timeout refresh interval for this module (default 60)
config_path Path to khal configuration file. The default None resolves to /home/$USER/.config/khal/config (default None)
date_end Until which datetime the module searches for events (default 'eod')
format display format for this module (default '{appointments}')
max_results an upper bound for the number of returned calendar entries (default None)
output_format khal conform format for displaying event output (default '{start-time} {title}')
Format placeholders:
{appointments} list of events in time rangeRequires:
khal https://github.com/pimutils/khalauthor @xenrox
license BSD
"},{"location":"user-guide/modules/#lm_sensors","title":"lm_sensors","text":"Display temperatures, voltages, fans, and more from hardware sensors.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
chips specify a list of chips to use (default [])
format display format for this module (default '{format_chip}')
format_chip display format for chips (default '{name} {format_sensor}')
format_chip_separator show separator if more than one (default ' ')
format_sensor display format for sensors (default '[\\?color=darkgray {name}] [\\?color=auto.input&show {input}]')
format_sensor_separator show separator if more than one (default ' ')
sensors specify a list of sensors to use (default [])
thresholds specify color thresholds to use (default {'auto.input': True})
Format placeholders:
{format_chip} format for chipsFormat_chip placeholders:
{name} chip name, eg coretemp-isa-0000, nouveau-pci-0500
{adapter} adapter type, eg ISA adapter, PCI adapter
{format_sensor} format for sensors
Format_sensor placeholders:
{name} sensor name, eg core_0, gpu_core, temp1, fan1
See sensors -u for a full list of placeholders for format_chip, format_sensors without the prefixes, chips and sensors options.
See https://www.kernel.org/doc/Documentation/hwmon/sysfs-interface for more information on the sensor placeholders.
Color options for auto.input threshold:
color_zero zero value or less (color red)
color_min minimum value (color lightgreen)
color_excl_input input value excluded from threshold (color None)
color_input input value (color lime)
color_near_max input value near maximum value (color yellow)
color_max maximum value (color orange)
color_near_crit input value near critical value (color lightcoral)
color_crit critical value (color red)
Color thresholds:
format_sensor xxx: print a color based on the value of xxx placeholder auto.input: print a color based on the value of input placeholder against a customized thresholdRequires:
lm_sensors a tool to read temperature/voltage/fan sensors
sensors-detect see man sensors-detect # --auto to read about using defaults or to compile a list of kernel modules
Examples:
# identify possible chips, sensors, placeholders, etc\n [user@py3status ~] $ sensors -u\n ----------------------------- # \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n coretemp-isa-0000 # chip {name} # chip: coretemp*\n Adapter: ISA adapter # \u251c\u2500\u2500 {adapter} type\n ---- # \u2502------------------------------------\n Core 0: # \u251c\u2500\u2500 sensor {name} # sensor: core_0\n temp2_input: 48.000 # \u2502 \u251c\u2500\u2500 {input}\n temp2_max: 81.000 # \u2502 \u251c\u2500\u2500 {max}\n temp2_crit: 91.000 # \u2502 \u251c\u2500\u2500 {crit}\n temp2_crit_alarm: 0.000 # \u2502 \u2514\u2500\u2500 {crit_alarm}\n Core 1: # \u2514\u2500\u2500 sensor {name} # sensor: core_1\n temp3_input: 48.000 # \u251c\u2500\u2500 {input}\n temp3_max: 81.000 # \u251c\u2500\u2500 {max}\n temp3_crit: 91.000 # \u251c\u2500\u2500 {crit}\n temp3_crit_alarm: 0.000 # \u2514\u2500\u2500 {crit_alarm}\n # \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n k10temp-pci-00c3 # chip {name} # chip: k10temp*\n Adapter: PCI adapter # \u251c\u2500\u2500 {adapter} type\n ---- # \u2502------------------------------------\n temp1: # \u251c\u2500\u2500 sensor {name} # sensor: temp1\n temp1_input: 30.000 # \u2502 \u251c\u2500\u2500 {input}\n temp1_max: -71.000 # \u2502 \u251c\u2500\u2500 {max}\n temp1_min: -15.000 # \u2502 \u251c\u2500\u2500 {min}\n temp1_alarm: 1.000 # \u2502 \u251c\u2500\u2500 {alarm}\n temp1_offset: 0.000 # \u2502 \u251c\u2500\u2500 {offset}\n temp1_beep: 0.000 # \u2502 \u2514\u2500\u2500 {beep}\n intrusion0: # \u2514\u2500\u2500 sensor {name} # sensor: intrusion0\n intrusion0_alarm: 0.000 # \u2514\u2500\u2500 {alarm}\n\n Solid lines denotes chips. Dashed lines denotes sensors.\n Sensor names are lowercased and its spaces replaced with underscores.\n The numbered prefixes, eg `temp1_*` are removed to keep names clean.\n\n# specify chips to use\nlm_sensors {\n chips = ['coretemp-isa-0000'] # full\n OR\n chips = ['coretemp-*'] # lm_sensors-compatible wildcard\n}\n\n# specify sensors to use\nlm_sensors {\n sensors = ['core_0', 'core_1', 'core_2', 'core_3'] # full\n OR\n sensors = ['core_*'] # fnmatch\n}\n\n# show name per chip, eg CPU 35\u00b0C 36\u00b0C 37\u00b0C 39\u00b0C GPU 52\u00b0C\nlm_sensors {\n format_chip = '[\\?if=name=coretemp-isa-0000 CPU ]'\n format_chip += '[\\?if=name=nouveau-pci-0500 GPU ]'\n format_chip += '{format_sensor}'\n format_sensor = '\\?color=auto.input {input}\u00b0C'\n sensors = ['core*', 'temp*']\n}\n\n# show name per sensor, eg CPU1 35\u00b0C CPU2 36\u00b0C CPU3 37\u00b0C CPU4 39\u00b0C GPU 52\u00b0C\nlm_sensors {\n format_chip = '{format_sensor}'\n format_sensor = '[\\?if=name=core_0 CPU1 ]'\n format_sensor += '[\\?if=name=core_1 CPU2 ]'\n format_sensor += '[\\?if=name=core_2 CPU3 ]'\n format_sensor += '[\\?if=name=core_3 CPU4 ]'\n format_sensor += '[\\?if=name=gpu_core GPU ]'\n format_sensor += '[\\?color=auto.input {input}\u00b0C]'\n sensors = ['core*', 'temp*']\n}\nauthor lasers
"},{"location":"user-guide/modules/#loadavg","title":"loadavg","text":"Display average system load over a period of time.
In UNIX computing, the system load is a measure of the amount of computational work that a computer system performs. The load average represents the average system load over a period of time. It conventionally appears in the form of three numbers which represent the system load during the last one-, five-, and fifteen-minute periods.
Configuration parameters:
cache_timeout refresh interval for this module (default 5)
format display format for this module (default 'Loadavg [\\?color=1avg {1min}] ' '[\\?color=5avg {5min}] [\\?color=15avg {15min}]')
thresholds specify color thresholds to use (default [(0, '#9dd7fb'), (20, 'good'), (40, 'degraded'), (60, '#ffa500'), (80, 'bad')])
Format placeholders:
{1min} load average during the last 1-minute, eg 1.44
{5min} load average during the last 5-minutes, eg 1.66
{15min} load average during the last 15-minutes, eg 1.52
{1avg} load average percentage during the last 1-minute, eg 12.00
{5avg} load average percentage during the last 5-minutes, eg 13.83
{15avg} load average percentage during the last 15-minutes, eg 12.67
Color thresholds:
xxx print a color based on the value of xxx placeholderNotes: http://blog.scoutapp.com/articles/2009/07/31/understanding-load-averages http://www.brendangregg.com/blog/2017-08-08/linux-load-averages.html
Examples:
# show load averages with static colors\nloadavg {\n format = 'Loadavg [\\?color=orange {1min} ][\\?color=gold {5min} {15min}]'\n}\n\n# remove prefix - easy copy and paste\nloadavg {\n format = '[\\?color=1avg {1min}] '\n format += '[\\?color=5avg {5min}] '\n format += '[\\?color=15avg {15min}]'\n}\n\n# show detailed load averages + percentages\nloadavg {\n format = 'Loadavg [\\?color=darkgray '\n format += '1min [\\?color=1avg {1min}]\\|[\\?color=1avg {1avg}%] '\n format += '5min [\\?color=5avg {5min}]\\|[\\?color=5avg {5avg}%] '\n format += '15min [\\?color=15avg {15min}]\\|[\\?color=15avg {15avg}%]]'\n}\n\n# show load averages with different colors + thresholds\nloadavg {\n # htop - default\n (0, '#9dd7fb'), # 1avg\n (0, 'cyan'), # 5avg\n (0, 'darkcyan'), $ 15avg\n\n # htop - monochrome\n (0, '#9dd7fb'), # 1avg\n (0, None), # 5avg\n (0, None), # 15avg\n\n # htop - black night\n (0, 'greenyellow'), # 1avg\n (0, 'limegreen'), # 5avg\n (0, 'limegreen'), # 15avg\n\n # htop - mc\n (0, '#ffffff'), # 1avg\n (0, '#aaaaaa'), # 5avg\n (0, '#555555'), # 15avg\n\n # three shades of blue\n (0, '#87cefa'), # 1avg\n (0, '#4bb6f8'), # 5avg\n (0, '#0991e5'), # 15avg\n\n # three shades of gray\n (0, '#dddddd'), # 1avg\n (0, '#bbbbbb'), # 5avg\n (0, '#999999'), # 15avg\n\n # htop - mc and three shades of gray is similar. htop - mc\n # have higher contrast between time periods over three shades\n # of gray for better readability. your mileage may vary.\n\n thresholds = {\n '1avg': [\n (0, 'REPLACE_ME'),\n (20, 'good'), (40, 'degraded'),\n (60, '#ffa500'), (80, 'bad')\n ],\n '5avg': [\n (0, 'REPLACE_ME'),\n (20, 'good'), (40, 'degraded'),\n (60, '#ffa500'), (80, 'bad')\n ],\n '15avg': [\n (0, 'REPLACE_ME'),\n (20, 'good'), (40, 'degraded'),\n (60, '#ffa500'), (80, 'bad')\n ],\n }\n}\n\n# don't show load averages if 1avg is under 60%\nloadavg {\n format = '[\\?if=1avg>59 Loadavg [\\?color=1avg {1min}] '\n format += '[\\?color=5avg {5min}] [\\?color=15avg {15min}]]'\n}\n\n# add your snippets here\nloadavg {\n format = \"...\"\n}\nauthor lasers
"},{"location":"user-guide/modules/#mail","title":"mail","text":"Display number of messages in various mailbox formats. This module supports Maildir, mbox, MH, Babyl, MMDF, and IMAP.
Configuration parameters:
accounts specify a dict consisting of mailbox types and a list of dicts consisting of mailbox settings and/or paths to use (default {})
cache_timeout refresh interval for this module (default 60)
format display format for this module (default '\\?not_zero Mail {mail}|No Mail')
thresholds specify color thresholds to use (default [])
Format placeholders:
{mail} number of messages
{maildir} number of Maildir messages
{mbox} number of mbox messages
{mh} number of MH messages
{babyl} number of Babyl messages
{mmdf} number of MMDF messages
{imap} number of IMAP messages
We can divide mailbox, eg {maildir}, into numbered placeholders based on number of mailbox accounts, eg {maildir_1}, and if we add name to a mailbox account, we can use {name} placeholder instead, eg {home}.
Color thresholds:
xxx print a color based on the value of xxx placeholderIMAP Subscriptions: You can specify a list of filters to decide which folders to search. By default, we search only the INBOX folder (ie: ['^INBOX$']). We can use regular expressions, so if you use more than one, it would be joined by a logical operator or.
`'.*'` will match all folders.\n`'pattern'` will match folders containing `pattern`.\n`'^pattern'` will match folders beginning with `pattern`.\n`'pattern$'` will match folders ending with `pattern`.\n`'^((?![Ss][Pp][Aa][Mm]).)*$'` will match all folders\nexcept for every possible case of `spam` folders.\n\nFor more documentation, see https://docs.python.org/3/library/re.html\nand/or any regex builder on the web. Don't forget to escape characters.\nExamples:
# add multiple accounts\nmail { #\n accounts = { # {mail}\n 'maildir': [ # \u251c\u2500\u2500 {maildir}\n {'path': '~/.mutt'}, # \u2502 \u251c\u2500\u2500 {maildir_1}\n {'path': '~/Mail'}, # \u2502 \u2514\u2500\u2500 {maildir_2}\n ], # \u2502\n 'mbox': [ # \u251c\u2500\u2500 {mbox}\n {'path': '~/home.mbox'}, # \u2502 \u251c\u2500\u2500 {mbox_1}\n { # \u2502 \u251c\u2500\u2500 {mbox_2}\n 'name': 'local', # <----\u2502----\u2502----\u2514\u2500\u2500 {local}\n 'path': '~/mbox' # \u2502 \u2502\n }, # \u2502 \u2502\n { # \u2502 \u2514\u2500\u2500 {mbox_3}\n 'name': 'debian', # <----\u2502---------\u2514\u2500\u2500 {debian}\n 'path': '/var/mail/$USER' # \u2502\n 'urgent': False, # <----\u2502---- disable urgent\n }, # \u2502\n ], # \u2502\n 'mh': [ # \u251c\u2500\u2500 {mh}\n {'path': '~/mh_mail'}, # \u2502 \u2514\u2500\u2500 {mh_1}\n ], # \u2502\n 'babyl': [ # \u251c\u2500\u2500 {babyl}\n {'path': '~/babyl_mail'}, # \u2502 \u2514\u2500\u2500 {babyl_1}\n ], # \u2502\n 'mmdf': [ # \u251c\u2500\u2500 {mmdf}\n {'path': '~/mmdf_mail'}, # \u2502 \u2514\u2500\u2500 {mmdf_1}\n ] # \u2502\n 'imap': [ # \u251c\u2500\u2500 {imap}\n { # \u2502 \u251c\u2500\u2500 {imap_1}\n 'name': 'home', # <----\u2502----\u2502----\u2514\u2500\u2500 {home}\n 'user': 'lasers', # \u2502 \u2502\n 'password': 'kiss_my_butt!', # \u2502 \u2502\n 'server': 'imap.gmail.com', # \u2502 \u2502\n # <---\u2502----\u2502 no filters to\n 'port': 993, # \u2502 \u2502 search folders, use\n # \u2502 \u2502 filters ['^INBOX$']\n }, # \u2502 \u2502\n { # \u2502 \u2514\u2500\u2500 {imap_2}\n 'name': 'work', # <----\u2502---------\u2514\u2500\u2500 {work}\n 'user': 'tobes', # \u2502\n 'password': 'i_love_python', #\n 'server': 'imap.yahoo.com', #\n # <---- no port, use port 993\n 'urgent': False, # <---- disable urgent\n # for this account\n 'filters': ['^INBOX$'] # <---- specify a list of filters\n # to search folders\n 'log': True, # <---- print a list of folders\n } # to filter in the log\n ]\n }\n allow_urgent = False <---- disable urgent for all accounts\n}\n\n# add colors, disable urgent\nmail {\n format = '[\\?color=mail&show Mail] {mail}'\n thresholds = [(1, 'good'), (5, 'degraded'), (15, 'bad')]\n allow_urgent = False\n}\n\n# identify the mailboxes, remove what you don't need\nmail {\n format = '[\\?color=mail '\n format += '[\\?if=imap&color=#00ff00 IMAP ]'\n format += '[\\?if=maildir&color=#ffff00 MAILDIR ]'\n format += '[\\?if=mbox&color=#ff0000 MBOX ]'\n format += '[\\?if=babyl&color=#ffa500 BABYL ]'\n format += '[\\?if=mmdf&color=#00bfff MMDF ]'\n format += '[\\?if=mh&color=#ee82ee MH ]'\n format += ']'\n format += '[\\?not_zero&color Mail {mail}|No Mail]'\n}\n\n# individual colorized mailboxes, remove what you don't need\nmail {\n format = '[\\?if=imap&color=#00ff00 IMAP] {imap} '\n format += '[\\?if=maildir&color=#ffff00 MAILDIR] {maildir} '\n format += '[\\?if=mbox&color=#ff0000 MBOX] {mbox} '\n format += '[\\?if=babyl&color=#ffa500 BABYL] {babyl} '\n format += '[\\?if=mmdf&color=#00bfff MMDF] {mmdf} '\n format += '[\\?if=mh&color=#ee82ee MH] {mh}'\n allow_urgent = False\n}\nauthor lasers
"},{"location":"user-guide/modules/#mega_sync","title":"mega_sync","text":"Display status of MEGAcmd.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for the module (default \"MEGA {format_sync}|No MEGA\")
format_sync display format for every sync (default \"{syncstate}\")
format_sync_separator show separator if more than one sync (default \" \")
Format placeholders:
{format_sync} Format for every sync returned by 'mega-sync' command.format_sync placeholders: Any column returned by 'mega-sync' command - in lower case! For example: id, syncstate, localpath
Requires: MEGAcmd: command-line interface for MEGA
author Maxim Baz (https://github.com/maximbaz)
license BSD
"},{"location":"user-guide/modules/#moc","title":"moc","text":"Display song currently playing in moc.
MOC (music on console) is a console audio player for Linux/Unix designed to be powerful and easy to use. It consists of two parts, a server (moc) and a player/interface (mocp). It supports OGG, WAV, MP3 and other formats.
Configuration parameters:
button_next mouse button to skip next track (default None)
button_pause mouse button to pause/play the playback (default 1)
button_previous mouse button to skip previous track (default None)
button_stop mouse button to stop the playback (default 3)
cache_timeout refresh interval for this module (default 5)
format display format for this module (default '\\?if=is_started [\\?if=is_stopped [] moc|' '[\\?if=is_paused ||][\\?if=is_playing >] {title}]')
replacements specify a list/dict of string placeholders to modify (default None)
sleep_timeout when moc is not running, this interval will be used to allow one to refresh constantly with time placeholders and/or to refresh once every minute rather than every few seconds (default 20)
Control placeholders:
{is_paused} a boolean based on moc status
{is_playing} a boolean based on moc status
{is_started} a boolean based on moc status
{is_stopped} a boolean based on moc status
Format placeholders:
{album} album name, eg (new output here)
{artist} artist name, eg (new output here)
{avgbitrate} audio average bitrate, eg 230kbps
{bitrate} audio bitrate, eg 230kbps
{currentsec} elapsed time in seconds, eg 32
{currenttime} elapsed time in [HH:]MM:SS, eg 00:32
{file} file location, eg /home/user/Music...
{rate} audio rate, eg 44kHz
{songtitle} song title, eg (new output here)
{state} playback state, eg PLAY, PAUSE, STOP
{timeleft} time left in [HH:]MM:SS, eg 71:30
{title} track title, eg (new output here)
{totalsec} total time in seconds, eg 4322
{totaltime} total time in seconds, eg 72:02
Placeholders are retrieved directly from mocp --info command. The list was harvested once and should not represent a full list.
Color options:
color_paused Paused, defaults to color_degraded
color_playing Playing, defaults to color_good
color_stopped Stopped, defaults to color_bad
Requires:
moc a console audio player with simple ncurses interfaceExamples:
# see 'man mocp' for more buttons\nmoc {\n on_click 9 = 'exec mocp --example'\n}\nauthor lasers
"},{"location":"user-guide/modules/#mpd_status","title":"mpd_status","text":"Display song currently playing in mpd.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 2)
format template string (see below) (default '{state} [[[{artist} ]- {title}]|[{file}]]')
hide_on_error hide the status if an error has occurred (default False)
hide_when_paused hide the status if state is paused (default False)
hide_when_stopped hide the status if state is stopped (default True)
host mpd host (default 'localhost')
idle_subsystems a list of subsystems to idle on. player: changes in song information, play state mixer: changes in volume options: e.g. repeat mode See the MPD protocol documentation for additional events. (default ['player', 'playlist', 'mixer', 'options'])
idle_timeout force idle to reset every n seconds (default 3600)
max_width maximum status length (default 120)
password mpd password (default None)
port mpd port (default '6600')
state_pause label to display for \"paused\" state (default '[pause]')
state_play label to display for \"playing\" state (default '[play]')
state_stop label to display for \"stopped\" state (default '[stop]')
use_idle whether to use idling instead of polling. None to autodetect (default None)
Format placeholders:
{state} state (paused, playing. stopped) can be defined via state_.. configuration parameters Refer to the mpc(1) manual page for the list of available placeholders to be used in the format. Placeholders should use braces {} rather than percent %% eg {artist}. Every placeholder can also be prefixed with next_ to retrieve the data for the song following the one currently playing.Color options:
color_pause Paused, default color_degraded
color_play Playing, default color_good
color_stop Stopped, default color_bad
Requires:
python-mpd2 (NOT python2-mpd2)Examples:
# Show state and (artist -) title, if no title fallback to file:\n{state} [[[{artist} - ]{title}]|[{file}]]\n\n# Show state, [duration], title (or file) and next song title (or file):\n{state} \\[{time}\\] [{title}|{file}] \u2192 [{next_title}|{next_file}]\nauthor shadowprince, zopieux
license Eclipse Public License
"},{"location":"user-guide/modules/#mpris","title":"mpris","text":"Display song/video and control MPRIS compatible players.
There are two ways to control the media player. Either by clicking with a mouse button in the text information or by using buttons. For former you have to define the button parameters in your config.
Configuration parameters:
button_next mouse button to play the next entry (default None)
button_next_player mouse button to switch next player in list (Same status as top player) (default None)
button_prev_player mouse button to switch previous player in list (Same status as top player) (default None)
button_previous mouse button to play the previous entry (default None)
button_stop mouse button to stop the player (default None)
button_switch_to_top_player mouse button to switch to top player (default None)
button_toggle mouse button to toggle between play and pause mode (default 1)
cache_timeout time (s) between Position update (default 0.5)
format display format for this module (default '[{artist} - ][{title}] {previous} {toggle} {next}')
format_none define output if no player is running (default 'no player running')
icon_next specify icon for next button (default u'\u25b9')
icon_pause specify icon for pause button (default u'\u25eb')
icon_play specify icon for play button (default u'\u25b7')
icon_previous specify icon for previous button (default u'\u25c3')
icon_stop specify icon for stop button (default u'\u25a1')
max_width maximum status length (default None)
player_priority priority of the players. Keep in mind that the state has a higher priority than player_priority. So when player_priority is \"[mpd, bomi]\" and mpd is paused and bomi is playing than bomi wins. (default [])
state_pause specify icon for pause state (default u'\u25eb')
state_play specify icon for play state (default u'\u25b7')
state_stop specify icon for stop state (default u'\u25a1')
Format placeholders:
{album} album name
{artist} artiste name (first one)
{length} time duration of the song
{player} show name of the player
{player_shortname} show name of the player from busname (usually command line name)
{state} playback status of the player
{time} played time of the song
{title} name of the song
{nowplaying} now playing field provided by VLC for stream info
Button placeholders:
{next} play the next title
{pause} pause the player
{play} play the player
{previous} play the previous title
{stop} stop the player
{toggle} toggle between play and pause
Color options:
color_control_inactive button is not clickable
color_control_active button is clickable
color_paused song is paused, defaults to color_degraded
color_playing song is playing, defaults to color_good
color_stopped song is stopped, defaults to color_bad
Requires:
mpris2 Python usable definiton of MPRIS2
dbus-python Python bindings for dbus PyGObject: Python bindings for GObject Introspection
Tested players:
bomi powerful and easy-to-use gui multimedia player based on mpv
cantata qt5 client for the music player daemon (mpd)
mpdris2 mpris2 support for mpd
vlc multi-platform mpeg, vcd/dvd, and divx player
Examples:
mpris {\n format = \"{previous}{play}{next} {player}: {state} [[{artist} - {title}]|[{title}]]\"\n format_none = \"no player\"\n player_priority = \"[mpd, cantata, vlc, bomi, *]\"\n}\n\nonly show information from mpd and vlc, but mpd has a higher priority:\nmpris {\n player_priority = \"[mpd, vlc]\"\n}\n\nshow information of all players, but mpd and vlc have the highest priority:\nmpris {\n player_priority = \"[mpd, vlc, *]\"\n}\n\nvlc has the lowest priority:\nmpris {\n player_priority = \"[*, vlc]\"\n}\nauthor Moritz L\u00fcdecke, tobes, valdur55
"},{"location":"user-guide/modules/#net_iplist","title":"net_iplist","text":"Display list of network interfaces and IP addresses.
This module supports both IPv4 and IPv6. There is the possibility to blacklist interfaces and IPs, as well as to show interfaces with no IP address. It will show an alternate text if no IP are available.
Configuration parameters:
cache_timeout refresh interval for this module in seconds. (default 30)
format format of the output. (default 'Network: {format_iface}')
format_iface format string for the list of IPs of each interface. (default '{iface}:[ {ip4}][ {ip6}]')
format_no_ip string to show if there are no IPs to display. (default 'no connection')
iface_blacklist list of interfaces to ignore. Accepts shell-style wildcards. (default ['lo'])
iface_sep string to write between interfaces. (default ' ')
ip_blacklist list of IPs to ignore. Accepts shell-style wildcards. (default [])
ip_sep string to write between IP addresses. (default ',')
remove_empty do not show interfaces with no IP. (default True)
Format placeholders:
{format_iface} the format_iface string.Format placeholders for format_iface:
{iface} name of the interface.
{ip4} list of IPv4 of the interface.
{ip6} list of IPv6 of the interface.
Color options:
color_bad no IPs to show
color_good IPs to show
Requires:
ip utility found in iproute2 packageExamples:
net_iplist {\n iface_blacklist = []\n ip_blacklist = ['127.*', '::1']\n}\nauthor guiniol
"},{"location":"user-guide/modules/#net_rate","title":"net_rate","text":"Display network transfer rate.
Configuration parameters:
all_interfaces ignore self.interfaces, but not self.interfaces_blacklist (default True)
cache_timeout how often we refresh this module in seconds (default 2)
devfile location of dev file under /proc (default '/proc/net/dev')
format format of the module output (default '{interface}: {total}')
format_no_connection when there is no data transmitted from the start of the plugin (default '')
format_value format to use for values (default \"[\\?min_length=11 {value:.1f} {unit}]\")
hide_if_zero hide indicator if rate == 0 (default False)
interfaces comma separated list of interfaces to track (default [])
interfaces_blacklist comma separated list of interfaces to ignore (default 'lo')
si_units use SI units (default False)
sum_values sum values of each interface instead of taking the top one (default False)
thresholds specify color thresholds to use (default [(0, 'bad'), (1024, 'degraded'), (1024 * 1024, 'good')])
unit unit to use. If the unit contains a multiplier prefix, only this exact unit will ever be used (default \"B/s\")
Format placeholders:
{down} download rate
{interface} name of interface
{total} total rate
{up} upload rate
format_value placeholders:
{unit} current unit
{value} numeric value
Color thresholds:
{down} Change color based on the value of down
{total} Change color based on the value of total
{up} Change color based on the value of up
author shadowprince
license Eclipse Public License
"},{"location":"user-guide/modules/#netdata","title":"netdata","text":"Display network speed and bandwidth usage.
Configuration parameters:
cache_timeout refresh interval for this module (default 2)
format display format for this module (default '{nic} [\\?color=down LAN(Kb): {down}\u2193 {up}\u2191] ' '[\\?color=total T(Mb): {download}\u2193 {upload}\u2191 {total}\u2195]')
nic specify a network interface to use (default None)
thresholds specify color thresholds to use (default {'down': [(0, 'bad'), (30, 'degraded'), (60, 'good')], 'total': [(0, 'good'), (400, 'degraded'), (700, 'bad')]})
Format placeholders:
{nic} network interface
{down} number of download speed
{up} number of upload speed
{download} number of download usage
{upload} number of upload usage
{total} number of total usage
Color thresholds:
xxx print a color based on the value of xxx placeholderauthor Shahin Azad <ishahinism at Gmail>
"},{"location":"user-guide/modules/#networkmanager","title":"networkmanager","text":"Display NetworkManager fields via nmcli, a command-line tool.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
devices specify a list of devices to use (default ['[e|w]'])*
format display format for this module (default '{format_device}')
format_device format for devices (default \"[\\?if=general_connection {general_device}[\\?soft ][\\?color=ap_signal {ap_ssid} {ap_bars} {ap_signal}%][\\?soft ][\\?color=good {ip4_address1}]]\")
format_device_separator show separator if more than one (default ' ')
thresholds specify color thresholds to use (default [(0, 'bad'), (30, 'degraded'), (65, 'good')])
Format placeholders:
{format_device} format for devicesFormat_device placeholders:
{general_connection} eg Py3status, Wired Connection 1
{general_device} eg wlp3s0b1, enp2s0
{general_type} eg wifi, ethernet
{ap_bars} signal strength in bars, eg \u2582\u2584\u2586_
{ap_chan} wifi channel, eg 6
{ap_mode} network mode, eg Adhoc or Infra
{ap_rate} bitrate, eg 54 Mbit/s
{ap_security} signal security, eg WPA2
{ap_signal} signal strength in percentage, eg 63
{ap_ssid} ssid name, eg Py3status
{ip4_address1} eg 192.168.1.108
{ip6_address1} eg 0000::0000:0000:0000:0000
Use nmcli --terse --fields=general,ap,ip4,ip6 device show for a full list of supported NetworkManager fields to use. Not all of NetworkManager fields will be usable. See man nmcli for more information.
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
nmcli cli configuration utility for NetworkManagerExamples:
# specify devices to use\nnetworkmanager {\n devices = ['e*'] # ethernet only\n devices = ['w*'] # wireless only\n devices = [] # ethernet, wireless, lo, etc\n}\nauthor Kevin Pulo <kev@pulo.com.au>
license BSD
"},{"location":"user-guide/modules/#ns_checker","title":"ns_checker","text":"Display DNS resolution success on a configured domain.
This module launch a simple query on each nameservers for the specified domain. Nameservers are dynamically retrieved. The FQDN is the only one mandatory parameter. It's also possible to add additional nameservers by appending them in nameservers list.
The default resolver can be overwritten with my_resolver.nameservers parameter.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 300)
domain domain name to check (default '')
format output format string (default '{total_count} NS {status}')
lifetime resolver lifetime (default 0.3)
nameservers specify a list of reference DNS nameservers (default [])
resolvers specify a list of DNS resolvers to use (default [])
Format placeholders:
{nok_count} The number of failed name servers
{ok_count} The number of working name servers
{status} The overall status of the name servers (OK or NOK)
{total_count} The total number of name servers
Color options:
color_bad One or more lookups have failed
color_good All lookups have succeeded
Requires:
dnspython a dns toolkit for pythonauthor nawadanp
"},{"location":"user-guide/modules/#nvidia_smi","title":"nvidia_smi","text":"Display NVIDIA properties currently exhibiting in the NVIDIA GPUs.
nvidia-smi, short for NVIDIA System Management Interface program, is a cross platform tool that supports all standard NVIDIA driver-supported Linux distros.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{format_gpu}')
format_gpu display format for NVIDIA GPUs (default '{gpu_name} [\\?color=temperature.gpu {temperature.gpu}\u00b0C] ' '[\\?color=memory.used_percent {memory.used_percent}%]')
format_gpu_separator show separator if more than one (default ' ')
memory_unit specify memory unit, eg 'KiB', 'MiB', 'GiB', otherwise auto (default None)
thresholds specify color thresholds to use (default [(0, 'good'), (65, 'degraded'), (75, 'orange'), (85, 'bad')])
Format placeholders:
{format_gpu} format for NVIDIA GPUsformat_gpu placeholders:
{index} Zero based index of the GPU.
{count} The number of NVIDIA GPUs in the system
{driver_version} The version of the installed NVIDIA display driver
{gpu_name} The official product name of the GPU
{gpu_uuid} Globally unique immutable identifier of the GPU
{memory.free} Total free memory
{memory.free_unit} Total free memory unit
{memory.total} Total installed GPU memory
{memory.total_unit} Total installed GPU memory unit
{memory.used} Total memory allocated by active contexts
{memory.used_percent} Total memory allocated by active contexts percentage
{memory.used_unit} Total memory unit
{temperature.gpu} Core GPU temperature in degrees C
Use python /path/to/nvidia_smi.py --list-properties for a full list of supported NVIDIA properties to use. Not all of supported NVIDIA properties will be usable. See nvidia-smi --help-query-gpu for more information.
Color thresholds:
format_gpu xxx: print a color based on the value of NVIDIA xxx propertyRequires:
nvidia-smi command line interface to query NVIDIA devicesExamples:
# display nvidia properties\nnvidia_smi {\n format_gpu = '{gpu_name} [\\?color=temperature.gpu {temperature.gpu}\u00b0C] '\n format_gpu += '[\\?color=memory.used_percent {memory.used} {memory.used_unit}'\n format_gpu += '[\\?color=darkgray&show \\|]{memory.used_percent:.1f}%]'\n}\nauthor lasers
"},{"location":"user-guide/modules/#online_status","title":"online_status","text":"Determine if you have an Internet Connection.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{icon}')
icon_off show when connection is offline (default '\u25a0')
icon_on show when connection is online (default '\u25cf')
timeout time to wait for a response, in seconds (default 2)
url specify URL to connect when checking for a connection (default 'https://www.google.com')
Format placeholders:
{icon} connection statusColor options:
color_off Connection offline, defaults to color_bad
color_on Connection online, defaults to color_good
author obb
"},{"location":"user-guide/modules/#pingdom","title":"pingdom","text":"Display response times of the configured Pingdom checks.
We also verify the status of the checks and colorize if needed. Pingdom API doc : https://www.pingdom.com/features/api/documentation/
Configuration parameters:
app_key create an APP KEY on pingdom first (default '')
cache_timeout how often to refresh the check from pingdom (default 600)
checks comma separated pindgom check names to display (default '')
format display format for this module (default '{pingdom}')
login pingdom login (default '')
max_latency maximal latency before coloring the output (default 500)
password pingdom password (default '')
request_timeout pindgom API request timeout (default 10)
Format placeholders:
{pingdom} pingdom response timesColor options:
color_bad Site is down
color_degraded Latency exceeded max_latency
Requires:
requests https://pypi.python.org/pypi/requestsauthor ultrabug
"},{"location":"user-guide/modules/#playerctl","title":"playerctl","text":"Display song/video and control players supported by playerctl
Playerctl is a command-line utility for controlling media players that implement the MPRIS D-Bus Interface Specification. With Playerctl you can bind player actions to keys and get metadata about the currently playing song or video.
Configuration parameters:
button_loop mouse button to cycle the loop status of the player (default None)
button_next mouse button to skip to the next track (default None)
button_pause mouse button to pause the playback (default None)
button_play mouse button to play the playback (default None)
button_play_pause mouse button to play/pause the playback (default 1)
button_previous mouse button to skip to the previous track (default None)
button_seek_backward mouse button to playback's position backward (default None)
button_seek_forward mouse button to playback's position forward (default None)
button_shuffle mouse button to toggle the shuffle mode of the player (default None)
button_stop mouse button to stop the playback (default 3)
button_volume_down mouse button to decrease the volume of the player (default None)
button_volume_up mouse button to increase the volume of the player (default None)
format display format for this module (default '{format_player}')
format_player display format for players (default '[\\?color=status [\\?if=status=Playing > ][\\?if=status=Paused || ]' '[\\?if=status=Stopped .. ][[{artist}][\\?soft - ][{title}|{player}]]]')
format_player_separator show separator if more than one player (default ' ')
players list of players to track. An empty list tracks all players (default [])
replacements specify a list/dict of string placeholders to modify (default None)
seek_delta time (in seconds) to change the playback's position by (default 5)
thresholds specify color thresholds to use for different placeholders (default {\"status\": [(\"Playing\", \"good\"), (\"Paused\", \"degraded\"), (\"Stopped\", \"bad\")]})
volume_delta percentage (from 0 to 100) to change the player's volume by (default 10)
Not all players support every button action
Format placeholders:
{format_player} format for playersFormat player placeholders:
{album} album name
{artist} artist name
{duration} length of track/video in [HH:]MM:SS, e.g. 03:22
{loop} loop status of the player, e.g. None, playlist, Track
{player} name of the player
{position} elapsed time in [HH:]MM:SS, e.g. 00:17
{shuffle} boolean indicating if the player's shuffle mode is on
{status} playback status, e.g. Playing, Paused, Stopped
{title} track/video title
{trackNumber} position of the track in the album or playlist
{volume} volume level of the player from 0 to 100
Not all media players support every placeholder
Requires:
playerctl mpris media player controller and lib for spotify, vlc, audacious, bmp, xmms2, and others.
python-gobject Python Bindings for GLib/GObject/GIO/GTK+
author jdholtz
"},{"location":"user-guide/modules/#pomodoro","title":"pomodoro","text":"Use Pomodoro technique to get things done easily.
Button 1 starts/pauses countdown. Button 2 switch Pomodoro/Break. Button 3 resets timer.
Configuration parameters:
display_bar display time in bars when True, otherwise in seconds (default False)
format define custom time format. See placeholders below (default '{ss}')
format_active format to display when timer is active (default 'Pomodoro [{format}]')
format_break format to display during break (default 'Break #{breakno} [{format}]')
format_break_stopped format to display during a break that is stopped (default 'Break #{breakno} ({format})')
format_separator separator between minutes:seconds (default ':')
format_stopped format to display when timer is stopped (default 'Pomodoro ({format})')
num_progress_bars number of progress bars (default 5)
pomodoros specify a number of pomodoros (intervals) (default 4)
sound_break_end break end sound (file path) (default None)
sound_pomodoro_end pomodoro end sound (file path) (default None)
sound_pomodoro_start pomodoro start sound (file path) (default None)
timer_break normal break time (seconds) (default 300)
timer_long_break long break time (seconds) (default 900)
timer_pomodoro pomodoro time (seconds) (default 1500)
Format placeholders:
{bar} display time in bars
{breakno} current break number
{ss} display time in total seconds (1500)
{mm} display time in total minutes (25)
{mmss} display time in (hh-)mm-ss (25:00)
Color options:
color_bad Pomodoro not running
color_degraded Pomodoro break
color_good Pomodoro active
Examples:
pomodoro {\n format = \"{mmss} {bar}\"\n}\nauthor Fandekasp (Adrien Lemaire), rixx, FedericoCeratto, schober-ch, ricci
"},{"location":"user-guide/modules/#process_status","title":"process_status","text":"Display status of a process on your system.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default '{icon}')
full match against the full command line (default False)
icon_off show this if a process is not running (default '\u25a0')
icon_on show this if a process is running (default '\u25cf')
process specify a process name to use (default None)
Format placeholders:
{icon} process icon
{process} process name
Color options:
color_bad Not running
color_good Running
author obb, Moritz L\u00fcdecke
"},{"location":"user-guide/modules/#prometheus","title":"prometheus","text":"Displays result of a Prometheus query.
Configuration parameters:
color Text colour. Supports py3status colour names. Examples: GOOD, DEGRADED, BAD, #E9967A (default None)
format Formatting of query result. Can refer to all labels from the query result. Query value placeholder __v. (default \"{__v:.0f}\")
join If query returned multiple rows, join them using this string. If you want to show just one, update your query. (default None)
query The PromQL query (default None)
query_interval Re-query interval in seconds. (default 60)
server str, URL pointing at your Prometheus(-compatible) server, example: http://prom.int.mydomain.net:9090 (default None)
units Dict with py3.format_units arguments, if you want human-readable unit formatting. Example: {\"unit\": \"Wh\", \"si\": True} If used, __v placeholder will contain formatted output. __n and __u will contain number and unit separately if you want to more finely control formatting. (default None)
Dynamic format placeholders: All query result labels are available as format placeholders. The vector values themselves are in placeholder __v. (Or __n and __u if you specified units).
Examples: # If blackbox exporter ran into any failures, show it. If everything # is healthy this will produce 0 rows hence not shown. query = \"probe_success == 0\" format = \"\ud83d\udc80 {job} {instance} \ud83d\udc80\" color = \"bad\"
# Basic Prometheus stat\nquery = \"sum(prometheus_sd_discovered_targets)\"\nformat = \"{__v:.0f} targets monitored\"\ncolor = \"ok\"\nauthor github.com/Wilm0r
"},{"location":"user-guide/modules/#rainbow","title":"rainbow","text":"Add color cycling fun to your i3bar.
This is the most pointless yet most exciting module you can imagine.
It allows color cycling of modules. Imagine the joy of having the current time change through the colors of the rainbow.
If you were completely insane you could also use it to implement the i3bar equivalent of the <blink> tag and cause yourself endless headaches and the desire to vomit.
The color for the contained module(s) is changed and cycles through your chosen gradient by default this is the colors of the rainbow. This module will increase the amount of updates that py3status needs to do so should be used sparingly.
Configuration parameters:
cycle_time How often we change this color in seconds (default 1)
force If True then the color will always be set. If false the color will only be changed if it has not been set by a module. (default False)
format display format for this module (default '{output}')
gradient The colors we will cycle through, This is a list of hex values (default [ '#FF0000', '#FFFF00', '#00FF00', '#00FFFF', '#0000FF', '#FF00FF', '#FF0000', ])
multi_color If True then each module the rainbow contains will be colored differently (default True)
steps Number of steps between each color in the gradient (default 10)
Format placeholders:
{output} rainbow outputExamples:
# show time colorfully\norder += \"rainbow time\"\nrainbow time {\n time {}\n}\n\n# blinking text black/white\norder += \"rainbow blink_time\"\nrainbow blink_time {\n gradient = [\n '#FFFFFF',\n '#000000',\n ]\n steps = 1\n time {}\n}\nauthor tobes
"},{"location":"user-guide/modules/#rate_counter","title":"rate_counter","text":"Display time spent and calculate the price of your service.
Configuration parameters:
cache_timeout how often to update in seconds (default 5)
config_file file path to store the time already spent and restore it the next session (default '~/.i3/py3status/counter-config.save')
format output format string (default 'Time: {days} day {hours}:{mins:02d} Cost: {total}')
format_money output format string (default '{price}$')
hour_price your price per hour (default 30)
tax tax value (1.02 = 2%) (default 1.02)
Format placeholders:
{days} The number of whole days in running timer
{hours} The remaining number of whole hours in running timer
{mins} The remaining number of whole minutes in running timer
{secs} The remaining number of seconds in running timer
{subtotal} The subtotal cost (time * rate)
{tax} The tax cost, based on the subtotal cost
{total} The total cost (subtotal + tax)
{total_hours} The total number of whole hours in running timer
{total_mins} The total number of whole minutes in running timer
format_money placeholders:
{price} numeric value of moneyColor options:
color_running Running, default color_good
color_stopped Stopped, default color_bad
author Amaury Brisou <py3status AT puzzledge.org>
"},{"location":"user-guide/modules/#rss_aggregator","title":"rss_aggregator","text":"Display unread feeds in your favorite RSS aggregator.
Configuration parameters:
aggregator feed aggregator used. Supported values are owncloud and ttrss. Other aggregators might be supported in future releases. Contributions are welcome. (default 'owncloud')
cache_timeout how often to run this check (default 60)
feed_ids list of IDs of feeds to watch, see note below (default [])
folder_ids list of IDs of folders ro watch (default [])
format format to display (default 'Feed: {unseen}')
password login password (default None)
server aggregator server to connect to (default 'https://yourcloudinstance.com')
user login user (default None)
Format placeholders:
{unseen} sum of numbers of unread feed elementsColor options:
color_new_items text color when there is new items (default color_good)
color_error text color when there is an error (default color_bad)
Requires:
requests python module from pypi https://pypi.python.org/pypi/requestsNotes: You can also decide to check only for specific feeds or folders of feeds. To use this feature, you have to first get the IDs of those feeds or folders. You can get those IDs by clicking on the desired feed or folder and watching the URL.
For OwnCloud/NextCloud with News application:\nhttps://yourcloudinstance.com/index.php/apps/news/#/items/feeds/FEED_ID\nhttps://yourcloudinstance.com/index.php/apps/news/#/items/folders/FOLDER_ID\n\nFor Tiny Tiny RSS 1.6 or newer:\nhttps://yourttrssinstance.com/index.php#f=FEED_ID&c=0\nhttps://yourttrssinstance.com/index.php#f=FOLDER_ID&c=1\n\nIf both feeds list and folders list are left empty, all unread feed items\nwill be counted. You may use both feeds list and folders list, but given\nfeeds shouldn't be included in given folders, else unread count number\nbehavior is unpredictable. Same warning when aggregator allows subfolders:\nthe folders list shouldn't include a folder and one of its subfolder.\nauthor raspbeguy
"},{"location":"user-guide/modules/#rt","title":"rt","text":"Display number of ongoing tickets from RT queues.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 300)
db database to use (default '')
format see placeholders below (default 'general: {General}')
host database host to connect to (default '')
password login password (default '')
threshold_critical set bad color above this threshold (default 20)
threshold_warning set degraded color above this threshold (default 10)
timeout timeout for database connection (default 5)
user login user (default '')
Format placeholders:
{YOUR_QUEUE_NAME} number of ongoing RT tickets (open+new+stalled)Color options:
color_bad Exceeded threshold_critical
color_degraded Exceeded threshold_warning
Requires: PyMySQL: https://pypi.org/project/PyMySQL/ or MySQL-python: https://pypi.org/project/MySQL-python/
It features thresholds to colorize the output and forces a low timeout to limit the impact of a server connectivity problem on your i3bar freshness.
author ultrabug
"},{"location":"user-guide/modules/#scratchpad","title":"scratchpad","text":"Display number of scratchpad windows and urgency hints.
Configuration parameters:
cache_timeout refresh interval for i3-msg or swaymsg (default 5)
format display format for this module (default \"\u232b [\\?color=scratchpad {scratchpad}]\")
thresholds specify color thresholds to use (default [(0, \"darkgray\"), (1, \"violet\")])
Format placeholders:
{scratchpad} number of scratchpads
{urgent} number of urgent scratchpads
Color thresholds:
xxx print a color based on the value of xxx placeholderOptional:
i3ipc an improved python library to control i3wm and swayExamples:
# hide zero scratchpad\nscratchpad {\n format = '[\\?not_zero \u232b [\\?color=scratchpad {scratchpad}]]'\n}\n\n# hide non-urgent scratchpad\nscratchpad {\n format = '[\\?not_zero \u232b {urgent}]'\n}\n\n# bring up scratchpads on clicks\nscratchpad {\n on_click 1 = 'scratchpad show'\n}\n\n# add more colors\nscratchpad {\n thresholds = [\n (0, \"darkgray\"), (1, \"violet\"), (2, \"deepskyblue\"), (3, \"lime\"),\n (4, \"yellow\"), (5, \"orange\"), (6, \"red\"), (7, \"tomato\"),\n ]\n}\nauthor shadowprince (counter), cornerman (async)
license Eclipse Public License (counter), BSD (async)
"},{"location":"user-guide/modules/#screenshot","title":"screenshot","text":"Take screenshots and upload them to a given server.
Configuration parameters:
file_length generated file_name length (default 4)
format display format for this module (default '\\?color=good [{basename}|\\?show SHOT]')
save_path Directory where to store your screenshots (default '~/Pictures')
screenshot_command the command used to generate the screenshot (default 'gnome-screenshot -f')
upload_path the remote path where to push the screenshot (default None)
upload_server your server address (default None)
upload_user your ssh user (default None)
Format placeholders:
{basename} generated basename, eg qs60.jpgExamples:
# push screenshots to a server\nscreenshot {\n save_path = \"~/Pictures/\"\n upload_user = \"erol\"\n upload_server = \"puzzledge.org\"\n upload_path = \"/files\"\n\n # scp $HOME/Pictures/$UUID.jpg erol@puzzledge.org:/files\n}\nauthor Amaury Brisou <py3status AT puzzledge.org>
"},{"location":"user-guide/modules/#scroll","title":"scroll","text":"Scroll modules.
Configuration parameters:
cache_timeout refresh interval for this module (default 1)
length specify a length of characters to scroll (default 25)
Format placeholders:
{output} outputauthor farnoy
"},{"location":"user-guide/modules/#selinux","title":"selinux","text":"Display SELinux state.
This module displays the state of SELinux on your machine: Enforcing (good), Permissive (degraded), or Disabled (bad).
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default 'SELinux: {state}')
state_disabled show when no SELinux policy is loaded. (default 'disabled')
state_enforcing show when SELinux security policy is enforced. (default 'enforcing')
state_permissive show when SELinux prints warnings instead of enforcing. (default 'permissive')
Format placeholders:
{state} SELinux stateColor options:
color_bad Enforcing
color_degraded Permissive
color_good Disabled
Requires:
libselinux-python SELinux python bindings for libselinuxauthor bstinsonmhk
license BSD
"},{"location":"user-guide/modules/#spaceapi","title":"spaceapi","text":"Display status of a given hackerspace.
Configuration parameters:
button_url mouse button to open URL sent in space's API (default 3)
cache_timeout refresh interval for this module (default 60)
format display format for this module (default '{state}[ {lastchanged}]')
format_lastchanged display format for time (default 'since %H:%M')
state_closed show when hackerspace is closed (default 'closed')
state_open show when hackerspace is open (default 'open')
url specify JSON URL of a hackerspace to retrieve from (default 'https://status.chaospott.de/status.json')
Format placeholders:
{state} Hackerspace state
{lastchanged} Time
format_lastchanged conversion: '%' Strftime characters to be translated
Color options:
color_closed Space closed, defaults to color_bad
color_open Space open, defaults to color_good
author timmszigat
license WTFPL <http://www.wtfpl.net/txt/copying/>
"},{"location":"user-guide/modules/#speedtest","title":"speedtest","text":"Perform a bandwidth test with speedtest-cli.
Use middle-click to start the speed test.
Configuration parameters:
button_share mouse button to share an URL (default None)
format display format for this module (default \"speedtest[\\?if=elapsed&color=elapsed_time \" \"{elapsed_time}s][ [\\?color=download \u2193{download}Mbps] \" \"[\\?color=upload \u2191{upload}Mbps]]\")
thresholds specify color thresholds to use (default {\"upload\": [(0, \"violet\")], \"ping\": [(0, \"#fff381\")], \"download\": [(0, \"cyan\")], \"elapsed_time\": [(0, \"#1cbfff\")]})
Control placeholders:
{elapsed} elapsed time state, eg False, TrueFormat placeholders:
{bytes_sent} bytes sent during test (in MB), eg 52.45
{bytes_received} bytes received during test (in MB), eg 70.23
{client_country} client country code, eg FR
{client_ip} client ip, eg 78.194.13.7
{client_isp} client isp, eg Free SAS
{client_ispdlavg} client isp download average, eg 0
{client_isprating} client isp rating, eg 3.7
{client_ispulavg} client isp upload average, eg 0
{client_lat} client latitude, eg 48.8534
{client_loggedin} client logged in, eg 0
{client_lon} client longitude, eg 2.3487999999999998
{client_rating} client rating, eg 0
{download} download speed (in MB), eg 20.23
{elapsed_time} elapsed time since speedtest start
{ping} ping time in ms to speedtest server
{server_cc} server country code, eg FR
{server_country} server country, eg France
{server_d} server distance, eg 2.316599376968091
{server_host} server host, eg speedtest.telecom-paristech.fr:8080
{server_id} server id, eg 11977
{share} share, eg share url
{timestamp} timestamp, eg 2018-08-30T16:27:25.318212Z
{server_lat} server latitude, eg 48.8742
{server_latency} server latency, eg 8.265
{server_lon} server longitude, eg 2.3470
{server_name} server name, eg Paris
{server_sponsor} server sponsor, eg T\u00e9l\u00e9com ParisTech
{server_url} server url, eg http://speedtest.telecom-paristech...
{upload} upload speed (in MB), eg 20.23
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
speedtest-cli Command line interface for testing Internet bandwidthExamples:
# show detailed elapsed_time|download/upload\nspeedtest {\n format = \"speedtest[\\?soft ][\\?if=elapsed [\\?color=darkgray [time \"\n format += \"[\\?color=elapsed_time {elapsed_time} s]]]|[\\?color=darkgray \"\n # format += \"ping [\\?color=ping {ping} ms] \"\n format += \"download [\\?color=download {download}Mbps] \"\n format += \"upload [\\?color=upload {upload}Mbps]]]\"\n}\n\n# show everything\nspeedtest {\n format = \"speedtest[\\?soft ][\\?color=darkgray \"\n format += \"[time [\\?color=elapsed_time {elapsed_time} s]][\\?soft ]\"\n format += \"[ping [\\?color=ping {ping} ms] \"\n format += \"download [\\?color=download {download}Mbps] \"\n format += \"upload [\\?color=upload {upload}Mbps]]]\"\n}\n\n# minimal\nspeedtest {\n format = \"speedtest[\\?soft ][\\?if=elapsed \"\n format += \"[\\?color=elapsed_time {elapsed_time}]|\"\n # format += \"[\\?color=ping {ping}] \"\n format += \"[[\\?color=download {download}] [\\?color=upload {upload}]]]\"\n}\n\n# don't hide data on reset\nspeedtest {\n format = \"speedtest[\\?soft ][\\?color=darkgray time \"\n format += \"[\\?color=elapsed_time {elapsed_time} s] \"\n # format += \"ping [\\?color=ping {ping} ms] \"\n format += \"download [\\?color=download {download}Mbps] \"\n format += \"upload [\\?color=upload {upload}Mbps]]\"\n}\n\n# don't hide data on reset, minimal\nspeedtest {\n format = \"speedtest[\\?soft ][[\\?color=elapsed_time {elapsed_time}] \"\n # format += \"[\\?color=ping {ping}] \"\n format += \"[\\?color=download {download}] [\\?color=upload {upload}]]\"\n}\nauthor Cyril Levis (@cyrinux)
"},{"location":"user-guide/modules/#spotify","title":"spotify","text":"Display song currently playing in Spotify.
Configuration parameters:
button_next button to switch to next song (default None)
button_play_pause button to toggle play/pause (default None)
button_previous button to switch to previous song (default None)
cache_timeout how often to update the bar (default 5)
dbus_client Used to override which app is used as a client for spotify. If you use spotifyd as a client, set this to 'org.mpris.MediaPlayer2.spotifyd' (default 'org.mpris.MediaPlayer2.spotify')
format see placeholders below (default '{artist} : {title}')
format_down define output if spotify is not running (default 'Spotify not running')
format_stopped define output if spotify is not playing (default 'Spotify stopped')
replacements specify a list/dict of string placeholders to modify (default None)
Format placeholders:
{album} album name
{artist} artiste name (first one)
{playback} state of the playback: Playing, Paused
{time} time duration of the song
{title} name of the song
Color options:
color_offline Spotify is not running, defaults to color_bad
color_paused Song is stopped or paused, defaults to color_degraded
color_playing Song is playing, defaults to color_good
Requires:
python-dbus to access dbus in python
spotify a proprietary music streaming service
Examples:
spotify {\n button_next = 4\n button_play_pause = 1\n button_previous = 5\n format = \"{title} by {artist} -> {time}\"\n format_down = \"no Spotify\"\n\n # sanitize\n replacements = {\n \"album\": [(\"\\s?[\\(\\[\\-,;/][^)\\],;/]*?(bonus|demo|edit|explicit|extended|feat|mono|remaster|stereo|version)[^)\\],;/]*[\\)\\]]?\", \"\")],\n \"title\": [(\"\\s?[\\(\\[\\-,;/][^)\\],;/]*?(bonus|demo|edit|explicit|extended|feat|mono|remaster|stereo|version)[^)\\],;/]*[\\)\\]]?\", \"\")]\n }\n}\nauthor Pierre Guilbert, Jimmy Garpeh\u00e4ll, sondrele, Andrwe
"},{"location":"user-guide/modules/#sql","title":"sql","text":"Display data stored in MariaDB, MySQL, sqlite3, and hopefully more.
Configuration parameters:
cache_timeout refresh cache_timeout for this module (default 10)
database specify database name to import (default None)
format display format for this module (default '{format_row}')
format_row display format for SQL rows (default None)
format_separator show separator if more than one (default ' ')
parameters specify connection parameters to use (default None)
query specify command to query a database (default None)
thresholds specify color thresholds to use (default [])
Format placeholders:
{row} number of SQL rows
{format_row} format for SQL rows Parameters can be placeholders too, eg {host}, {passd}
Format_row placeholders:
{field} placeholders will have the value returned by the query for the fieldColor thresholds:
format row: print a color based on the number of SQL rows
format_row field: print a color based on the value of field placeholder
Requires:
mariadb fast sql database server, drop-in replacement for mysql
mysql-python mysql support for python
sqlite a c library that implements an sql database engine
Examples:
# specify database name to import\nsql {\n database = 'sqlite3' # from sqlite3 import connect\n database = 'MySQLdb' # from MySQLdb import connect\n database = '...' # from ... import connect\n}\n\n# specify connection parameters to use\nhttp://mysql-python.sourceforge.net/MySQLdb.html#functions-and-attributes\nhttps://docs.python.org/3/library/sqlite3.html#module-functions-and-constants\nsql {\n name = 'MySQLdb'\n format = '{host} {passd} ...'\n parameters = {\n 'host': 'host',\n 'passwd': 'password',\n '...': '...',\n }\n}\n\n# specify command to query a database\nsql {\n query = 'SHOW SLAVE STATUS'\n query = 'SELECT * FROM cal_todos'\n query = '...'\n}\n\n# display number of seconds behind master with MySQLdb\nsql {\n database = 'MySQLdb'\n format_row = '\\?color=seconds_behind_master {host} is '\n format_row += '[{seconds_behind_master}s behind|\\?show master]'\n parameters = {\n 'host': 'localhost',\n 'passwd': '********'\n }\n query = 'SHOW SLAVE STATUS'\n thresholds = [\n (0, 'deepskyblue'), (100, 'good'), (300, 'degraded'), (600, 'bad')\n ]\n}\n\n# display thunderbird tasks with sqlite3\nsql {\n database = 'sqlite3'\n format_row = '{title}'\n format_separator = ', '\n query = 'SELECT * FROM cal_todos'\n parameters = '~/.thunderbird/user.default/calendar-data/local.sqlite'\n}\nauthor cereal2nd
license BSD
"},{"location":"user-guide/modules/#static_string","title":"static_string","text":"Display static text.
Configuration parameters:
format display format for this module (default 'Hello, world!')author frimdo ztracenastopa@centrum.cz
"},{"location":"user-guide/modules/#sway_idle","title":"sway_idle","text":"Display sway inhibit idle status.
This Module shows an indicator, if an idle is inhibited by an inhibitor. For more information about inhibit idle see man 5 sway
Configuration parameters:
cache_timeout How often we refresh this module in seconds (default 1)
format Display format (default 'Inhibit Idle: {inhibit_idle}')
Format placeholders:
{inhibit_idle} Returns 'True' if idle is inhibited, 'False' else.Example:
sway_idle {\n format = \"Inhibit Idle: [\\?if=inhibit_idle=True True]|False\"\n}\nauthor Valentin Weber <valentin+py3status@wv2.ch>
license BSD
"},{"location":"user-guide/modules/#sysdata","title":"sysdata","text":"Display system RAM, SWAP and CPU utilization.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 10)
cpu_freq_unit the unit of CPU frequency to use in report, case insensitive. ['kHz', 'MHz', 'GHz'] (default 'GHz')
cpu_temp_unit specify cpu temperature unit ['C', 'F', 'K'] (default 'C')
cpus specify a list of CPUs to use (default ['cpu?'])*
format output format string (default '[\\?color=cpu_used_percent CPU: {cpu_used_percent}%], ' '[\\?color=mem_used_percent Mem: {mem_used}/{mem_total} ' '{mem_total_unit} ({mem_used_percent}%)]')
format_cpu display format for CPUs (default '\\?color=used_percent {used_percent}%')
format_cpu_separator show separator if more than one (default ' ')
mem_unit the unit of memory to use in report, case insensitive. ['dynamic', 'KiB', 'MiB', 'GiB'] (default 'GiB')
swap_unit the unit of swap to use in report, case insensitive. ['dynamic', 'KiB', 'MiB', 'GiB'] (default 'GiB')
thresholds specify color thresholds to use (default [(0, \"good\"), (40, \"degraded\"), (75, \"bad\")])
Format placeholders:
{cpu_freq_avg} average CPU frequency across all cores
{cpu_freq_max} highest CPU clock frequency
{cpu_freq_unit} unit for frequency
{cpu_temp} cpu temperature
{cpu_temp_unit} cpu temperature unit
{cpu_used_percent} cpu used percentage
{format_cpu} format for CPUs
{load1} load average over the last minute
{load5} load average over the five minutes
{load15} load average over the fifteen minutes
{mem_total} total memory
{mem_total_unit} memory total unit, eg GiB
{mem_used} used memory
{mem_used_unit} memory used unit, eg GiB
{mem_used_percent} used memory percentage
{mem_free} free memory
{mem_free_unit} free memory unit, eg GiB
{mem_free_percent} free memory percentage
{swap_total} total swap
{swap_total_unit} swap total memory unit, eg GiB
{swap_used} used swap
{swap_used_unit} swap used memory unit, eg GiB
{swap_used_percent} used swap percentage
{swap_free} free swap
{swap_free_unit} free swap unit, eg GiB
{swap_free_percent} free swap percentage
format_cpu placeholders:
{name} cpu name, eg cpu, cpu0, cpu1, cpu2, cpu3
{used_percent} cpu used percentage, eg 88.99
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
lm_sensors a tool to read cpu temperatureExamples:
# specify a list of cpus to use. see \"grep cpu /proc/stat\"\nsysdata {\n cpus = [] # avg + all CPUs\n cpus = ['cpu'] # avg # same as {cpu_used_percent}\n cpus = ['cpu0', 'cpu2'] # selective CPUs # full\n cpus = ['cpu?*'] # all CPUs # fnmatch (default)\n}\n\n# display per cpu percents\nsysdata {\n format = \"{format_cpu}\"\n format_cpu = \"{name} [\\?color=used_percent {used_percent}%]\"\n}\n\n# customize per cpu padding, precision, etc\nsysdata {\n format = \"CPU {format_cpu}\"\n format_cpu = \"[\\?min_length=4 [\\?color=used_percent {used_percent:.0f}%]]\"\n}\n\n# display per cpu histogram\nsysdata {\n format = \"CPU Histogram [\\?color=cpu_used_percent {format_cpu}]\"\n format_cpu = \"[\\?if=used_percent>80 \u2847|[\\?if=used_percent>60 \u2846\"\n format_cpu += \"|[\\?if=used_percent>40 \u2844|[\\?if=used_percent>20 \u2840\"\n format_cpu += \"|\u2800]]]]\"\n format_cpu_separator = \"\"\n thresholds = [(0, \"good\"), (60, \"degraded\"), (80, \"bad\")]\n cache_timeout = 1\n}\nauthor Shahin Azad <ishahinism at Gmail>, shrimpza, guiniol, JackDoan <me at jackdoan dot com>, farnoy
"},{"location":"user-guide/modules/#systemd","title":"systemd","text":"Display status of a service on your system.
Configuration parameters:
cache_timeout refresh interval for this module (default 5)
format display format for this module (default '\\?if=!hide {unit}: {status}')
hide_extension suppress extension of the systemd unit (default False)
hide_if_default suppress the output if the systemd unit is in default state 'off' the output is never suppressed 'on' the output is suppressed if the unit is (enabled and active) or (disabled and inactive) 'active' the output is suppressed if the unit is active 'inactive' the output is suppressed if the unit is inactive (default 'off')
unit specify the systemd unit to use (default 'dbus.service')
user specify if this is a user service (default False)
Format placeholders:
{unit} unit name, eg sshd.service
{status} unit status, eg active, inactive, not-found
Color options:
color_good unit active
color_bad unit inactive
color_degraded unit not-found
Requires:
dbus-python to interact with dbus
pygobject which in turn requires libcairo2-dev, libgirepository1.0-dev
Examples:
# show the status of vpn service\n# left click to start, right click to stop\nsystemd vpn {\n unit = 'vpn.service'\n on_click 1 = 'exec sudo systemctl start vpn'\n on_click 3 = 'exec sudo systemctl stop vpn'\n}\nauthor Adrian Lopez <adrianlzt@gmail.com>
license BSD
"},{"location":"user-guide/modules/#systemd_suspend_inhibitor","title":"systemd_suspend_inhibitor","text":"Turn on and off systemd suspend inhibitor.
Configuration parameters:
format display format for this module (default '[\\?color=state SUSPEND [\\?if=state OFF|ON]]')
lock_types specify state to inhibit, comma separated list https://www.freedesktop.org/wiki/Software/systemd/inhibit/ (default ['handle-lid-switch', 'idle', 'sleep'])
thresholds specify color thresholds to use (default [(True, 'bad'), (False, 'good')])
Format placeholders:
{state} systemd suspend inhibitor state, eg True, FalseColor thresholds:
xxx print a color based on the value of xxx placeholderauthor Cyrinux https://github.com/cyrinux
license BSD
"},{"location":"user-guide/modules/#taskwarrior","title":"taskwarrior","text":"Display tasks currently running in taskwarrior.
Configuration parameters:
cache_timeout refresh interval for this module (default 5)
filter specify one or more criteria to use (default 'status:pending')
format display format for this module (default '{descriptions}')
report report to export, for TaskWarrior 2.6.0 and above (default '')
Format placeholders:
{descriptions} descriptions of active tasks
{tasks} number of active tasks
Requires task: https://taskwarrior.org/download/
author James Smith https://jazmit.github.io
license BSD
"},{"location":"user-guide/modules/#thunderbird_todos","title":"thunderbird_todos","text":"Display number of todos and more for Thunderbird.
Configuration parameters:
cache_timeout refresh interval for this module (default 60)
format display format for this module (default '{format_todo}')
format_datetime specify strftime formatting to use (default {})
format_separator show separator if more than one (default ' ')
format_todo display format for todos (default '\\?if=!todo_completed {title}')
profile specify a profile path, otherwise first available profile eg '~/.thunderbird/abcd1234.default' (default None)
sort specify a tuple, eg ('placeholder_name', reverse_boolean) to sort by; excluding placeholder indexes (default ())
thresholds specify color thresholds to use (default [])
Format placeholders:
{todo_total} eg 5
{todo_completed} eg 2
{todo_incompleted} eg 3
{format_todo} format for todos
format_todo placeholders:
{index_total} eg 1, 2, 3
{index_completed} eg 1, 2, 3
{index_incompleted} eg 1, 2, 3
{alarm_last_ack} eg None, 1513291952000000
{cal_id} eg 966bd855-5e71-4168-8072-c98f244ed825
{flags} eg 4, 276
{ical_status} eg None, IN-PROCESS, COMPLETED
{id} eg 87e9bfc9-eaad-4aa6-ad5f-adbf6d7a11a5
{last_modified} eg 1513276147000000
{offline_journal} eg None
{priority} eg None, # None=None, 0=None, 1=High, 5=Normal, 9=Low
{privacy} eg None, CONFIDENTIAL
{recurrence_id} eg None
{recurrence_id_tz} eg None, UTC
{time_created} eg 1513276147000000
{title} eg New Task
{todo_complete} eg None
{todo_completed} eg None, 1513281528000000
{todo_completed_tz} eg None, UTC
{todo_due} eg None, 1513292400000000
{todo_due_tz} eg None, America/Chicago
{todo_entry} eg None, 1513292400000000
{todo_entry_tz} eg None, America/Chicago
{todo_stamp} eg 1513276147000000
format_datetime placeholders: KEY: alarm_last_ack, last_modified, time_created, todo, todo_completed, todo_entry, todo_stamp VALUE: % strftime characters to be translated, eg '%b %d' ----> 'Dec 14' SEE EXAMPLE BELOW: \"show incompleted titles with last modified time\"
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
thunderbird standalone mail and news readerExamples:
# show number of incompleted titles\nthunderbird_todos {\n format = '{todo_incompleted} incompleted todos'\n}\n\n# show rainbow number of incompleted titles\nthunderbird_todos {\n format = '\\?color=todo_incompleted {todo_incompleted} todos'\n thresholds = [\n (1, '#bababa'), (2, '#ffb3ba'), (3, '#ffdfba'), (4, '#ffffba'),\n (5, '#baefba'), (6, '#baffc9'), (7, '#bae1ff'), (8, '#bab3ff')\n ]\n}\n\n# show rainbow incompleted titles\nthunderbird_todos {\n format_todo = '\\?if=!todo_completed&color=index_incompleted {title}'\n thresholds = [\n (1, '#bababa'), (2, '#ffb3ba'), (3, '#ffdfba'), (4, '#ffffba'),\n (5, '#baefba'), (6, '#baffc9'), (7, '#bae1ff'), (8, '#bab3ff')\n ]\n}\n\n# show incompleted titles with last modified time\nthunderbird_todos {\n format_todo = '\\?if=!todo_completed {title} {last_modified}'\n format_datetime = {\n 'last_modified': '\\?color=degraded last modified %-I:%M%P'\n }\n}\n\n# show 'No todos'\nthunderbird_todos {\n format = '{format_todo}|No todos'\n}\n\n# show completed titles and incompleted titles\nthunderbird_todos {\n format_todo = '\\?if=todo_completed&color=good {title}|\\?color=bad {title}'\n}\n\n# make todo blocks\nthunderbird_todos {\n format = 'TODO {format_todo}'\n format_todo = '\\?if=todo_completed&color=good \u25b0|\\?color=bad \u25b0'\n format_separator = ''\n}\n\n# display incompleted titles with any priority\nthunderbird_todos {\n format_todo = '\\?if=!todo_completed [\\?if=priority>0 {title}]'\n}\n\n# colorize titles based on priorities\nthunderbird_todos {\n format_todo = '\\?if=!todo_completed [\\?color=priority {title}]'\n thresholds = [(0, None), (1, 'red'), (5, None), (9, 'deepskyblue')]\n}\n\n# sort todos\nthunderbird_todos {\n sort = ('last_modified', True) # sort by modified time: recent first\n sort = ('priority', True) # sort by priority: high to low\n sort = ('title', False) # sort by title: ABC to abc\n}\n\n# add your snippets here\nthunderbird_todos {\n format = '...'\n}\nauthor mrt-prodz, lasers
"},{"location":"user-guide/modules/#timer","title":"timer","text":"A simple countdown timer.
This is a very basic countdown timer. You can change the timer length as well as pausing, restarting and resetting it. Currently this is more of a demo of a composite.
Each part of the timer can be changed independently hours, minutes, seconds using mouse buttons 4 and 5 (scroll wheel). Button 1 starts/pauses the countdown. Button 2 resets timer.
Configuration parameters:
format display format for this module (default 'Timer {timer}')
sound play sound file path when the timer ends (default None)
time number of seconds to start countdown with (default 60)
Format placeholders:
{timer} display hours:minutes:secondsauthor tobes
"},{"location":"user-guide/modules/#timewarrior","title":"timewarrior","text":"Track your time with Timewarrior.
Timewarrior is a time tracking utility that offers simple stopwatch features as well as sophisticated calendar-base backfill, along with flexible reporting. See https://taskwarrior.org/docs/timewarrior for more information.
Configuration parameters:
cache_timeout refresh interval for this module, otherwise auto (default None)
filter specify interval and/or tag to filter (default '1day')
format display format for this module (default '[Timew {format_time}]|No Timew')
format_datetime specify strftime characters to format (default {})
format_duration display format for time duration (default '\\?not_zero [{days}d ][{hours}:]{minutes}:{seconds}')
format_tag display format for tags (default '\\?color=state_tag {name}')
format_tag_separator show separator if more than one (default ' ')
format_time display format for tracked times (default '[\\?color=state_time [{format_tag} ]{format_duration}]')
format_time_separator show separator if more than one (default ' ')
thresholds specify color thresholds to use (default {'state_tag': [(0, 'darkgray'), (1, 'darkgray')], 'state_time': [(0, 'darkgray'), (1, 'degraded')]})
Format placeholders:
{format_time} format for tracked times
{tracking} time tracking state, eg False, True
format_time placeholders:
{state} time tracking state, eg False, True
{format_tag} format for tags
{format_duration} format for time duration
{start} start date, eg 20171021T010203Z
{end} end date, eg 20171021T010203Z
format_tag placeholders:
{name} tag name, eg gaming, studying, gardeningformat_datetime placeholders:
key start, end
value strftime characters, eg '%b %d' ----> 'Oct 06'
format_duration placeholders:
{days} days
{hours} hours
{minutes} minutes
{seconds} seconds
Color thresholds:
format_time state_time: print color based on the state of time tracking
format_tag state_tag: print color based on the state of time tracking
Requires:
timew feature-rich time tracking utilityRecommendations: We can refresh a module using py3-cmd command. An excellent example of using this command in a function.
```\n~/.{bash,zsh}{rc,_profile}\n---------------------------\nfunction timew () {\n command timew \"$@\" && py3-cmd refresh timewarrior\n}\n```\n\nWith this, you can consider giving `cache_timeout` a much larger number,\neg 3600 (an hour), so the module does not need to be updated that often.\nExamples:
# show times matching the filter, see documentation for more filters\ntimewarrior {\n filter = ':day' # filter times not in 24 hours of current day\n filter = '12hours' # filter times not in 12 hours of current time\n filter = '5min' # filter times not in 5 minutes of current time\n filter = '1sec' # filter times not in 1 second of current time\n filter = '5pm to 11:59pm # filter times not in 5pm to 11:59pm range\n}\n\n# intervals\ntimewarrior {\n # if you are printing other intervals too with '1day' filter or so,\n # then you may want to add this too for better bar readability\n format_time_separator = ', '\n\n # you also can change the thresholds with different colors\n thresholds = {\n 'state_tag': [(0, 'darkgray'), (1, 'degraded')],\n 'state_time': [(0, 'darkgray'), (1, 'degraded')],\n }\n}\n\n# cache_timeout\ntimewarrior {\n # auto refresh every 10 seconds when there is no active time tracking\n # auto refresh every second when there is active time tracking\n cache_timeout = None\n\n # refresh every minute when there is no active time tracking\n # refresh every second when there is active time tracking\n cache_timeout = 60\n\n # explicit refresh every 20 seconds when there is no active time tracking\n # explicit refresh every 5 seconds when there is active time tracking\n cache_timeout = (20, 5)\n}\n\n# add your snippets here\ntimewarrior {\n format = \"...\"\n}\nauthor lasers
"},{"location":"user-guide/modules/#tor_rate","title":"tor_rate","text":"Display transfer rates of a tor instance.
Configuration parameters:
cache_timeout An integer specifying the cache life-time of the modules output in seconds (default 2)
control_address The address on which the Tor daemon listens for control connections (default \"127.0.0.1\")
control_password The password to use for the Tor control connection (default None)
control_port The port on which the Tor daemon listens for control connections (default 9051)
format A string describing the output format for the module (default \"\u2191 {up} \u2193 {down}\")
format_value A string describing how to format the transfer rates (default \"[\\?min_length=12 {rate:.1f} {unit}]\")
hide_socket_errors Hide errors connecting to Tor control socket (default False)
rate_unit The unit to use for the transfer rates (default \"B/s\")
si_units A boolean value selecting whether or not to use SI units (default False)
Format placeholders:
{down} The incoming transfer rate
{up} The outgoing transfer rate
format_value placeholders:
{rate} The current transfer-rate's value
{unit} The current transfer-rate's unit
Requires:
stem python controller library for tor https://pypi.org/project/stemExamples:
tor_rate {\n cache_timeout = 10\n format = \"IN: {down} | OUT: {up}\"\n control_port = 1337\n control_password = \"TertiaryAdjunctOfUnimatrix01\"\n si_units = True\n}\nauthor Felix Morgner <felix.morgner@gmail.com>
license 3-clause-BSD
"},{"location":"user-guide/modules/#transmission","title":"transmission","text":"Display number of torrents and more.
Configuration parameters:
arguments additional arguments for the transmission-remote (default None)
button_next mouse button to switch next torrent (default None)
button_previous mouse button to switch previous torrent (default None)
button_run mouse button to run the command on current torrent (default [(1, '--start'), (2, '--verify'), (3, '--stop')])
cache_timeout refresh interval for this module (default 20)
format display format for this module (default '{format_torrent}')
format_separator show separator if more than one (default ' ')
format_torrent display format for torrents (default '[\\?if=is_focused&color=bad X] {status} {id} {name} {done}%')
thresholds specify color thresholds to use (default [])
Format placeholders:
{torrent} number of torrents
{format_torrent} format for torrents
{up} summary up traffic
{down} summary down traffic
{have} summary download
format_torrent placeholders:
{index} torrent index, eg 1
{id} torrent id, eg 2
{done} torrent percent, eg 100%
{have} torrent download, 253 KB
{eta} torrent estimated time, eg Done, 1 min, etc
{up} torrent up traffic
{down} torrent down traffic
{ratio} torrent seed ratio
{status} torrent status, eg Idle, Downloading, Stopped, Verifying, etc
{name} torrent name, eg py3status-3.8.tar.gz
Color options:
color_bad current torrentColor thresholds:
xxx print a color based on the value of xxx placeholderRequires:
transmission-cli fast, easy, and free bittorrent client (cli tools, daemon, web client)Examples:
# add arguments\ntransmission {\n # We use 'transmission-remote --list'\n # See `transmission-remote --help' for more information.\n # Not all of the arguments will work here.\n arguments = '--auth username:password --port 9091'\n}\n# see 'man transmission-remote' for more buttons\ntransmission {\n button_run = [\n (1, '--start'),\n (2, '--verify'),\n (3, '--stop'),\n (8, '--remove'),\n (9, '--exit'),\n ]\n}\n\n# open web-based transmission client\ntransmission {\n on_click 1 = 'exec xdg-open http://username:password@localhost:9091'\n}\n\n# add buttons\ntransmission {\n button_next = 5\n button_previous = 4\n}\n\n# see 'man transmission-remote' for more buttons\ntransmission {\n # specify a script to run when a torrent finishes\n on_click 9 = 'exec transmission-remote --torrent-done-script ~/file'\n\n # use the alternate limits?\n on_click 9 = 'exec transmission-remote --alt-speed'\n on_click 10 = 'exec transmission-remote --no-alt-speed'\n}\n\n# show summary statistcs - up, down, have\ntransmission {\n format = '{format_torrent}'\n format += '[\\?color=#ffccff [\\?not_zero Up:{up}]'\n format += '[\\?not_zero Down:{down}][\\?not_zero Have:{have}]]'\n}\n\n# add a format that sucks less than the default plain format\ntransmission {\n format_torrent = '[\\?if=is_focused&color=bad X ]'\n format_torrent += '[[\\?if=status=Idle&color=degraded {status}]'\n format_torrent += '|[\\?if=status=Stopped&color=bad {status}]'\n format_torrent += '|[\\?if=status=Downloading&color=good {status}]'\n format_torrent += '|[\\?if=status=Verifying&color=good {status}]'\n format_torrent += '|\\?color=degraded {status}]'\n format_torrent += ' {name} [\\?color=done {done}]'\n}\n\n# show percent thresholds\ntransmission {\n format_torrent = '{name} [\\?color=done {done}]'\n thresholds = [(0, 'bad'), (1, 'degraded'), (100, 'good')]\n}\n\n# download the rainbow\ntransmission {\n format_torrent = '[\\?if=is_focused&color=bad X ]'\n format_torrent += '{status} [\\?color=index {name}] [\\?color=done {done}%]'\n thresholds = {\n 'done': [(0, '#ffb3ba'), (1, '#ffffba'), (100, '#baefba')],\n 'index': [\n (1, '#ffb3ba'), (2, '#ffdfba'), (3, '#ffffba'),\n (4, '#baefba'), (5, '#baffc9'), (6, '#bae1ff'),\n (7, '#bab3ff')\n ]\n }\n}\nauthor lasers
"},{"location":"user-guide/modules/#twitch","title":"twitch","text":"Display if a Twitch channel is currently streaming or not.
Configuration parameters:
cache_timeout how often we refresh this module in seconds (default 60)
client_id Your client id. Create your own key at https://dev.twitch.tv (default None)
client_secret Your client secret. (default None)
format Display format when online (default \"{display_name} is live!\")
format_offline Display format when offline (default \"{display_name} is offline.\")
format_tag Tag formatting (default \"{name}\")
locales List of locales to try for tag translations, eg. [\"cs-cz\", \"en-uk\", \"en-us\"]. If none is specified, auto-detect from environment, with a fallback to \"en-us\". (default [])
stream_name name of streamer(twitch.tv/<stream_name>) (default None)
tag_delimiter string to write between tags (default \" \")
trace enable trace level debugging (default False)
Stream format placeholders:
{display_name} User's display name., eg Ultrabug
{is_streaming} (bool) True if streaming, fields prefixed with stream_ are available.
{tags} List of tags
{user_id} User's id
{user_login} User's login name, eg xisumavoid
{user_display_name} (same as {display_name})
{user_type} \"staff\", \"admin\", \"global_mod\", or \"\"
{user_broadcaster_type} \"partner\", \"affiliate\", or \"\".
{user_description} User's channel description.
{user_profile_image_url} URL of the user's profile image.
{user_offline_image_url} URL of the user's offline image.
{user_view_count} Total number of views of the user's channel.
{user_created_at} Date when the user was created.
{stream_id} Stream ID.
{stream_game_id} ID of the game being played on the stream.
{stream_game_name} Name of the game being played.
{stream_title} Stream title.
{stream_viewer_count} Number of viewers watching the stream at the time of last update.
{stream_started_at} Stream start UTC timestamp.
{stream_language} Stream language. A language value is either the ISO 639-1 two-letter code or \u201cother\u201d.
{stream_thumbnail_url} Thumbnail URL of the stream. All image URLs have variable width and height. You can replace {width} and {height} with any values to get that size image
{stream_is_mature} Indicates if the broadcaster has specified their channel contains mature content that may be inappropriate for younger audiences.
{stream_runtime} (string) Stream runtime as a human readable, non-localized string. eg \"3h 5m\"
{stream_runtime_seconds} (int) Stream runtime in seconds.
Tag format placeholders: (see locales) {name} The tag name {desc} The tag description
Color options:
color_bad Stream offline
color_good Stream is live
Client ID: Example settings when creating your app at https://dev.twitch.tv
Name: <your_name>_py3status\nOAuth Redirect URI: https://localhost\nApplication Category: Application Integration\nauthor Alex Caswell horatioesf@virginmedia.com
author Julian Picht julian.picht@gmail.com
license BSD
"},{"location":"user-guide/modules/#uname","title":"uname","text":"Display system information.
Configuration parameters:
format display format for this module (default '{system} {release}')Format placeholders:
{system} system/OS name, e.g. 'Linux', 'Windows', or 'Java'
{node} computer\u2019s network name (may not be fully qualified!)
{release} system\u2019s release, e.g. '2.2.0' or 'NT'
{version} system\u2019s release version, e.g. '#3 on degas'
{machine} machine type, e.g. 'x86_64'
{processor} the (real) processor name, e.g. 'amdk6'
author ultrabug (inspired by ndalliard)
"},{"location":"user-guide/modules/#uptime","title":"uptime","text":"Display system uptime.
Configuration parameters:
format display format for this module (default 'up {days} days {hours} hours {minutes} minutes')Format placeholders:
{decades} decades
{years} years
{weeks} weeks
{days} days
{hours} hours
{minutes} minutes
{seconds} seconds
If you don't use a placeholder, its value will be carried over to the next placeholder. For example, an uptime of 1 hour 30 minutes will give you 90 if {minutes} or 1:30 if {hours}:{minutes}.
You also can specify strftime characters to print system up since with or without placeholders. See man strftime for more information.
Examples:
# show uptime without zeroes\nuptime {\n format = 'up [\\?if=weeks {weeks} weeks ][\\?if=days {days} days ]\n [\\?if=hours {hours} hours ][\\?if=minutes {minutes} minutes ]'\n}\n\n# show uptime in multiple formats using group module\ngroup uptime {\n format = \"up {output}\"\n uptime {\n format = '[\\?if=weeks {weeks} weeks ][\\?if=days {days} days ]\n [\\?if=hours {hours} hours ][\\?if=minutes {minutes} minutes]'\n }\n uptime {\n format = '[\\?if=weeks {weeks}w ][\\?if=days {days}d ]\n [\\?if=hours {hours}h ][\\?if=minutes {minutes}m]'\n }\n uptime {\n format = '[\\?if=days {days}, ][\\?if=hours {hours}:]\n [\\?if=minutes {minutes:02d}]'\n }\n}\n\n# specify strftime characters to display system up since\nuptime {\n format = \"{days}d {hours}:{minutes:02d}:{seconds:02d}\"\n format += \", up since %Y-%m-%d %H:%M:%S\"\n}\nauthor Alexis \"Horgix\" Chotard <alexis.horgix.chotard@gmail.com>, Volkov \"BabyWolf\" Semjon <Volkov.BabyWolf.Semjon@gmail.com>
license BSD
"},{"location":"user-guide/modules/#usbguard","title":"usbguard","text":"Allow or Reject newly plugged USB devices using USBGuard.
Configuration parameters:
format display format for this module (default '{format_device}')
format_button_allow display format for allow button filter (default '[Allow]')
format_button_reject display format for reject button filter (default '[Reject]')
format_device display format for USB devices (default '{format_button_reject} [{name}|{usb_id}] {format_button_allow}')
format_device_separator show separator if more than one (default ' ')
Format placeholders:
{device} number of USB devices
{format_device} format for USB devices
format_device:
{format_button_allow} button to allow the device
{format_button_reject} button to reject the device
{id} eg 1, 2, 5, 6, 7, 22, 23, 33
{policy} eg allow, block, reject
{usb_id} eg 054c:0268
{name} eg Poker II, PLAYSTATION(R)3 Controller
{serial} eg 0000:00:00.0
{port} eg usb1, usb2, usb3, 1-1, 4-1.2.1
{interface} eg 00:00:00:00 00:00:00 00:00:00
{hash} eg ihYz60+8pxZBi/cm+Q/4Ibrsyyzq/iZ9xtMDAh53sng
{parent_hash} eg npSDT1xuEIOSLNt2RT2EbFrE8XRZoV29t1n7kg6GxXg
Requires:
python-gobject Python Bindings for GLib/GObject/GIO/GTK+
usbguard USB device authorization policy framework
author @cyrinux, @maximbaz
license BSD
"},{"location":"user-guide/modules/#vnstat","title":"vnstat","text":"Display vnstat statistics.
Configuration parameters:
cache_timeout refresh interval for this module (default 180)
format display format for this module (default '{total}')
initial_multi set to 1 to disable first bytes (default 1024)
left_align (default 0)
multiplier_top if value is greater, divide it with unit_multi and get next unit from units (default 1024)
precision (default 1)
statistics_type d for daily, m for monthly (default 'd')
thresholds thresholds to use for color changes (default [])
unit_multi value to divide if rate is greater than multiplier_top (default 1024)
Format placeholders:
{down} download
{total} total
{up} upload
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
vnstat a console-based network traffic monitorExamples:
# colorize thresholds\nvnstat {\n format = '[\\?color=total {total}]'\n thresholds = [\n (838860800, \"degraded\"), # 838860800 B -> 800 MiB\n (943718400, \"bad\"), # 943718400 B -> 900 MiB\n ]\n}\nauthor shadowprince
license Eclipse Public License
"},{"location":"user-guide/modules/#volume_status","title":"volume_status","text":"Volume control.
Configuration parameters:
blocks a string, where each character represents a volume level (default \"_\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588\")
button_down button to decrease volume (default 5)
button_mute button to toggle mute (default 1)
button_up button to increase volume (default 4)
cache_timeout how often we refresh this module in seconds. (default 10)
card Card to use. amixer supports this. (default None)
channel channel to track. Default value is backend dependent. (default None)
command Choose between \"amixer\", \"pamixer\" or \"pactl\". If None, try to guess based on available commands. (default None)
device Device to use. Defaults value is backend dependent. \"aplay -L\", \"pactl list sinks short\", \"pamixer --list-sinks\" (default None)
format Format of the output. (default '[\\?if=is_input \ud83d\ude2e|\u266a]: {percentage}%')
format_muted Format of the output when the volume is muted. (default '[\\?if=is_input \ud83d\ude36|\u266a]: muted')
is_input Is this an input device or an output device? (default False)
max_volume Allow the volume to be increased past 100% if available. pactl and pamixer supports this. (default 120)
thresholds Threshold for percent volume. (default [(0, 'bad'), (20, 'degraded'), (50, 'good')])
volume_delta Percentage amount that the volume is increased or decreased by when volume buttons pressed. (default 5)
Format placeholders:
{icon} Character representing the volume level, as defined by the 'blocks'
{percentage} Percentage volume
Color options:
color_muted Volume is muted, if not supplied color_bad is used if set to None then the threshold color will be used.Requires:
alsa-utils an alternative implementation of linux sound support
pamixer pulseaudio command-line mixer like amixer
Notes: If you are changing volume state by external scripts etc and want to refresh the module quicker than the i3status interval, send a USR1 signal to py3status in the keybinding. Example: killall -s USR1 py3status
Examples:
# Set thresholds to rainbow colors\nvolume_status {\n thresholds = [\n (0, \"#FF0000\"),\n (10, \"#E2571E\"),\n (20, \"#FF7F00\"),\n (30, \"#FFFF00\"),\n (40, \"#00FF00\"),\n (50, \"#96BF33\"),\n (60, \"#0000FF\"),\n (70, \"#4B0082\"),\n (80, \"#8B00FF\"),\n (90, \"#FFFFFF\")\n ]\n}\nauthor <Jan T> <jans.tuomi@gmail.com>
license BSD
"},{"location":"user-guide/modules/#vpn_status","title":"vpn_status","text":"Drop-in replacement for i3status run_watch VPN module.
Expands on the i3status module by displaying the name of the connected vpn using pydbus. Asynchronously updates on dbus signals unless check_pid is True.
Configuration parameters:
cache_timeout How often to refresh in seconds when check_pid is True. (default 10)
check_pid If True, act just like the default i3status module. (default False)
format Format of the output. (default 'VPN: {format_vpn}|VPN: no')
format_vpn display format for vpns (default '{name}')
format_vpn_separator show separator if more than one VPN (default ', ')
pidfile Same as i3status pidfile, checked when check_pid is True. (default '/sys/class/net/vpn0/dev_id')
Format placeholders:
{format_vpn} format for VPNsFormat VPN placeholders:
{name} The name and/or status of the VPN.
{ipv4} The IPv4 address of the VPN
{ipv6} The IPv6 address of the VPN
Color options:
color_bad VPN connected
color_good VPN down
Requires:
dbus-python to interact with dbus
pygobject which in turn requires libcairo2-dev, libgirepository1.0-dev
author Nathan Smith <nathan AT praisetopia.org>
"},{"location":"user-guide/modules/#wanda_the_fish","title":"wanda_the_fish","text":"Display a fortune-telling, swimming fish.
Wanda has no use what-so-ever. It only takes up disk space and compilation time, and if loaded, it also takes up precious bar space, memory, and cpu cycles. Anybody found using it should be promptly sent for a psychiatric evaluation.
Configuration parameters:
cache_timeout refresh interval for this module (default 0)
format display format for this module (default '{nomotion}[{fortune} ]{wanda}{motion}')
fortune_timeout refresh interval for fortune (default 60)
Format placeholders:
{fortune} one of many aphorisms or vague prophecies
{wanda} name of one of the most commonly kept freshwater aquarium fish
{motion} biologically propelled motion through a liquid medium
{nomotion} opposite behavior of motion to prevent modules from shifting
Optional:
fortune-mod the fortune cookie program from bsd gamesExamples:
# disable motions when not in use\nwanda_the_fish {\n format = '[\\?if=fortune {nomotion}][{fortune} ]'\n format += '{wanda}[\\?if=fortune {motion}]'\n}\n\n# no updates, no motions, yes fortunes, you click\nwanda_the_fish {\n format = '[{fortune} ]{wanda}'\n cache_timeout = -1\n}\n\n# wanda moves, fortunes stays\nwanda_the_fish {\n format = '[{fortune} ]{nomotion}{wanda}{motion}'\n}\n\n# wanda is swimming too fast, slow down wanda\nwanda_the_fish {\n cache_timeout = 2\n}\nauthor lasers
"},{"location":"user-guide/modules/#watson","title":"watson","text":"Display the current status of the watson time-tracking tool.
Configuration parameters:
cache_timeout Number of seconds before state is re-read (default 10)
format The format for module output. (default 'Project {project}{tag_str} started')
state_file Path to the file which watson uses to track its own state (default '~/.config/watson/state')
Format placeholders:
{project} Name of the active project
{tag_str} String-representation of the list of active tags
Requires:
https://github.com/TailorDev/Watson commandline time tracking toolauthor Markus Sommer (https://github.com/CryptoCopter)
license BSD
"},{"location":"user-guide/modules/#weather_owm","title":"weather_owm","text":"Display ultimately customizable weather.
This module allows you to specify an icon for nearly every weather scenario imaginable. The default configuration options lump many of the icons into a few groups, and due to the limitations of UTF-8, this is really as expressive as it gets.
This module uses OpenWeatherMap API (https://openweathermap.org).
Requires a 3.0 API key for OpenWeatherMap (OWM) with a subscription which this module will try as hard as it can to stay under the free tier limit.
Setting location or city allows you to specify the location for the weather you want displaying.
I would highly suggest you install an additional font, such as the incredible (and free!) Weather Icons font (https://erikflowers.github.io/weather-icons), which has icons for most weather scenarios. But, this will still work with the i3bar default font, Deja Vu Sans Mono font, which has Unicode support. You can see the (limited) weather icon support within Unicode in the defaults.
For more information, see the documentation (https://openweathermap.org/weather-conditions) on what weather conditions are supported. See the configuration options for how to specify each weather icon.
Configuration parameters:
api_key Your OpenWeatherMap API key See https://openweathermap.org/appid. Required! (default None)
cache_timeout The time between API polling in seconds It is recommended to keep this at a higher value to avoid rate limiting with the API's. (default 1800)
city The city to display for location information. If set, implicitly disables the Geo API for determining city name. (default None)
country The country to display for location information. If set, implicitly disables the Geo API for determining country name. (default None)
forecast_days Number of days to include in the forecast, including today (regardless of the 'forecast_include_today' flag) (default 3)
forecast_include_today Include today in the forecast? (Boolean) (default False)
format How to display the weather This also dictates the type of forecast. The placeholders here refer to the format_[...] variables found below. Available placeholders: icon, city, clouds, rain, snow, wind, humidity, pressure, temperature, sunrise, sunset, main, description, forecast (default '{city} {icon} {temperature}[ {rain}], {description} {forecast}')
format_clouds Formatting for cloud coverage (percentage) Available placeholders: icon, coverage (default '{icon} {coverage}%')
format_forecast Formatting for future forecasts Available placeholders: See 'format' This is similar to the 'format' field, but contains information for future weather. Notably, this does not include information about sunrise or sunset times. (default '{icon}')
format_forecast_separator Separator between entries in the forecast (default ' ')
format_humidity Formatting for humidity (percentage) Available placeholders: icon, humidity (default '{icon} {humidity}%')
format_pressure Formatting for atmospheric pressure Available placeholders: icon, pressure, sea_level (default '{icon} {pressure} hPa')
format_rain Formatting for rain volume over the past 3 hours Available placeholders: icon, amount (default '[\\?if=amount {icon} {amount:.0f} {unit}]')
format_snow Formatting for snow volume over the past 3 hours Available placeholders: icon, amount (default '[\\?if=amount {icon} {amount:.0f} {unit}]')
format_sunrise Formatting for sunrise time Note that this format accepts strftime/strptime placeholders to populate the output with the time information. Available placeholders: icon (default '{icon} %-I:%M %p')
format_sunset Formatting for sunset time This format accepts strftime/strptime placeholders to populate the output with the time information. Available placeholders: icon (default '{icon} %-I:%M %p')
format_temperature Formatting for temperature Available placeholders: current, icon, max, min (default '{icon} [\\?color=all {current:.0f}\u00b0{unit}]')
format_wind Formatting for wind degree and speed The 'gust' option represents the speed of wind gusts in the wind unit. Available placeholders: icon, degree, speed, gust, direction (default '[\\?if=speed {icon} {speed:.0f} {unit}]')
icon_atmosphere Icon for atmospheric conditions, like fog, smog, etc. (default '\ud83c\udf2b')
icon_cloud Icon for clouds (default '\u2601')
icon_extreme Icon for extreme weather (default '\u26a0')
icon_humidity Icon for humidity (default '\u25cf')
icon_pressure Icon for pressure (default '\u25cc')
icon_rain Icon for rain (default '\ud83c\udf27')
icon_snow Icon for snow (default '\u2744')
icon_sun Icon for sunshine (default '\u263c')
icon_sunrise Icon for sunrise (default '\u21d1')
icon_sunset Icon for sunset (default '\u21d3')
icon_temperature Icon for temperature (default '\u25cb')
icon_thunderstorm Icon for thunderstorms (default '\u26c8')
icon_wind Icon for wind or breeze (default '\u2634')
icons A dictionary relating weather code to icon See https://openweathermap.org/weather-conditions for a complete list of supported icons. This will fall-back to the listed icon if there is no specific icon present. However, options included here take precedent over the above 'icon_{...}' options. There are multiple ways to specify individual icons based on the id:
lang An ISO 639-1 code for your language (two letters) (default 'en')
location A tuple of floats describing the desired weather location The tuple should follow the form (latitude, longitude), and if set, implicitly disables the Geo API for determining location. (default None)
thresholds Configure temperature colors based on limits The numbers specified inherit the unit of the temperature as configured. The default below is intended for Fahrenheit. If the set value is empty or None, the feature is disabled. You can specify this parameter using a dictionary:
unit_rain Unit for rain fall When specified, a unit may be any combination of upper and lower case, such as 'Ft', and still be considered valid as long as it is in the below options. Options: mm, cm, in (default 'in')
unit_snow Unit for snow fall Options: mm, cm, in (default 'in')
unit_temperature Unit for temperature Options: c, f, k (default 'F')
unit_wind Unit for wind speed Options: fsec, msec, mph, kmh, knot (default 'mph')
Format placeholders:
{icon} The icon associated with a formatting section
format_clouds
{coverage} Cloud coverage percentage
format_humidity
{humidity} Humidity percentage
format_pressure
{pressure} Current atmospheric pressure in Pascals
{sea_level} Sea-level atmospheric pressure in Pascals.
format_rain
{amount} Rainfall in the specified unit
{unit} The unit specified
format_snow
{amount} Snowfall in the specified unit
{unit} The unit specified
format_temperature
{current} Current temperature
{max} Maximum temperature in the configured unit
{min} Minimum temperature
{unit} The unit specified
format_wind
{degree} Current wind heading
{direction} Letter reprents direction e.g. N,NE,E etc
{gust} Wind gusts speed in the specified unit
{speed} Wind speed
{unit} The unit specified format only:
{city} The name of the city where the weather is
{country} The name of the country where the weather is
{forecast} Output of format_forecast format, format_forecast:
{clouds} Output of format_clouds
{description} Natural description of the current weather
{humidity} Output of format_humidity
{main} Short description of the current weather
{pressure} Output of format_pressure
{snow} Output of format_snow
{sunrise} Output of format_sunrise
{sunset} Output of format_sunset
{temperature} Output of format_temperature
{wind} Output of format_wind
Examples:
# change icons\nweather_owm {\n api_key = <my api key>\n icons = {\n '200': \"\u2614\"\n '230_232': \"\ud83c\udf27\"\n }\n}\n\n# set a city\nweather_owm {\n api_key = <my api key>\n city = 'London'\n}\n\n# set a location\nweather_owm {\n api_key = <my api key>\n location = (48.9342, 2.3548) # Saint-Denis\n}\nauthor alexoneill
@licence MIT
"},{"location":"user-guide/modules/#whatismyip","title":"whatismyip","text":"Display public IP address and online status.
Configuration parameters:
button_refresh mouse button to refresh this module (default 2)
button_toggle mouse button to toggle between states (default 1)
cache_timeout how often we refresh this module in seconds (default 60)
expected define expected values for format placeholders, and use color_degraded to show the output of this module if any of them does not match the actual value. This should be a dict eg {'country': 'France'} (default None)
format available placeholders are {ip} and {country}, as well as any other key in JSON fetched from url_geo (default '{ip}')
hide_when_offline hide the module output when offline (default False)
icon_off what to display when offline (default '\u25a0')
icon_on what to display when online (default '\u25cf')
mode default mode to display is 'ip' or 'status' (click to toggle) (default 'ip')
url_geo IP to check for geo location (must output json) (default 'https://ifconfig.co/json')
Format placeholders:
{icon} eg \u25cf, \u25a0
{country} eg France
{country_iso} eg FR
{ip} eg 123.45.67.890
{ip_decimal} eg 1234567890
{city} eg Paris any other key in JSON fetched from url_geo
Color options:
color_bad Offline
color_degraded Output is unexpected (IP/country mismatch, etc.)
color_good Online
Examples:
# ip choices\nwhatismyip {\n url_geo = \"https://ifconfig.co/json\"\n # url_geo = \"https://api.ip2location.io\"\n # url_geo = \"https://ipinfo.io/json\"\n # url_geo = \"http://ip-api.com/json\"\n}\nauthor ultrabug, Cyril Levis (@cyrinux)
"},{"location":"user-guide/modules/#whoami","title":"whoami","text":"Display logged-in username.
Configuration parameters:
format display format for this module (default '{username}')Format placeholders:
{hostname} display current hostname
{username} display current username
Inspired by i3 FAQ: https://faq.i3wm.org/question/1618/add-user-name-to-status-bar.1.html
author ultrabug
"},{"location":"user-guide/modules/#wifi","title":"wifi","text":"Display WiFi bit rate, quality, signal and SSID using iw.
Configuration parameters:
bitrate_bad Bad bit rate in Mbit/s (default 26)
bitrate_degraded Degraded bit rate in Mbit/s (default 53)
blocks a string, where each character represents quality level (default \"_\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588\")
cache_timeout Update interval in seconds (default 10)
device specify name or MAC address of device to use, otherwise auto (default None)
down_color Output color when disconnected, possible values: \"good\", \"degraded\", \"bad\" (default \"bad\")
format Display format for this module (default 'W: {bitrate} {bitrate_unit} {signal_percent}% {ssid}|W: down')
signal_bad Bad signal strength in percent (default 29)
signal_degraded Degraded signal strength in percent (default 49)
thresholds specify color thresholds to use (default [])
Format placeholders:
{bitrate} Display bitrate
{bitrate_unit} Display bitrate unit
{device} Display device name
{freq_ghz} Network frequency in Ghz
{freq_mhz} Network frequency in Mhz
{icon} Character representing the quality based on bitrate, as defined by the 'blocks'
{ip} Display IP address
{signal_dbm} Display signal in dBm
{signal_percent} Display signal in percent
{ssid} Display SSID
Color options:
color_bad Signal strength signal_bad or lower
color_degraded Signal strength signal_degraded or lower
color_good Signal strength above signal_degraded
Color thresholds:
xxx print a color based on the value of xxx placeholderRequires:
iw cli configuration utility for wireless devices
ip only for {ip}. may be part of iproute2: ip routing utilities
Notes: Some distributions require commands to be run with privileges. You can give commands some root rights to run without a password by editing sudoers file, i.e., sudo visudo, and add a line that requires sudo. '<user> ALL=(ALL) NOPASSWD:/sbin/iw dev,/sbin/iw dev [a-z] link' '<user> ALL=(ALL) NOPASSWD:/sbin/ip addr list [a-z]'
author Markus Weimar <mail@markusweimar.de>
license BSD
"},{"location":"user-guide/modules/#window","title":"window","text":"Display window properties (i.e. title, class, instance).
Configuration parameters:
cache_timeout refresh interval for i3-msg or swaymsg (default 0.5)
format display format for this module (default \"{title}\")
hide_title hide title on containers with window title (default False)
max_width specify width to truncate title with ellipsis (default None)
Format placeholders:
{class} window class
{instance} window instance
{title} window title
Requires:
i3ipc an improved python library to control i3wm and swayExamples:
# show alternative instead of empty title\nwindow_title {\n format = '{title}|\u2665'\n}\nauthor shadowprince (counter), Anon1234 (async)
license Eclipse Public License (counter), BSD (async)
"},{"location":"user-guide/modules/#wwan","title":"wwan","text":"Display WWANs, IP addresses, signals, properties and sms.
Configuration parameters:
cache_timeout refresh interval for this module (default 5)
format display format for this module (default '\\?color=state WW: [\\?if=state_name=connected ' '({signal_quality_0}% at {m3gpp_operator_name}) ' '[{format_ipv4}[\\?soft ]{format_ipv6}]|{state_name}]' '[ SMS {messages} [{format_message}]]')
format_ipv4 display format for ipv4 network (default '[{address}]')
format_ipv6 display format for ipv6 network (default '[{address}]')
format_message display format for SMS messages (default '\\?if=index<2 {number} [\\?max_length=10 {text}...]')
format_message_separator show separator if more than one (default ' ')
format_notification specify notification to use (default None)
format_stats display format for statistics (default '{duration_hms}')
modem specify a modem device to use, otherwise auto (default None)
thresholds specify color thresholds to use (default [(0, 'bad'), (11, 'good')])
Format placeholders:
{access_technologies} network speed, in bit, eg 192
{access_technologies_name} network speed names, eg LTE
{current_bands} modem band, eg 1
{current_bands_name} modem band name, eg GSM/GPRS/EDGE 900 MHz
{format_ipv4} format for ipv4 network config
{format_ipv6} format for ipv6 network config
{format_message} format for SMS messages
{format_stats} format for network connection statistics
{interface_name} network interface name, eg wwp0s20f0u2i12
{m3gpp_registration_state_name} network registration state name, eg HOME
{m3gpp_registration_state} network registration state, eg 1
{m3gpp_operator_code} network operator code, eg 496
{m3gpp_operator_name} network operator name, eg Py3status Telecom
{message} number of messages, eg 2
{messages} total number of messages, eg 30
{signal_quality_0} signal quality percentage, eg 88
{signal_quality_1} signal quality refreshed, eg True/False
{state} network state, eg 0, 7, 11
{state_name} network state name, eg searching, connected
format_ipv4 placeholders:
{address} ip address
{dns1} dns1
{dns2} dns2
{gateway} gateway
{mtu} mtu
{prefix} netmask prefix
format_ipv6 placeholders:
{address} ip address
{dns1} dns1
{dns2} dns2
{gateway} gateway
{mtu} mtu
{prefix} netmask prefix
format_message placeholders:
{index} message index
{text} text received, eg: 'hello how are you?'
{number} contact number, eg: '+33601020304'
format_stats placeholders:
{duration} time since connected, in seconds, eg 171
{duration_hms} time since connected, in [hh:]mm:ss, eg 02:51
{tx_bytes} transmit bytes
{rx_bytes} receive bytes
Color thresholds:
format xxx: print a color based on the value of xxx placeholderRequires:
modemmanager mobile broadband modem management service
networkmanager network connection manager and user applications
dbus-python Python bindings for dbus
Examples:
# show state names, eg initializing, searching, registered, connecting.\nwwan {\n format = '\\?color=state WWAN: {state_name}'\n}\n\n# show state names, and when connected, show network information too.\nwwan {\n format = 'WWAN:[\\?color=state [ {format_ipv4}]'\n format += '[ {format_ipv6}] {state_name}]'\n}\n\n# show internet access technologies name with up/down state.\nwwan {\n format = 'WWAN: [\\?color=state [{access_technologies_name}]'\n format += '[\\?soft ][\\?if=state_name=connected up|down]]'\n}\n\n# show SMS messages only\nwwan {\n format = '[SMS: {format_message}]'\n}\n\n# SMS counter\nwwan {\n format = 'SMS: {message}/{messages}'\n}\n\n\n# add starter pack thresholds. you do not need to add them all.\nwwan {\n thresholds = {\n 'access_technologies': [\n (2, 'bad'), (32, 'orange'), (512, 'degraded'), (16384, 'good')\n ],\n 'signal_quality_0': [\n (0, 'bad'), (10, 'orange'), (30, 'degraded'), (50, 'good')\n ],\n 'signal_quality_1': [\n (False, 'darkgrey'), (True, 'degraded')\n ],\n 'state': [\n (-1, 'bad'), (4, 'orange'), (5, 'degraded'), (11, 'good')\n ]\n }\n}\n\n# customize WWAN format\nwwan {\n format = 'WWAN: [\\?color=state {state_name}] '\n format += '[\\?if=m3gpp_registration_state_name=HOME {m3gpp_operator_name} ] '\n format += '[\\?if=m3gpp_registration_state_name=ROAMING {m3gpp_operator_name} ]'\n format += '[\\?color=access_technologies {access_technologies_name} ]'\n format += '[([\\?color=signal_quality_0 {signal_quality_0}]]'\n format += '[\\?if=!signal_quality_1&color=signal_quality_1 \\[!\\]|] '\n format += '[\\?if=state_name=connected [{format_ipv4}] [{format_stats}]]')\n}\n\n# notify users when an event occur... such as new messages, change in state,\n# disconnected, etc. you need to specify formatting correctly so it does not\n# return anything. otherwise, you always get notifications.\nwwan {\n # notify users on low signal percent 25%\n format_notification = '\\?if=signal_quality_0<25 Low signal'\n\n # notify users on connected state\n format_notification = '[\\?if=state_name=connected Connected.]'\n format_notification += '[\\?if=state_name=disconnected Disconnected.]'\n\n # message notification\n format_message = '[\\?if=index=1 [{number}] [{text}]]'\n format_notification = '[\\?if=message>0 {format_message}]'\n}\nauthor Cyril Levis (@cyrinux), girst (https://gir.st/)
"},{"location":"user-guide/modules/#wwan_status","title":"wwan_status","text":"Display network and IP address for newer Huwei modems.
It is tested for Huawei E3276 (usb-id 12d1:1506) aka Telekom Speed Stick LTE III but may work on other devices too.
Configuration parameters:
baudrate There should be no need to configure this, but feel free to experiment. (default 115200)
cache_timeout How often we refresh this module in seconds. (default 5)
consider_3G_degraded If set to True, only 4G-networks will be considered 'good'; 3G connections are shown as 'degraded', which is yellow by default. Mostly useful if you want to keep track of where there is a 4G connection. (default False)
format_down What to display when the modem is not plugged in (default 'WWAN: down')
format_error What to display when modem can't be accessed. (default 'WWAN: {error}')
format_no_service What to display when the modem does not have a network connection. This allows to omit the (then meaningless) network generation. (default 'WWAN: {status} {ip}')
format_up What to display upon regular connection (default 'WWAN: {status} ({netgen}) {ip}')
interface The default interface to obtain the IP address from. For wvdial this is most likely ppp0. For netctl it can be different. (default 'ppp0')
modem The device to send commands to. (default '/dev/ttyUSB1')
modem_timeout The timespan between querying the modem and collecting the response. (default 0.4)
Color options:
color_bad Error or no connection
color_degraded Low generation connection eg 2G
color_good Good connection
Requires:
netifaces portable module to access network interface information
pyserial multiplatform serial port module for python
author Timo Kohorst timo@kohorst-online.com
PGP: B383 6AE6 6B46 5C45 E594 96AB 89D2 209D DBF3 2BB5
"},{"location":"user-guide/modules/#xkb_input","title":"xkb_input","text":"Switch inputs.
Configuration parameters:
button_next mouse button to cycle next layout (default 4)
button_prev mouse button to cycle previous layout (default 5)
cache_timeout refresh interval for this module; xkb-switch and swaymsg will listen for new updates instead (default 10)
format display format for this module (default '{format_input}')
format_input display format for inputs (default '[{alias}][\\?soft ][\\?color=s {s}[ {v}]]')
format_input_separator show separator if more than one (default ' ')
inputs specify a list of inputs to use in swaymsg (default [])
switcher specify xkb-switch, xkblayout-state, xkbgroup, or swaymsg to use, otherwise auto (default None)
thresholds specify color thresholds to use (default [(\"fr\", \"lightgreen\"), (\"ru\", \"lightcoral\"), (\"ua\", \"khaki\"), (\"us\", \"lightskyblue\")])
Format placeholders:
{format_input} format for inputs
{input} number of inputs, eg 1
{switcher} eg, xkb-switch, xkblayout-state, xkbgroup, swaymsg
format_input placeholders:
xkb-switch
xkblayout-state
xkbgroup
swaymsg
{c} layout number, eg, 0
{n} layout name, eg, English (US)
{s} layout symbol, eg, us
{v} layout variant, eg, basic
{e} layout variant, {v} or {s}, eg, dvorak
{C} layout count, eg, 2
swaymsg
{alias} custom string or {name}
{identifier} eg, 162:253 USB-HID Keyboard
{name} eg, Trackball, Keyboard, etc
{vendor} eg, 320
{product} eg, 556
{type} eg, pointer, keyboard, touchpad, etc
{xkb_layout_names} eg, English (US), French, Russian
{xkb_active_layout_index} eg, 0, 1, 2, etc
{xkb_active_layout_name} eg, English (US)
{send_events} eg, True
{accel_speed} eg, 0.0
{accel_profile} eg, adaptive
{natural_scroll} eg, adaptive
{left_handed} eg, False
{middle_emulation} eg, False
{scroll_method} eg, None
{scroll_button} eg, 274
Use `swaymsg -r -t get_inputs` to get a list of current sway inputs\nand for a list of placeholders. Not all of placeholders will be usable.\nColor thresholds:
xxx print a color based on the value of xxx placeholderRequires:
xkb-switch program that allows to query and change the xkb layout state
xkblayout-state a command-line program to get/set the current keyboard layout
xkbgroup query and change xkb layout state
swaymsg send messages to sway window manager
Examples:
# sway users: for best results, add switcher to avoid false positives with `pgrep i3`\n# because sway users can be using scripts, tools, et cetera with `i3` in its name.\nxkb_input {\n switcher = \"swaymsg\"\n}\n\n# sway users: specify inputs to fnmatch\nxkb_input {\n # display logitech identifiers\n inputs = [{\"identifier\": \"*Logitech*\"}]\n\n # display logi* keyboards only\n inputs = [{\"name\": \"Logi*\", \"type\": \"keyb*\"}]\n\n # display pointers only\n inputs = [{\"type\": \"pointer\"}]\n}\n\n# sway users: display inputs, optional aliases, et cetera\nxkb_input {\n inputs = [\n {\"identifier\": \"1625:3192:Heng_Yu_Technology_Poker_II\", \"alias\": \"Poker 2\"},\n {\"identifier\": \"0012:021:USB-HID_Keyboard\", \"alias\": \"Race 3\"},\n {\"identifier\": \"0123:45678:Logitech_MX_Ergo\", \"alias\": \"MX Ergo\", \"type\": \"pointer\"},\n ]\n}\n\n# i3 users: display inputs - see https://wiki.archlinux.org/index.php/X_keyboard_extension\n# $ setxkbmap -layout \"us,fr,ru\" # install xkb-group to enable a listener thread\nauthor lasers, saengowp, javiertury
"},{"location":"user-guide/modules/#xrandr","title":"xrandr","text":"Control screen layout.
This modules allows you to handle your screens outputs directly from your bar! - Detect and propose every possible screen combinations - Switch between combinations using click events and mouse scroll - Activate the screen or screen combination on a single click - It will detect any newly connected or removed screen automatically
For convenience, this module also proposes some added features: - Dynamic parameters for POSITION and WORKSPACES assignment (see below) - Automatic fallback to a given screen or screen combination when no more screen is available (handy for laptops) - Automatically apply this screen combination on start: no need for xorg! - Automatically move workspaces to screens when they are available - Define your own subset of output combinations to use
Configuration parameters:
cache_timeout how often to (re)detect the outputs (default 10)
command a custom command to be run after display configuration changes (default None)
fallback when the current output layout is not available anymore, fallback to this layout if available. This is very handy if you have a laptop and switched to an external screen for presentation and want to automatically fallback to your laptop screen when you disconnect the external screen. (default True)
fixed_width show output as fixed width (default True)
force_on_change switch display layout to the leftmost combination mode of the given list whenever it is available. The combination modes are checked from left (high priority) to right (less priority) until one matches. Example: We have a laptop with internal screen and we are often moving from our desk where another screen is available. We want the layout to follow our changes so that we do not have to switch manually. So whenever we plug at our desk, we want the second monitor to be used, and whenever we go away we want everything back on the laptop screen automatically: force_on_change = [\"eDP1+DP1\", \"eDP1\"] NOTES: Click controls will override force_on_change until the layout changes in the background so you can still manually control your layout changes on the bar. Use the force_on_start to handle initial layout setup on module startup along with this feature to benefit from fully dynamic and automated changes of screen layouts. (default [])
force_on_start switch to the given combination mode if available when the module starts (saves you from having to configure xorg) (default None)
format display format for xrandr (default '{output}')
hide_if_single_combination hide if only one combination is available (default False)
icon_clone icon used to display a 'clone' combination (default '=')
icon_extend icon used to display a 'extend' combination (default '+')
on_udev_drm dynamic variable to watch for drm udev subsystem events to trigger specified action. (default 'refresh_and_freeze')
output_combinations string used to define your own subset of output combinations to use, instead of generating every possible combination automatically. Provide the values in the format that this module uses, splitting the combinations using '|' character. The combinations will be rotated in the exact order as you listed them. When an output layout is not available any more, the configurations are automatically filtered out. Example: Assuming the default values for icon_clone and icon_extend are used, and assuming you have two screens 'eDP1' and 'DP1', the following setup will reduce the number of output combinations from four (every possible one) down to two. output_combinations = \"eDP1|eDP1+DP1\" (default None)
Dynamic configuration parameters:
<OUTPUT>_icon use this icon instead of OUTPUT name as text Example: DP1_icon = \"\ud83d\uddb5\"
<OUTPUT>_pos apply the given position to the OUTPUT Example: DP1_pos = \"-2560x0\" Example: DP1_pos = \"above eDP1\" Example: DP1_pos = \"below eDP1\" Example: DP1_pos = \"left-of LVDS1\" Example: DP1_pos = \"right-of eDP1\"
<OUTPUT>_workspaces comma separated list of workspaces to move to the given OUTPUT when it is activated Example: DP1_workspaces = \"1,2,3\"
<OUTPUT>_rotate rotate the output as told Example: DP1_rotate = \"left\"
<OUTPUT>_mode define the mode (resolution) for the output if not specified use --auto : preferred mode Example: eDP1_mode = \"2560x1440\"
<OUTPUT>_primary apply the primary to the OUTPUT Example: DP1_primary = True
Format placeholders:
{output} xrandr outputColor options:
color_bad Displayed layout unavailable
color_degraded Using a fallback layout
color_good Displayed layout active
Notes: Some days are just bad days. Running xrandr --query command can cause unexplainable brief screen freezes due to an overall combination of computer hardware, installed software, your choice of linux distribution, and/or some other unknown factors such as recent system updates.
Configuring `cache_timeout` with a different number, eg `3600` (an hour)\nor `-1` (runs once) can be used to remedy this issue. See issue #580.\nExamples:
# start with a preferable setup\nxrandr {\n force_on_start = \"eDP1+DP1\"\n DP1_pos = \"left-of eDP1\"\n VGA_workspaces = \"7\"\n}\nauthor ultrabug
"},{"location":"user-guide/modules/#xrandr_rotate","title":"xrandr_rotate","text":"Control screen rotation.
Configuration parameters:
cache_timeout how often to refresh this module. (default 10)
format a string that formats the output, can include placeholders. (default '{icon}')
hide_if_disconnected a boolean flag to hide icon when screen is disconnected. It has no effect unless screen option is also configured. (default False)
horizontal_icon a character to represent horizontal rotation. (default 'H')
horizontal_rotation a horizontal rotation for xrandr to use. Available options: 'normal' or 'inverted'. (default 'normal')
screen display output name to rotate, as detected by xrandr. If not provided, all enabled screens will be rotated. (default None)
vertical_icon a character to represent vertical rotation. (default 'V')
vertical_rotation a vertical rotation for xrandr to use. Available options: 'left' or 'right'. (default 'left')
Format placeholders:
{icon} a rotation icon, specified by horizontal_icon or vertical_icon.
{screen} a screen name, specified by screen option or detected automatically if only one screen is connected, otherwise 'ALL'.
Color options:
color_degraded Screen is disconnected
color_good Displayed rotation is active
author Maxim Baz (https://github.com/maximbaz)
license BSD
"},{"location":"user-guide/modules/#xscreensaver","title":"xscreensaver","text":"Control Xscreensaver.
This script is useful for people who let Xscreensaver manage DPMS settings. Xscreensaver has its own DPMS variables separate from xset. DPMS can be safely turned off in xset as long as Xscreensaver is running. Settings can be managed using \"xscreensaver-demo\".
Configuration parameters:
button_activate mouse button to activate Xscreensaver (default 3)
button_toggle mouse button to toggle Xscreensaver (default 1)
cache_timeout refresh interval for this module (default 15)
format display format for this module (default '{icon}')
icon_off show when Xscreensaver is not running (default 'XSCR')
icon_on show when Xscreensaver is running (default 'XSCR')
Format placeholders:
{icon} Xscreensaver iconColor options:
color_on Enabled, defaults to color_good
color_off Disabled, defaults to color_bad
author neutronst4r, lasers
"},{"location":"user-guide/modules/#xsel","title":"xsel","text":"Display X selection.
Configuration parameters:
cache_timeout refresh interval for this module (default 0.5)
command the clipboard command to run (default 'xsel --output')
format display format for this module (default '{selection}')
log_file specify the clipboard log to use (default None)
max_size strip the selection to this value (default 15)
symmetric show beginning and end of the selection string with respect to configured max_size. (default True)
Format placeholders:
{selection} output from clipboard commandRequires:
xsel a command-line program to retrieve/set the X selectionExamples:
xsel {\n max_size = 50\n command = \"xsel --clipboard --output\"\n on_click 1 = \"exec xsel --clear --clipboard\"\n log_file = \"~/.local/share/xsel/clipboard_log\"\n}\nauthor Sublim3 umbsublime@gamil.com
license BSD
"},{"location":"user-guide/modules/#yandexdisk_status","title":"yandexdisk_status","text":"Display Yandex.Disk status.
Configuration parameters:
cache_timeout refresh interval for this module (default 10)
format display format for this module (default 'Yandex.Disk: {status}')
status_busy show when Yandex.Disk is busy (default None)
status_off show when Yandex.Disk isn't running (default 'Not started')
status_on show when Yandex.Disk is idling (default 'Idle')
Format placeholders:
{status} Yandex.Disk statusColor options:
color_bad Not started
color_degraded Idle
color_good Busy
Requires:
yandex-disk command line interface for Yandex.Diskauthor Vladimir Potapev (github:vpotapev)
license BSD
"},{"location":"user-guide/modules/#yubikey","title":"yubikey","text":"Show an indicator when YubiKey is waiting for a touch.
Configuration parameters:
format Display format for the module. (default '[YubiKey[\\?if=is_gpg ][\\?if=is_u2f ]]')
socket_path A path to the yubikey-touch-detector socket file. (default '$XDG_RUNTIME_DIR/yubikey-touch-detector.socket')
Control placeholders:
{is_gpg} a boolean, True if YubiKey is waiting for a touch due to a gpg operation.
{is_u2f} a boolean, True if YubiKey is waiting for a touch due to a pam-u2f request.
Requires:
github.com/maximbaz/yubikey-touch-detector tool to detect when YubiKey is waiting for a touchauthor Maxim Baz (https://github.com/maximbaz)
license BSD
"},{"location":"user-guide/modules/#zypper_updates","title":"zypper_updates","text":"Display number of pending updates for OpenSUSE Linux.
Configuration parameters:
cache_timeout How often we refresh this module in seconds (default 600)
format Display format to use (default 'zypper: [\\?color=update {update}]')
thresholds specify color thresholds to use (default [(0, 'good'), (50, 'degraded'), (100, 'bad')])
Format placeholders:
{updates} number of pending zypper updatesColor thresholds:
xxx print a color based on the value of xxx placeholderauthor Ioannis Bonatakis <ybonatakis@suse.com>
license BSD
"},{"location":"user-guide/remote-control/","title":"Controlling py3status remotely","text":"Just like i3status, you can force an update of your i3bar by sending a SIGUSR1 signal to py3status. Note that this will also send a SIGUSR1 signal to i3status.
$ killall -USR1 py3status\npy3status can be controlled remotely via the py3-cmd cli utility.
This utility allows you to run a number of commands.
# button numbers\n1 = left click\n2 = middle click\n3 = right click\n4 = scroll up\n5 = scroll down\nSend a click event to a module as though it had been clicked on. You can specify the button to simulate.
# send a left/middle/right click\n$ py3-cmd click --button 1 dpms # left\n$ py3-cmd click --button 2 sysdata # middle\n$ py3-cmd click --button 3 pomodoro # right\n\n# send a up/down click\n$ py3-cmd click --button 4 volume_status # up\n$ py3-cmd click --button 5 volume_status # down\n# toggle button in frame module\n$ py3-cmd click --button 1 --index button frame # left\n\n# change modules in group module\n$ py3-cmd click --button 5 --index button group # down\n\n# change time units in timer module\n$ py3-cmd click --button 4 --index hours timer # up\n$ py3-cmd click --button 4 --index minutes timer # up\n$ py3-cmd click --button 4 --index seconds timer # up\nPrint a list of modules or module docstrings.
# list one or more modules\n$ py3-cmd list clock loadavg xrandr # full\n$ py3-cmd list coin* git* window* # fnmatch\n$ py3-cmd list [a-e]* # abcde\n\n# list all modules\n$ py3-cmd list --all\n\n# show full (i.e. docstrings)\n$ py3-cmd list vnstat uname -f\nCause named module(s) to have their output refreshed.
# refresh all instances of the wifi module\n$ py3-cmd refresh wifi\n\n# refresh multiple modules\n$ py3-cmd refresh coin_market github weather_yahoo\n\n# refresh module with instance name\n$ py3-cmd refresh \"weather_yahoo chicago\"\n\n# refresh all modules\n$ py3-cmd refresh --all\npy3-cmd can be used in your i3 configuration file.
To send a click event to the whatismyip module when Mod+x is pressed
bindsym $mod+x exec py3-cmd click whatismyip\nThis example shows how volume control keys can be bound to change the volume and then cause the volume_status module to be updated.
bindsym XF86AudioRaiseVolume exec \"amixer -q sset Master 5%+ unmute; py3-cmd refresh volume_status\"\nbindsym XF86AudioLowerVolume exec \"amixer -q sset Master 5%- unmute; py3-cmd refresh volume_status\"\nbindsym XF86AudioMute exec \"amixer -q sset Master toggle; py3-cmd refresh volume_status\"\nHere you can find community contributed configuration examples to help you get started with some modules or benefit from the tricks of other hackers!
"},{"location":"user-guide/user-contributed-conf-examples/#ultrabugs-configuration-examples","title":"Ultrabug's configuration examples","text":"# one button for bluetooth on/off\nbluetooth {\n format = \"\uf519\"\n on_click 1 = \"exec bluetoothctl power on\"\n on_click 3 = \"exec bluetoothctl power off\"\n}\n\n# I use pulseausio and I like to control the sinks and sources \n# directly from my bar!\n#\n# These modules allow me to not only control the volume of the given\n# devices but to also switch the sound output from one to another\n\n# This is the speakers from my laptop, I can switch sound to it\n# on middle click\nvolume_status speakers {\n command = \"pactl\"\n device = \"alsa_output.pci-0000_00_1f.3.analog-stereo\"\n format = \"\ud83d\udcbb{percentage}%\"\n format_muted = \"\ud83d\udcbb{percentage}%\"\n on_click 2 = \"exec pactl set-default-sink alsa_output.pci-0000_00_1f.3.analog-stereo\"\n thresholds = [(0, 'bad'), (5, 'degraded'), (10, 'good')]\n}\n\n# I plugin a USB headset, it appears, I can switch default sound to\n# it while controlling its volume output. When disconnected, it\n# disappears from the bar\nvolume_status sennheiser {\n command = \"pactl\"\n device = \"alsa_output.usb-Sennheiser_\"\n format = \"[\\?if=!percentage=? \ud83c\udfa7{percentage}%]\"\n format_muted = '\ud83c\udfa7{percentage}%'\n on_click 2 = \"exec pactl set-default-sink alsa_output.usb-Sennheiser_Sennheiser_SC_160_USB_A002430203100377-00.analog-stereo\"\n thresholds = [(0, 'bad'), (5, 'degraded'), (10, 'good')]\n}\n\n# I also can activate a remote bluetooth speaker by clicking on this,\n# when it connects the sound percentage appears, I can switch output\n# to it by middle clicking or disconnect it by right clicking\nvolume_status bose {\n command = \"pactl\"\n device = \"bluez_sink..+.a2dp_sink\"\n format = \"[\\?if=!percentage=? \ud83d\udcfb{percentage}%][\\?if=percentage=? \ud83d\udcfb]\"\n format_muted = '\ud83d\udcfb{percentage}%'\n on_click 2 = \"exec pactl set-default-sink bluez_sink.2C_41_A1_Z7_FA_C2.a2dp_sink\"\n on_click 1 = \"exec bluetoothctl connect 2C:41:A1:Z7:FA:C2\"\n on_click 3 = \"exec bluetoothctl disconnect 2C:41:A1:Z7:FA:C2\"\n thresholds = [(0, 'bad'), (5, 'degraded'), (10, 'good')]\n max_volume = 200\n}\n\n# I also control the default microphone volume from the bar\n# and can mute it\nvolume_status mic {\n format = '\ud83c\udf99\ufe0f{percentage}%'\n format_muted = '\ud83c\udf99\ufe0f{percentage}%'\n button_down = 5\n button_mute = 1\n button_up = 4\n is_input = true\n thresholds = [(0, 'bad'), (10, 'degraded'), (20, 'good')]\n}\n\n# DMPS status shows as a red/green screen\ndpms {\n icon_off = \"\uf108\"\n icon_on = \"\uf108\"\n}\n\n# cycling time in meaningful cities\ngroup tz {\n cycle = 10\n format = \"{output}\"\n #click_mode = \"button\"\n\n tztime la {\n format = \"\ud83c\udf09%H:%M\"\n timezone = \"America/Los_Angeles\"\n }\n\n tztime ny {\n format = \"\ud83d\uddfd%H:%M\"\n timezone = \"America/New_York\"\n }\n\n tztime du {\n format = \"\ud83d\udd4c%H:%M\"\n timezone = \"Asia/Dubai\"\n }\n\n tztime tw {\n format = \"\u26e9\ufe0f%H:%M\"\n timezone = \"Asia/Taipei\"\n }\n\n tztime in {\n format = \"\ud83d\uded5%H:%M\"\n timezone = \"Asia/Kolkata\"\n }\n}\n# If I had time, I would make these proper modules. Free feel to make them\n# if you got time.\n\n# weather without needing an API key\ngetjson wttr {\n url = \"https://wttr.in/Paris?format=j1\"\n format = \"{current_condition-0-FeelsLikeC}\u00b0 {current_condition-0-weatherDesc-0-value}\"\n cache_timeout = 3600\n}\n\n# example output\n# 6\u00b0 Partly cloudy\n\n# SABnzbd status\ngetjson sabnzbd {\n url = \"https://sabnzbd.example.com/api?mode=queue&apikey=000000000&output=json\"\n format = \"SABnzbd: {queue-status}\"\n cache_timeout = 60\n}\n# example output\n# SABnzbd: Idle\nDisplay output of a given script.
Display output of any executable script set by script_path. Only the first
two lines of output will be used. The first line is used as the displayed
-text. If the output has two or more lines, the second line is set as the text
-color (and should hence be a valid hex color code such as #FF0000 for red).
-If the second line is urgent, or has ! prefixing the hex color, then the
-"urgent" flag will be set.
-The script should not have any parameters, but it could work.
#rrggbb: the text color as a hex color code (eg. #FF0000 for red)
+ urgent: the word urgent to set the urgent flag
+ The script should not have any parameters, but it could work.
Configuration parameters: