Configuration reference

Main configuration

Location:powerline/config.json

The main configuration file defines some common options that applies to all extensions, as well as some extension-specific options like themes and colorschemes.

Common configuration

Common configuration is a subdictionary that is a value of common key in powerline/config.json file.

term_truecolor
Defines whether to output cterm indices (8-bit) or RGB colors (24-bit) to the terminal emulator. See the Application/terminal emulator feature support matrix for information on whether your terminal emulator supports 24-bit colors.
ambiwidth
Tells powerline what to do with characters with East Asian Width Class Ambigious (such as Euro, Registered Sign, Copyright Sign, Greek letters, Cyrillic letters). Valid values: any positive integer; it is suggested that you only set it to 1 (default) or 2.
watcher

Select filesystem watcher. Variants are

Variant Description
auto Selects most performant watcher.
inotify Select inotify watcher. Linux only.
stat Select stat-based polling watcher.
uv Select libuv-based watcher.

Default is auto.

additional_escapes
Valid for shell extensions, makes sense only if term_truecolor is enabled. Is to be set from command-line (unless you are sure you always need it). Controls additional escaping that is needed for tmux/screen to work with terminal true color escape codes: normally tmux/screen prevent terminal emulator from receiving these control codes thus rendering powerline prompt colorless. Valid values: "tmux", "screen", null (default).
paths
Defines additional paths which will be searched for modules when using function segment option or Vim local_themes option. Paths defined here have priority when searching for modules.
log_file
Defines path which will hold powerline logs. If not present, logging will be done to stderr.
log_level
String, determines logging level. Defaults to WARNING.
log_format
String, determines format of the log messages. Defaults to '%(asctime)s:%(level)s:%(message)s'.
interval
Number, determines time (in seconds) between checks for changed configuration. Checks are done in a seprate thread. Use null to check for configuration changes on .render() call in main thread. Defaults to None.
reload_config
Boolean, determines whether configuration should be reloaded at all. Defaults to True.
default_top_theme
String, determines which top-level theme will be used as the default. Defaults to powerline in unicode locales and ascii in non-unicode locales. See Themes section for more details.

Extension-specific configuration

Common configuration is a subdictionary that is a value of ext key in powerline/config.json file.

colorscheme
Defines the colorscheme used for this extension.
theme
Defines the theme used for this extension.
top_theme
Defines the top-level theme used for this extension. See Themes section for more details.
local_themes

Defines themes used when certain conditions are met, e.g. for buffer-specific statuslines in vim. Value depends on extension used. For vim it is a dictionary {matcher_name : theme_name}, where matcher_name is either matcher_module.module_attribute or module_attribute (matcher_module defaults to powerline.matchers.vim) and module_attribute should point to a function that returns boolean value indicating that current buffer has (not) matched conditions. There is an exception for matcher_name though: if it is __tabline__ no functions are loaded. This special theme is used for tabline Vim option.

For shell and ipython it is a simple {prompt_type : theme_name}, where prompt_type is a string with no special meaning (specifically it does not refer to any Python function). Shell has continuation, and select prompts with rather self-explanatory names, IPython has in2, out and rewrite prompts (refer to IPython documentation for more details) while in prompt is the default.

components

Determines which extension components should be enabled. This key is highly extension-specific, here is the table of extensions and corresponding components:

Extension Component Description
vim statusline Makes Vim use powerline statusline.
tabline Makes Vim use powerline tabline.
shell prompt Makes shell display powerline prompt.
tmux Makes shell report its current working directory and screen width to tmux for tmux powerline bindings.

All components are enabled by default.

Color definitions

Location:powerline/colors.json
colors

Color definitions, consisting of a dict where the key is the name of the color, and the value is one of the following:

  • A cterm color index.
  • A list with a cterm color index and a hex color string (e.g. [123, "aabbcc"]). This is useful for colorschemes that use colors that aren’t available in color terminals.
gradients

Gradient definitions, consisting of a dict where the key is the name of the gradient, and the value is a list containing one or two items, second item is optional:

  • A list of cterm color indicies.
  • A list of hex color strings.

It is expected that you define gradients from least alert color to most alert or use non-alert colors.

Colorschemes

Location:powerline/colorschemes/name.json, powerline/colorschemes/__main__.json, powerline/colorschemes/extension/name.json

Colorscheme files are processed in order given: definitions from each next file override those from each previous file. It is required that either powerline/colorschemes/name.json, or powerline/colorschemes/extension/name.json exists.

name
Name of the colorscheme.
groups

Segment highlighting groups, consisting of a dict where the key is the name of the highlighting group (usually the function name for function segments), and the value is either

  1. a dict that defines the foreground color, background color and attributes:

    fg

    Foreground color. Must be defined in colors.

    bg

    Background color. Must be defined in colors.

    attr

    List of attributes. Valid values are one or more of bold, italic and underline. Note that some attributes may be unavailable in some applications or terminal emulators. If you do not need any attributes leave this empty.

  2. a string (an alias): a name of existing group. This group’s definition will be used when this color is requested.

mode_translations

Mode-specific highlighting for extensions that support it (e.g. the vim extension). It’s an easy way of changing a color in a specific mode. Consists of a dict where the key is the mode and the value is a dict with the following options:

colors
A dict where the key is the color to be translated in this mode, and the value is the new color. Both the key and the value must be defined in colors.
groups
Segment highlighting groups for this mode. Same syntax as the main groups option.

Themes

Location:powerline/themes/top_theme.json, powerline/themes/extension/__main__.json, powerline/themes/extension/name.json

Theme files are processed in order given: definitions from each next file override those from each previous file. It is required that file powerline/themes/extension/name.json exists.

{top_theme} component of the file name is obtained either from top_theme extension-specific key or from default_top_theme common configuration key. Powerline ships with the following top themes:

Theme Description
powerline Default powerline theme with fancy powerline symbols
unicode Theme without any symbols from private use area
unicode_terminus Theme containing only symbols from terminus PCF font
unicode_terminus_condensed Like above, but occupies as less space as possible
ascii Theme without any unicode characters at all
name
Name of the theme.
default_module
Python module where segments will be looked by default. Defaults to powerline.segments.{ext}.
spaces
Defines number of spaces just before the divider (on the right side) or just after it (on the left side). These spaces will not be added if divider is not drawn.
use_non_breaking_spaces

Determines whether non-breaking spaces should be used in place of the regular ones. This option is needed because regular spaces are not displayed properly when using powerline with some font configuration. Defaults to True.

Note

Unlike all other options this one is only checked once at startup using whatever theme is the default. If this option is set in the local themes it will be ignored. This option may also be ignored in some bindings.

dividers

Defines the dividers used in all Powerline extensions. This option should usually only be changed if you don’t have a patched font, or if you use a font patched with the legacy font patcher.

The hard dividers are used to divide segments with different background colors, while the soft dividers are used to divide segments with the same background color.

cursor_space
Space reserved for user input in shell bindings. It is measured in per cents.
cursor_columns
Space reserved for user input in shell bindings. Unlike cursor_space it is measured in absolute amout of columns.
segment_data

A dict where keys are segment names or strings {module}.{function}. Used to specify default values for various keys: after, before, contents (only for string segments if name is defined), display.

Key args (only for function and segments_list segments) is handled specially: unlike other values it is merged with all other values, except that a single {module}.{function} key if found prevents merging all {function} values.

When using local themes values of these keys are first searched in the segment description, then in segment_data key of a local theme, then in segment_data key of a default theme. For the default theme itself step 2 is obviously avoided.

Note

Top-level themes are out of equation here: they are merged before the above merging process happens.

segments

A dict with a left and a right lists, consisting of segment dictionaries. Shell themes may also contain above list of dictionaries. Each item in above list may have left and right keys like this dictionary, but no above key.

above list is used for multiline shell configurations.

left and right lists are used for segments that should be put on the left or right side in the output. Actual mechanizm of putting segments on the left or the right depends on used renderer, but most renderers require one to specify segment with width auto on either side to make generated line fill all of the available width.

Each segment dictionary has the following options:

type

The segment type. Can be one of function (default), string or segments_list:

function

The segment contents is the return value of the function defined in the function option.

List of function segments is available in Segment reference section.

string
A static string segment where the contents is defined in the contents option, and the highlighting group is defined in the highlight_group option.
segments_list

Sub-list of segments. This list only allows function, segments and args options.

List of lister segments is available in Lister reference section.

name

Segment name. If present allows referring to this segment in segment_data dictionary by this name. If not string segments may not be referred there at all and function and segments_list segments may be referred there using either {module}.{function_name} or {function_name}, whichever will be found first. Function name is taken from function key.

Note

If present prevents function key from acting as a segment name.

function
Function used to get segment contents, in format {module}.{function} or {function}. If {module} is omitted default_module option is used.
highlight_group

Highlighting group for this segment. Consists of a prioritized list of highlighting groups, where the first highlighting group that is available in the colorscheme is used.

Ignored for segments that have function type.

before
A string which will be prepended to the segment contents.
after
A string which will be appended to the segment contents.
contents
Segment contents, only required for string segments.
args
A dict of arguments to be passed to a function segment.
align
Aligns the segments contents to the left (l), center (c) or right (r). Has no sense if width key was not specified or if segment provides its own function for auto width handling and does not care about this option.
width

Enforces a specific width for this segment.

This segment will work as a spacer if the width is set to auto. Several spacers may be used, and the space will be distributed equally among all the spacer segments. Spacers may have contents, either returned by a function or a static string, and the contents can be aligned with the align property.

priority

Optional segment priority. Segments with priority None (the default priority, represented by null in json) will always be included, regardless of the width of the prompt/statusline.

If the priority is any number, the segment may be removed if the prompt/statusline width is too small for all the segments to be rendered. A lower number means that the segment has a higher priority.

Segments are removed according to their priority, with low priority segments being removed first.

draw_hard_divider, draw_soft_divider
Whether to draw a divider between this and the adjacent segment. The adjacent segment is to the right for segments on the left side, and vice versa. Hard dividers are used between segments with different background colors, soft ones are used between segments with same background. Both options default to True.
draw_inner_divider
Determines whether inner soft dividers are to be drawn for function segments. Only applicable for functions returning multiple segments. Defaults to False.
exclude_modes, include_modes
A list of modes where this segment will be excluded: the segment is not included or is included in all modes, except for the modes in one of these lists respectively. If exclude_modes is not present then it acts like an empty list (segment is not excluded from any modes). Without include_modes it acts like a list with all possible modes (segment is included in all modes). When there are both exclude_modes overrides include_modes.
exclude_function, include_function

Function name in a form {name} or {module}.{name} (in the first form {module} defaults to powerline.selectors.{ext}). Determines under which condition specific segment will be included or excluded. By default segment is always included and never excluded. exclude_function overrides include_function.

Note

Options exclude_/include_modes complement exclude_/include_functions: segment will be included if it is included by either include_mode or include_function and will be excluded if it is excluded by either exclude_mode or exclude_function.

display
Boolean. If false disables displaying of the segment. Defaults to True.
segments
A list of subsegments.