Config Files

mybar uses the Scuff language to process data from and write to config files, or JSON.

The default config file location is ~/.config/mybar/mybar.conf

Configuring mybar

Bar options

The following options are used to control how the bar runs:

• refresh

  (float) How often in seconds the bar automatically prints itself.

• separator

  (string) A string or list of strings (one for ASCII terminals, one for Unicode terminals) used to separate each Field.

• count

  (integer) Print the bar this many times before the program quits.

• template

  (string) A template string to use instead of field_order.

• break_lines

  (bool) Write each Bar on a new line every refresh cycle.

• unicode

  (bool) Use Unicode Field icons and separator, if given.

• field_order

  (list) A list of Fields to display if template is unset. For example:

  field_order [uptime cpu_usage cpu_temp net_stats datetime]
  

• field_icons

  (mapping) A mapping of Field names to icons or lists of icons (one for ASCII terminals, one for Unicode terminals) for each Field. For example:

  field_icons {
      uptime "Up "
      cpu_usage ["CPU ", "📈"]
      cpu_temp ["", "\uf06d "]
  }
  

• clock_align

  (bool) Print the bar at the top of each second.

• join_empty_fields

  (bool) Show separators around Fields, even when they are empty.

• thread_cooldown

  (float) How long a field thread loop sleeps after checking if the bar is still running. Between executions, unlike async fields, a threaded field sleeps for several iterations of thread_cooldown seconds that always add up to Field.interval seconds. Between sleeps, it checks if the bar has stopped. A shorter cooldown means more chances to check if the bar has stopped and a faster exit time.

• Field definitions

  Field definitions are mappings with Field options used to override defaults. See Field options for a complete reference. You may use the rest of the file to customize specific Fields in the field_order list. For example:

  datetime {
      interval 3
      template "{} o'clock"
  }
  
  cpu_usage {threaded no}
  

Note

See Programming with Fields for a description of default fields.

Field options

• icon

  (string) Positioned in front of Field contents or in place of {icon} in template, if provided

• template

  (string) A curly-brace format string. This parameter is required if icon is None.

  Valid placeholders:

  • {icon} references icon

  • {} references Field contents

  Example:

  When the Field’s current contents are '69F' and its icon is 'TEMP',

  template='[{icon}]: {}' shows as '[TEMP]: 69F'

• interval

  (float) How often in seconds Field contents are updated, defaults to 1.0

• clock_align

  (bool) Update contents at the start of each second, defaults to False

• timely

  (bool) Run the Field function as soon as possible after every refresh, defaults to False

• overrides_refresh

  (bool) Ensure updates to this Field re-print the Bar between refreshes, defaults to False

• threaded

  (bool) Run this Field in a separate thread, defaults to False

• always_show_icon

  (bool) Show icons even when contents are empty, defaults to False

• run_once

  (bool) Permanently set contents by running the func only once, defaults to False

• constant_output

  (string) Permanently set contents instead of running a function

• args

  (list) Positional args passed to func

• kwargs

  (mapping) Keyword args passed to func

• command

  (string) A shell command to run

• script

  (string) The path to a shell script to run

• allow_multiline

  (bool) Don’t join the output of a command or script if it spans multiple lines, defaults to False

• Custom Fields

  New positionable Fields with custom values are specified with the custom option. For example:

  my_custom_field {
      custom true
      constant_value "Hello!"
  }
  

Here is an example config file:

refresh 0.5
separator ["|", "∦"]
unicode yes

field_order [
    uptime
    my_custom_field
    cpu_usage
    cpu_temp
    mem_usage
    disk_usage
    battery
    net_stats
    datetime
]

field_icons {
    # Unicode codepoints in the second slot are for Fontawesome icons
    uptime ["Up ", "\uf2f2 "]
    cpu_usage ["CPU ", "\uf3fd "]
    cpu_temp ["", "\uf06d "]
    mem_usage ["MEM ", "\uf2db "]
    battery "BAT "
    net_stats ["", "\uf1eb "]
}

datetime {interval 0.1}

# Give the time function a different format:
datetime.kwargs.fmt '%H:%M:%S.%f'

my_custom_field {
    custom yes
    script "check-email.sh"
    interval 60
}