Uses \e[{fb};5;{color}m for colors ({fb} is either 38
(foreground) or 48 (background)). Should be used for most
terminals.

fbterm

Uses \e[{fb};{color}} for colors ({fb} is either 1
(foreground) or 2 (background)). Should be used for fbterm:
framebuffer terminal.

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 this option is 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.
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).

Absent. In this case logging will be done to stderr: equivalent to
[["logging.StreamHandler",[]]] or [null].

Plain string. In this case logging will be done to the given file:
"/file/name" is equivalent to [["logging.FileHandler",[["/file/name"]]]] or ["/file/name"]. Leading ~/ is expanded in
the file name, so using "~/.log/foo" is permitted. If directory
pointed by the option is absent, it will be created, but not its parent.

List of handler definitions. Handler definition may either be null,
a string or a list with two or three elements:

Logging class name and module. If module name is absent, it is
equivalent to logging.handlers.

Class constructor arguments in a form [[args[,kwargs]]]: accepted
variants are [] (no arguments), [args] (e.g.
[["/file/name"]]: only positional arguments) or [args,kwargs]
(e.g. [[],{"host":"localhost","port":6666}]: positional and
keyword arguments, but no positional arguments in the example).

Optional logging level. Overrides log_level key and has the same format.

Optional format string. Partially overrides log_format key and has the same format. “Partially” here
means that it may only specify more critical level.

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_terminus in unicode locales and ascii in
non-unicode locales. See Themes section for more details.

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.

For wm (lemonbar only) it is a dictionary
{output:theme_name} that maps the xrandr output names to the
local themes to use on that output.

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.

update_interval

Determines how often WM status bars need to be updated, in seconds. Only
valid for WM extensions which use powerline-daemon. Defaults to
2 seconds.

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

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

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 no
attributes are needed this list should be left empty.

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.

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.

outer_padding

Defines number of spaces at the end of output (on the right side) or at
the start of output (on the left side). Defaults to 1.

dividers

Defines the dividers used in all Powerline extensions.

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
segment_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 widthauto
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
segment_list:

function

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

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 segment_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_groups

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 autowidth 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 (i.e. with a greater priority number) 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.