Powerline¶

Fonts installation¶

Python package¶

1. Install a proper Python version (see issue #39 for a discussion regarding the required Python version on OS X):

   sudo port select python python27-apple
   

   . You may use homebrew for this:

   brew install python
   

   .

   Note

   In case you want or have to use powerline.sh socat-based client you should also install GNU env named genv. This may be achieved by running brew install coreutils.

2. Install Powerline using the following command:

   pip install --user git+git://github.com/Lokaltog/powerline
   

   Warning

   When using brew install to install Python one must not supply --user flag to pip.

   Note

   You need to use the GitHub URI when installing Powerline! This project is currently unavailable on the PyPI due to a naming conflict with an unrelated project.

   Note

   If you are powerline developer you should be aware that pip install --editable does not currently fully work. If you install powerline this way you will be missing powerline executable and need to symlink it. It will be located in scripts/powerline.

Vim installation¶

Any terminal vim version with Python 3.2+ or Python 2.6+ support should work, but if you’re using MacVim you need to install it using the following command:

brew install macvim --env-std --override-system-vim

Fonts installation¶

Install downloaded patched font by double-clicking the font file in Finder, then clicking Install this font in the preview window.

After installing the patched font you need to update MacVim or your terminal emulator to use the patched font. The correct font usually ends with for Powerline.

Bash prompt¶

Add the following line to your bashrc, where {repository_root} is the absolute path to your Powerline installation directory:

. {repository_root}/powerline/bindings/bash/powerline.sh

powerline-daemon -q
POWERLINE_BASH_CONTINUATION=1
POWERLINE_BASH_SELECT=1
. {repository_root}/powerline/bindings/bash/powerline.sh

Zsh prompt¶

Add the following line to your zshrc, where {repository_root} is the absolute path to your Powerline installation directory:

. {repository_root}/powerline/bindings/zsh/powerline.zsh

Fish prompt¶

Add the following line to your config.fish, where {repository_root} is the absolute path to your Powerline installation directory:

set fish_function_path $fish_function_path "{repository_root}/powerline/bindings/fish"
powerline-setup

Busybox (ash), mksh and dash prompt¶

After launching busybox run the following command:

. {repository_root}/powerline/bindings/shell/powerline.sh

Mksh users may put this line into ~/.mkshrc file. Dash users may use the following in ~/.profile:

if test "x$0" != "x${0#dash}" ; then
    export ENV={repository_root}/powerline/bindings/shell/powerline.sh
fi

Awesome widget¶

Add the following to your rc.lua, where {repository_root} is the absolute path to your Powerline installation directory:

package.path = package.path .. ';{repository_root}/powerline/bindings/awesome/?.lua'
require('powerline')

Then add the powerline_widget to your wibox:

right_layout:add(powerline_widget)

Qtile widget¶

Add the following to your ~/.config/qtile/config.py:

from powerline.bindings.qtile.widget import Powerline

screens = [
    Screen(
        top=bar.Bar([
                # ...
                Powerline(timeout=2),
                # ...
            ],
        ),
    ),
]

I3 bar¶

Add the following to your ~/.i3/config:

bar {
    i3bar_command i3bgbar

    status_command python /path/to/powerline/bindings/i3/powerline-i3.py
    font pango:PowerlineFont 12
}

where i3bgbar may be replaced with the path to the custom i3bar binary and PowerlineFont is any system font with powerline support.

Vim statusline¶

If installed using pip just add

python from powerline.vim import setup as powerline_setup
python powerline_setup()
python del powerline_setup

(replace python with python3 if appropriate) to your vimrc.

If you just cloned the repository add the following line to your vimrc, where {repository_root} is the absolute path to your Powerline installation directory:

set rtp+={repository_root}/powerline/bindings/vim

If you’re using pathogen and don’t want Powerline functionality in any other applications, simply add Powerline as a bundle and point the path above to the Powerline bundle directory, e.g. ~/.vim/bundle/powerline/powerline/bindings/vim.

With Vundle you may instead use

Bundle 'Lokaltog/powerline', {'rtp': 'powerline/bindings/vim/'}

(replace Bundle with NeoBundle for NeoBundle).

For vim-addon-manager it is even easier since you don’t need to write this big path or install anything by hand: powerline is installed and run just like any other plugin using

call vam#ActivateAddons(['powerline'])

Tmux statusline¶

Add the following lines to your .tmux.conf, where {repository_root} is the absolute path to your Powerline installation directory:

source "{repository_root}/powerline/bindings/tmux/powerline.conf"

run-shell "powerline-daemon -q"

IPython prompt¶

For IPython<0.11 add the following lines to your .ipython/ipy_user_conf.py:

# top
from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup

# main() function (assuming you launched ipython without configuration to
# create skeleton ipy_user_conf.py file):
powerline_setup()

For IPython>=0.11 add the following line to your ipython_config.py file in the profile you are using:

c.InteractiveShellApp.extensions = [
    'powerline.bindings.ipython.post_0_11'
]

IPython=0.11* is not supported and does not work. IPython<0.10 was not tested (not installable by pip).

Main configuration¶

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

Color definitions¶

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¶

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¶

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:

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.

Segments¶

Segments are written in Python, and the default segments provided with Powerline are located in powerline/segments/extension.py. User-defined segments can be defined in any module in sys.path or paths common configuration option, import is always absolute.

Segments are regular Python functions, and they may accept arguments. All arguments should have a default value which will be used for themes that don’t provide an args dict.

More information is available in Writing segments section.

Available segments¶

Vim listers¶

powerline.listers.vim.bufferlister(show_unlisted=False)[source]¶

List all buffers in segment_info format

Specifically generates a list of segment info dictionaries with buffer and bufnr keys set to buffer-specific ones, window, winnr and window_id keys set to None.

Adds either buf: or buf_nc: prefix to all segment highlight groups.

Parameters:	show_unlisted (bool) – True if unlisted buffers should be shown as well. Current buffer is always shown.

powerline.listers.vim.tablister()[source]¶

List all tab pages in segment_info format

Specifically generates a list of segment info dictionaries with window, winnr, window_id, buffer and bufnr keys set to tab-local ones and additional tabpage and tabnr keys.

Adds either tab: or tab_nc: prefix to all segment highlight groups.

Works best with vim-7.4 or later: earlier versions miss tabpage object and thus window objects are not available as well.

Available selectors¶

Vim overrides¶

Vim configuration can be overridden using the following options:

g:powerline_config_overrides

Dictionary, recursively merged with contents of powerline/config.json.

g:powerline_theme_overrides__{theme_name}

Dictionary, recursively merged with contents of powerline/themes/vim/theme_name.json. Note that this way you can’t redefine some value (e.g. segment) in list, only the whole list itself: only dictionaries are merged recursively.

g:powerline_config_paths

Paths list (each path must be expanded, ~ shortcut is not supported). Points to the list of directories which will be searched for configuration. When this option is present, none of the other locations are searched.

g:powerline_no_python_error

If this variable is set to a true value it will prevent Powerline from reporting an error when loaded in a copy of vim without the necessary Python support.

Powerline script overrides¶

Powerline script has a number of options controlling powerline behavior. Here VALUE always means “some JSON object”.

-c KEY.NESTED_KEY=VALUE or --config=KEY.NESTED_KEY=VALUE

Overrides options from powerline/config.json. KEY.KEY2.KEY3=VALUE is a shortcut for KEY={"KEY2": {"KEY3": VALUE}}. Multiple options (i.e. -c K1=V1 -c K2=V2) are allowed, result (in the example: {"K1": V1, "K2": V2}) is recursively merged with the contents of the file.

If VALUE is omitted then corresponding key will be removed from the configuration (if it was present).

-t THEME_NAME.KEY.NESTED_KEY=VALUE or --theme_option=THEME_NAME.KEY.NESTED_KEY=VALUE

Overrides options from powerline/themes/ext/THEME_NAME.json. KEY.NESTED_KEY=VALUE is processed like described above, {ext} is the first argument to powerline script. May be passed multiple times.

If VALUE is omitted then corresponding key will be removed from the configuration (if it was present).

-p PATH or --config_path=PATH

Sets directory where configuration should be read from. If present, no default locations are searched for configuration. No expansions are performed by powerline script itself, but -p ~/.powerline will likely be expanded by the shell to something like -p /home/user/.powerline.

Zsh/zpython overrides¶

Here overrides are controlled by similarly to the powerline script, but values are taken from zsh variables.

POWERLINE_CONFIG

Overrides options from powerline/config.json. Should be a zsh associative array with keys equal to KEY.NESTED_KEY and values being JSON strings. Pair KEY.KEY1 VALUE is equivalent to {"KEY": {"KEY1": VALUE}}. All pairs are then recursively merged into one dictionary and this dictionary is recursively merged with the contents of the file.

POWERLINE_THEME_CONFIG

Overrides options from powerline/themes/shell/*.json. Should be a zsh associative array with keys equal to THEME_NAME.KEY.NESTED_KEY and values being JSON strings. Is processed like the above POWERLINE_CONFIG, but only subdictionaries for THEME_NAME key are merged with theme configuration when theme with given name is requested.

POWERLINE_CONFIG_PATHS

Sets directories where configuration should be read from. If present, no default locations are searched for configuration. No expansions are performed by powerline script itself, but zsh usually performs them on its own if you set variable without quotes: POWERLINE_CONFIG_PATHS=( ~/example ). You should use array parameter or the usual colon-separated POWERLINE_CONFIG_PATHS=$HOME/path1:$HOME/path2.

Ipython overrides¶

Ipython overrides depend on ipython version. Before ipython-0.11 you should pass additional keyword arguments to setup() function. After ipython-0.11 you should use c.Powerline.KEY. Supported KEY strings or keyword argument names:

config_overrides

Overrides options from powerline/config.json. Should be a dictionary that will be recursively merged with the contents of the file.

theme_overrides

Overrides options from powerline/themes/ipython/*.json. Should be a dictionary where keys are theme names and values are dictionaries which will be recursively merged with the contents of the given theme.

paths

Sets directories where configuration should be read from. If present, no default locations are searched for configuration. No expansions are performed thus you cannot use paths starting with ~/.

Prompt command¶

In addition to the above configuration options you can use $POWERLINE_COMMAND environment variable to tell shell or tmux to use specific powerline implementation and $POWERLINE_CONFIG to tell zsh or tmux where powerline-config script is located. This is mostly useful for putting powerline into different directory.

If you want to disable prompt in shell, but still have tmux support or if you want to disable tmux support you can use variables $POWERLINE_NO_{SHELL}_PROMPT/$POWERLINE_NO_SHELL_PROMPT and $POWERLINE_NO_{SHELL}_TMUX_SUPPORT/$POWERLINE_NO_SHELL_TMUX_SUPPORT (substitute {SHELL} with the name of the shell (all-caps) you want to disable support for (e.g. BASH) or use all-inclusive SHELL that will disable support for all shells). These variables have no effect after configuration script was sourced (in fish case: after powerline-setup function was run). To disable specific feature support set one of these variables to some non-empty value.

If you do not want to disable prompt in shell, but yet do not want to launch python twice to get above lines you do not use in tcsh you should set $POWERLINE_NO_TCSH_ABOVE or $POWERLINE_NO_SHELL_ABOVE variable.

If you do not want to see additional space which is added to the right prompt in fish in order to support multiline prompt you should set $POWERLINE_NO_FISH_ABOVE or $POWERLINE_NO_SHELL_ABOVE variables.

I can’t see any fancy symbols, what’s wrong?¶

• Make sure that you’ve configured gvim or your terminal emulator to use a patched font.

• You need to set your LANG and LC_* environment variables to a UTF-8 locale (e.g. LANG=en_US.utf8). Consult your Linux distro’s documentation for information about setting these variables correctly.

• Make sure that vim is compiled with the --with-features=big flag.

• If you’re using rxvt-unicode make sure that it’s compiled with the --enable-unicode3 flag.

• If you’re using xterm make sure you have told it to work with unicode. You may need -u8 command-line argument, uxterm shell wrapper that is usually shipped with xterm for this or xterm*utf8 property set to 1 or 2 in ~/.Xresources (applied with xrdb). Note that in case uxterm is used configuration is done via uxterm*… properties and not xterm*….

  In any case the only absolute requirement is launching xterm with UTF-8 locale.

The fancy symbols look a bit blurry or “off”!¶

• Make sure that you have patched all variants of your font (i.e. both the regular and the bold font files).

I can’t see any fancy symbols, what’s wrong?¶

• If you’re using iTerm2, please update to this revision or newer.
• You need to set your LANG and LC_* environment variables to a UTF-8 locale (e.g. LANG=en_US.utf8). Consult your Linux distro’s documentation for information about setting these variables correctly.

The colors look weird in the default OS X Terminal app!¶

• The arrows may have the wrong colors if you have changed the “minimum contrast” slider in the color tab of your OS X settings.
• The default OS X Terminal app is known to have some issues with the Powerline colors. Please use another terminal emulator. iTerm2 should work fine.

The colors look weird in iTerm2!¶

• The arrows may have the wrong colors if you have changed the “minimum contrast” slider in the color tab of your OS X settings.
• Please disable background transparency to resolve this issue.

Statusline is getting wrapped to the next line in iTerm2¶

• Turn off “Treat ambigious-width characters as double width” in Preferences –> Text.
• Alternative: remove fancy dividers (they suck in this case), set ambiwidth to 2.

I receive a NameError when trying to use Powerline with MacVim!¶

• Please install MacVim using this command:

  brew install macvim --env-std --override-system-vim
  

  Then install Powerline locally with pip install --user, or by running these commands in the powerline directory:

  ./setup.py build
  ./setup.py install --user
  

I receive an ImportError when trying to use Powerline on OS X!¶

• This is caused by an invalid sys.path when using system vim and system Python. Please try to select another Python distribution:

  sudo port select python python27-apple
  

• See issue #39 for a discussion and other possible solutions for this issue.