Powerline¶
Overview¶
Powerline is a statusline plugin for vim, and provides statuslines and prompts for several other applications, including zsh, bash, tmux, IPython, Awesome, i3 and Qtile.
Features¶
- Extensible and feature rich, written in Python. Powerline was completely rewritten in Python to get rid of as much vimscript as possible. This has allowed much better extensibility, leaner and better config files, and a structured, object-oriented codebase with no mandatory third-party dependencies other than a Python interpreter.
- Stable and testable code base. Using Python has allowed unit testing of all the project code. The code is tested to work in Python 2.6+ and Python 3.
- Support for prompts and statuslines in many applications. Originally created exclusively for vim statuslines, the project has evolved to provide statuslines in tmux and several WMs, and prompts for shells like bash/zsh and other applications. It’s simple to write renderers for any other applications that Powerline doesn’t yet support.
- Configuration and colorschemes written in JSON. JSON is a standardized, simple and easy to use file format that allows for easy user configuration across all of Powerline’s supported applications.
- Fast and lightweight, with daemon support for even better performance. Although the code base spans a couple of thousand lines of code with no goal of “less than X lines of code”, the main focus is on good performance and as little code as possible while still providing a rich set of features. The new daemon also ensures that only one Python instance is launched for prompts and statuslines, which provides excellent performance.
But I hate Python / I don’t need shell prompts / this is just too much hassle for me / what happened to the original vim-powerline project / …
You should check out some of the Powerline derivatives. The most lightweight and feature-rich alternative is currently the vim-airline project.
Installation¶
Generic requirements¶
- Python 2.6 or later, 3.2 or later, PyPy 2.0 or later, PyPy3 2.3 or later. It is the only non-optional requirement.
- C compiler. Required to build powerline client on linux. If it is not present then powerline will fall back to shell script or python client.
socat
program. Required for shell variant of client which runs a bit faster than python version of the client, but still slower than C version.psutil
python package. Required for some segments like cpu_percent. Some segments have linux-only fallbacks forpsutil
functionality.hglib
python package and mercurial executable. Required to work with mercurial repositories.pygit2
python package orgit
executable. Required to work withgit
repositories.bzr
python package (note: not standalone executable). Required to work with bazaar repositories.pyuv
python package. Required for libuv-based watcher to work.i3ipc
python package. Required for i3wm bindings and segments.xrandr
program. Required for the multi-monitor lemonbar binding and thepowerline.listers.i3wm.output_lister()
.
Note
Until bazaar supports Python-3 or PyPy powerline will not support repository information when running in these interpreters.
Note
When using pip
, the {repository_root}
directory referenced in
documentation may be found using pip show powerline-status
. In the output
of pip show
there is a line like Location: {path}
, that {path}
is
{repository_root}
. Unless it is --editable
installation this is only
applicable for {repository_root}/powerline/…
paths: something like
{repository_root}/scripts/powerline-render
is not present.
When using other packages referenced paths may not exist, in this case refer to package documentation.
Pip installation¶
Due to a naming conflict with an unrelated project powerline is available on
PyPI under the powerline-status
name:
pip install powerline-status
is the preferred method because this will get the latest release. To get current development version
pip install --user git+git://github.com/powerline/powerline
may be used. If powerline was already checked out into some directory
pip install --user --editable={path_to_powerline}
is useful, but note that in this case pip
will not install powerline
executable and something like
ln -s {path_to_powerline}/scripts/powerline ~/.local/bin
will have to be done (~/.local/bin
should be replaced with some path
present in $PATH
).
Note
If ISP blocks git protocol for some reason github also provides ssh
(git+ssh://git@github.com/powerline/powerline
) and https
(git+https://github.com/powerline/powerline
) protocols. git
protocol
should be the fastest, but least secure one though.
Fonts installation¶
Powerline uses several special glyphs to get the arrow effect and some custom symbols for developers. This requires having either a symbol font or a patched font installed in the system. The used application (e.g. terminal emulator) must also either be configured to use patched fonts (in some cases even support it because custom glyphs live in private use area which some applications reserve for themselves) or support fontconfig for powerline to work properly with powerline-specific glyphs.
24-bit color support may be enabled if used terminal emulator supports it (see the terminal emulator support matrix).
There are basically two ways to get powerline glyphs displayed: use
PowerlineSymbols.otf
font as a fallback for one of the existing fonts or
install a patched font.
Patched fonts¶
This method is the fallback method and works for every terminal.
Download the font from powerline-fonts. If preferred font can’t be found in the powerline-fonts repo, then patching the preferred font is needed instead.
After downloading this font refer to platform-specific instructions.
Installation on various platforms¶
Installation on Linux¶
The following distribution-specific packages are officially supported, and they provide an easy way of installing and upgrading Powerline. The packages will automatically do most of the configuration.
- Arch Linux (AUR), Python 2 version
- Arch Linux (AUR), Python 3 version
- Gentoo Live ebuild in raiagent overlay
- Powerline package is available for Debian starting from Wheezy (via backports). Use search to get more information.
If used distribution does not have an official package installation guide below should be followed:
Install Python 3.2+, Python 2.6+ or PyPy and
pip
withsetuptools
. This step is distribution-specific, so no commands provided.Install Powerline using one of the following commands:
pip install --user powerline-status
will get the latest release version and
pip install --user git+git://github.com/powerline/powerline
will get the latest development version.
Note
Due to the naming conflict with an unrelated project powerline is named
powerline-status
in PyPI.Note
Powerline developers should be aware that``pip install –editable`` does not currently fully work. Installation performed this way are missing
powerline
executable that needs to be symlinked. It will be located inscripts/powerline
.
Fonts installation¶
Fontconfig¶
This method only works on Linux. It’s the second recommended method if terminal emulator supports it as patching fonts is not needed, and it generally works with any coding font.
Download the latest version of the symbol font and fontconfig file:
wget https://github.com/powerline/powerline/raw/develop/font/PowerlineSymbols.otf wget https://github.com/powerline/powerline/raw/develop/font/10-powerline-symbols.conf
Move the symbol font to a valid X font path. Valid font paths can be listed with
xset q
:mv PowerlineSymbols.otf ~/.local/share/fonts/
Update font cache for the path the font was moved to (root priveleges may be needed to update cache for the system-wide paths):
fc-cache -vf ~/.local/share/fonts/
Install the fontconfig file. For newer versions of fontconfig the config path is
~/.config/fontconfig/conf.d/
, for older versions it’s~/.fonts.conf.d/
:mv 10-powerline-symbols.conf ~/.config/fontconfig/conf.d/
If custom symbols still cannot be seen then try closing all instances of the terminal emulator. Restarting X may be needed for the changes to take effect.
If custom symbols still can’t be seen, double-check that the font have been installed to a valid X font path, and that the fontconfig file was installed to a valid fontconfig path. Alternatively try to install a patched font.
Patched font installation¶
This is the preferred method, but it is not always available because not all fonts were patched and not all fonts can be patched due to licensing issues.
After downloading font the following should be done:
Move the patched font to a valid X font path. Valid font paths can be listed with
xset q
:mv 'SomeFont for Powerline.otf' ~/.local/share/fonts/
Update font cache for the path the font was moved to (root privileges may be needed for updating font cache for some paths):
fc-cache -vf ~/.local/share/fonts/
After installing patched font terminal emulator, GVim or whatever application powerline should work with must be configured to use the patched font. The correct font usually ends with for Powerline.
If custom symbols cannot be seen then try closing all instances of the terminal emulator. X server may need to be restarted for the changes to take effect.
If custom symbols still can’t be seen then double-check that the font have been installed to a valid X font path.
Installation on OS X¶
Python package¶
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
Homebrew may be used here:
brew install python
Note
In case
powerline.sh
as a clientsocat
andcoreutils
need to be installed.coreutils
may be installed usingbrew install coreutils
.Install Powerline using one of the following commands:
pip install --user powerline-status
will get current release version and
pip install --user git+git://github.com/powerline/powerline
will get latest development version.
Warning
When using
brew install
to install Python one must not supply--user
flag topip
.Note
Due to the naming conflict with an unrelated project powerline is named
powerline-status
in PyPI.Note
Powerline developers should be aware that
pip install --editable
does not currently fully work. Installation performed this way are missingpowerline
executable that needs to be symlinked. It will be located inscripts/powerline
.
Vim installation¶
Any terminal vim version with Python 3.2+ or Python 2.6+ support should work, but MacVim users need to install it using the following command:
brew install macvim --env-std --with-override-system-vim
Fonts installation¶
To install patched font double-click the font file in Finder, then click Install this font in the preview window.
After installing the patched font MacVim or terminal emulator (whatever application powerline should work with) need to be configured to use the patched font. The correct font usually ends with for Powerline.
Usage¶
Application-specific requirements¶
Vim plugin requirements¶
The vim plugin requires a vim version with Python support compiled in. Presence
of Python support in Vim can be checked by running vim --version | grep
+python
.
If Python support is absent then Vim needs to be compiled with it. To do this
use --enable-pythoninterp
./configure
flag (Python 3 uses
--enable-python3interp
flag instead). Note that this also requires the
related Python headers to be installed. Please consult distribution’s
documentation for details on how to compile and install packages.
Vim version 7.4 or newer is recommended for performance reasons, but Powerline supports Vim 7.0.112 and higher.
Shell prompts requirements¶
Due to fish having incorrect code for prompt width calculations up to version
2.1 and no way to tell that certain sequence of characters has no width
(%{…%}
in zsh and \[…\]
in bash prompts serve exactly this purpose)
users that have fish versions below 2.1 are not supported..
WM widgets requirements¶
Awesome is supported starting from version 3.5.1, inclusive. QTile is supported from version 0.6, inclusive.
Terminal emulator requirements¶
Powerline uses several special glyphs to get the arrow effect and some custom symbols for developers. This requires either a symbol font or a patched font installed. Used terminal emulator must also support either patched fonts or fontconfig for Powerline to work properly.
24-bit color support can also be enabled if terminal emulator supports it.
Name | OS | Patched font support | Fontconfig support | 24-bit color support |
---|---|---|---|---|
Gvim | Linux | |||
iTerm2 | OS X | |||
Konsole | Linux | |||
lxterminal | Linux | |||
MacVim | OS X | |||
rxvt-unicode | Linux | [1] | ||
st | Linux | [2] | ||
Terminal.app | OS X | |||
libvte-based [3] | Linux | [4] | ||
xterm | Linux | [5] | ||
fbterm | Linux |
[1] | Must be compiled with --enable-unicode3 for the patched font to work. |
[2] | Since version 0.5. |
[3] | Including XFCE terminal and GNOME terminal. |
[4] | Since version 0.36. |
[5] | Uses nearest color from 8-bit palette. |
Plugins¶
Shell prompts¶
Note
Powerline daemon is not run automatically by any of my bindings. It is advised to add
powerline-daemon -q
before any other powerline-related code in the shell configuration file.
Bash prompt¶
Add the following line to the bashrc
, where {repository_root}
is the
absolute path to the Powerline installation directory (see repository root):
. {repository_root}/powerline/bindings/bash/powerline.sh
Note
Since without powerline daemon bash bindings are very slow PS2 (continuation) and PS3 (select) prompts are not set up. Thus it is advised to use
powerline-daemon -q
POWERLINE_BASH_CONTINUATION=1
POWERLINE_BASH_SELECT=1
. {repository_root}/powerline/bindings/bash/powerline.sh
in the bash configuration file. Without POWERLINE_BASH_*
variables PS2
and PS3 prompts are computed exactly once at bash startup.
Warning
At maximum bash continuation PS2 and select PS3 prompts are computed each time main PS1 prompt is computed. Thus putting e.g. current time into PS2 or PS3 prompt will not work as expected.
At minimum they are computed once on startup.
Zsh prompt¶
Add the following line to the zshrc
, where {repository_root}
is the
absolute path to the Powerline installation directory (see repository root):
. {repository_root}/powerline/bindings/zsh/powerline.zsh
Fish prompt¶
Add the following line to config.fish
, where {repository_root}
is
the absolute path to the Powerline installation directory (see repository
root):
set fish_function_path $fish_function_path "{repository_root}/powerline/bindings/fish"
powerline-setup
Warning
Fish is supported only starting from version 2.1.
Rcsh prompt¶
Powerline supports Plan9 rc reimplementation by Byron Rakitzis packaged by many *nix distributions. To use it add
. {repository_root}/powerline/bindings/rc/powerline.rc
({repository_root}
is the absolute path to the Powerline installation
directory, see repository root) to rcrc
file
(usually ~/.rcrc
) and make sure rc
is started as a login shell (with
-l
argument): otherwise this configuration file is not read.
Warning
Original Plan9 shell and its *nix port are not supported because they are
missing prompt
special function (it is being called once before each
non-continuation prompt). Since powerline could not support shell without
this or equivalent feature some other not-so-critical features of that port
were used.
Busybox (ash), mksh and dash prompt¶
After launching busybox run the following command:
. {repository_root}/powerline/bindings/shell/powerline.sh
where {repository_root}
is the absolute path to the Powerline installation
directory (see repository root).
Mksh users may put this line into ~/.mkshrc
file. Dash users may use the
following in ~/.profile
:
if test "$0" != "${0#dash}" ; then
export ENV={repository_root}/powerline/bindings/shell/powerline.sh
fi
Note
Dash users that already have $ENV
defined should either put the .
…/shell/powerline.sh
line in the $ENV
file or create a new file which
will source (using .
command) both former $ENV
file and
powerline.sh
files and set $ENV
to the path of this new file.
Warning
Mksh users have to set $POWERLINE_SHELL_CONTINUATION
and
$POWERLINE_SHELL_SELECT
to 1 to get PS2 and PS3 (continuation and
select) prompts support respectively: as command substitution is not
performed in these shells for these prompts they are updated once each time
PS1 prompt is displayed which may be slow.
It is also known that while PS2 and PS3 update is triggered at PS1 update it is actually performed only next time PS1 is displayed which means that PS2 and PS3 prompts will be outdated and may be incorrect for this reason.
Without these variables PS2 and PS3 prompts will be set once at startup. This only touches mksh users: busybox and dash both have no such problem.
Warning
Job count is using some weird hack that uses signals and temporary files for interprocess communication. It may be wrong sometimes. Not the case in mksh.
Warning
Busybox has two shells: ash
and hush
. Second is known to segfault in
busybox 1.22.1 when using powerline.sh
script.
Window manager widgets¶
Awesome widget¶
Note
Powerline currently only supports awesome 3.5 and 4+.
Note
The Powerline widget will spawn a shell script that runs in the
background and updates the statusline with awesome-client
.
Add the following to rc.lua
, where {repository_root}
is the absolute
path to Powerline installation directory (see repository root):
package.path = package.path .. ';{repository_root}/powerline/bindings/awesome/?.lua'
require('powerline')
Then add the powerline_widget
to wibox
:
-- awesome3.5
right_layout:add(powerline_widget)
-- awesome4+
s.mywibox:setup {
...
{ -- Right widgets
...
powerline_widget,
},
}
Qtile widget¶
Add the following to ~/.config/qtile/config.py
:
from libqtile.bar import Bar
from libqtile.config import Screen
from libqtile.widget import Spacer
from powerline.bindings.qtile.widget import PowerlineTextBox
screens = [
Screen(
top=Bar([
PowerlineTextBox(update_interval=2, side='left'),
Spacer(),
PowerlineTextBox(update_interval=2, side='right'),
],
35 # width
),
),
]
lemonbar (formerly bar-aint-recursive)¶
To run the bar simply start the binding script:
python /path/to/powerline/bindings/lemonbar/powerline-lemonbar.py
You can specify options to be passed to lemonbar
after --
, like so:
python /path/to/powerline/bindings/lemonbar/powerline-lemonbar.py –height 16 – -f “Source Code Pro for Powerline-9”
to run with i3, simply exec
this in the i3 config file and set the --i3
switch:
exec python /path/to/powerline/bindings/lemonbar/powerline-lemonbar.py –i3
Running the binding in i3-mode will require i3ipc (or the outdated i3-py).
See the lemonbar documentation for more information and options.
All powerline-lemonbar.py
arguments:
powerline-lemonbar.py [--i3] [--height=PIXELS] [--interval=SECONDS]
[--bar-command=CMD] [--] [ARGS]…
- --i3
- Subscribe for i3 events.
- --height PIXELS
- Bar height.
- --interval, -i SECONDS
- Refresh interval.
- --bar-command, -C CMD
- Name of the lemonbar executable to use.
- ARGS
- Extra arguments for lemonbar. Should be preceded with
--
argument in order not to be confused with script own arguments. - -h, --help
- Display help and exit.
I3 bar¶
Add the following to ~/.config/i3/config
:
bar {
status_command python /path/to/powerline/bindings/i3/powerline-i3.py
font pango:PowerlineFont 12
}
where PowerlineFont
is any system font with powerline support.
Other plugins¶
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 the vimrc
.
Note
Status line will not appear by default when there is only a single window
displayed. Run :h 'laststatus'
in Vim for more information.
If the repository was just cloned the following line needs to be added to the
vimrc
:
set rtp+={repository_root}/powerline/bindings/vim
where {repository_root}
is the absolute path to the Powerline installation
directory (see repository root).
If pathogen is used and Powerline functionality is not needed outside of Vim
then it is possible to simply add Powerline as a bundle and point the path above
to the Powerline bundle directory, e.g.
~/.vim/bundle/powerline/powerline/bindings/vim
.
Vundle and NeoBundle users may instead use
Bundle 'powerline/powerline', {'rtp': 'powerline/bindings/vim/'}
(NeoBundle users need NeoBundle
in place of Bundle
, otherwise setup is
the same).
Vim-addon-manager setup is even easier because it is not needed to write this
big path or install anything by hand: powerline
can be installed and
activated just like any other plugin using
call vam#ActivateAddons(['powerline'])
Warning
Never install powerline with pathogen/VAM/Vundle/NeoBundle and with pip.
If powerline functionality is needed in applications other then Vim then
system-wide installation (in case used OS distribution has powerline
package), pip-only or pip install --editable
kind of installation
performed on the repository installed by Vim plugin manager should be used.
No issues are accepted in powerline issue tracker for double pip/non-pip installations, especially if these issues occur after update.
Note
If supplied powerline.vim
file is used to load powerline there are
additional configuration variables available: g:powerline_pycmd
and
g:powerline_pyeval
. First sets command used to load powerline: expected
values are "py"
and "py3"
. Second sets function used in statusline,
expected values are "pyeval"
and "py3eval"
.
If g:powerline_pycmd
is set to the one of the expected values then
g:powerline_pyeval
will be set accordingly. If it is set to some other
value then g:powerline_pyeval
must also be set. Powerline will not check
that Vim is compiled with Python support if g:powerline_pycmd
is set to
an unexpected value.
These values are to be used to specify the only Python that is to be loaded if both versions are present: Vim may disable loading one python version if other was already loaded. They should also be used if two python versions are able to load simultaneously, but powerline was installed only for python-3 version.
Tmux statusline¶
Add the following lines to .tmux.conf
, where {repository_root}
is
the absolute path to the Powerline installation directory (see repository
root):
source "{repository_root}/powerline/bindings/tmux/powerline.conf"
Note
The availability of the powerline-config
command is required for
powerline support. The location of this script may be specified via
the $POWERLINE_CONFIG_COMMAND
environment variable.
Note
It is advised to run powerline-daemon
before adding the above line to
tmux.conf. To do so add:
run-shell "powerline-daemon -q"
to .tmux.conf
.
Warning
Segments which depend on current working directory (e.g.
powerline.segments.common.vcs.branch()
) require also setting up
shell bindings. It is not required to use powerline
shell prompt, components setting allows to
set up only powerline bindings for tmux without altering your prompt.
Without setting up shell bindings powerline will use current working
directory of tmux server which is probably not what you need.
Segments which depend on environment like
powerline.segments.common.env.virtualenv()
will not work at all
(i.e. they will use environment of the tmux server), tracking environment
changes is going to slow down shell a lot.
In any case it is suggested to avoid both kinds of segments in tmux themes because even support for tracking current directory is very limited:
- It works only in shell. Should you e.g. run Vim and run
:cd
there you will get current working directory from shell. - It works only in local shell and requires configuring it.
- Some shells are not supported at all.
IPython prompt¶
For IPython<0.11 add the following lines to .ipython/ipy_user_conf.py
:
# top
from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup
# main() function (assuming ipython was launched without configuration to
# create skeleton ipy_user_conf.py file):
powerline_setup()
For IPython>=0.11 add the following line to
~/.ipython/profile_default/ipython_config.py
file in the used profile:
c = get_config()
c.InteractiveShellApp.extensions = [
'powerline.bindings.ipython.post_0_11'
]
For IPython>=5.0 you may use the above set up, but it is deprecated. It is suggested to use
from powerline.bindings.ipython.since_5 import PowerlinePrompts
c = get_config()
c.TerminalInteractiveShell.simple_prompt = False
c.TerminalInteractiveShell.prompts_class = PowerlinePrompts
Note
Setting simple_prompt
to False after IPython-5.0 is required regardless
of whether you use c.InteractiveShellApp.extensions
setting or
c.TerminalInteractiveShell.prompts_class
. But you probably already have
this line because IPython is not very useful without it.
IPython=0.11* is not supported and does not work. IPython<0.10 was not tested (not installable by pip).
PDB prompt¶
To use Powerline with PDB prompt you need to use custom class. Inherit your
class from pdb.Pdb
and decorate it with
powerline.bindings.pdb.use_powerline_prompt()
:
import pdb
from powerline.bindings.pdb import use_powerline_prompt
@use_powerline_prompt
class MyPdb(pdb.Pdb):
pass
MyPdb.run('some.code.to.debug()')
. Alternatively you may use
python -mpowerline.bindings.pdb path/to/script.py
just like you used python -m pdb
.
Configuration and customization¶
Note
Forking the main GitHub repo is not needed to personalize Powerline configuration! Please read through the Quick setup guide for a quick introduction to user configuration.
Powerline is configured with one main configuration file, and with separate configuration files for themes and colorschemes. All configuration files are written in JSON, with the exception of segment definitions, which are written in Python.
Powerline provides default configurations in the following locations:
- Main configuration
powerline/config.json
- Colorschemes
powerline/colorschemes/name.json
,powerline/colorschemes/extension/__main__.json
,powerline/colorschemes/extension/name.json
- Themes
powerline/themes/top_theme.json
,powerline/themes/extension/__main__.json
,powerline/themes/extension/default.json
Here {powerline} is one of the following:
- The default configuration directory located in the main package:
powerline_root/powerline/config_files
. May be absent in some packages (e.g. when installing via Gentoo ebuilds). - If variable
$XDG_CONFIG_DIRS
is set and non-empty then to anydirectory/powerline
where {directory} is a directory listed in a colon-separated$XDG_CONFIG_DIRS
list. Directories are checked in reverse order. - User configuration directory located in
$XDG_CONFIG_HOME/powerline
. This usually corresponds to~/.config/powerline
on all platforms.
If per-instance configuration is needed please refer to Local configuration overrides.
Note
Existing multiple configuration files that have the same name, but are placed in different directories, will be merged. Merging happens in the order given in the above list of possible {powerline} meanings.
When merging configuration only dictionaries are merged and they are merged recursively: keys from next file overrule those from the previous unless corresponding values are both dictionaries in which case these dictionaries are merged and key is assigned the result of the merge.
Note
Some configuration files (i.e. themes and colorschemes) have two level of merging: first happens merging described above, second theme- or colorscheme-specific merging happens.
Quick setup guide¶
This guide will help you with the initial configuration of Powerline.
Look at configuration in powerline_root/powerline/config_files
. If you
want to modify some file you can create ~/.config/powerline
directory
and put modifications there: all configuration files are merged with each other.
Each extension (vim, tmux, etc.) has its own theme, and they are located in
config directory/themes/extension/default.json
. Best way to modify
it is to copy this theme as a whole, remove segment_data
key with
corresponding value if present (unless you need to modify it, in which case only
modifications must be left) and do necessary modifications in the list of
segments (lists are not subject to merging: this is why you need a copy).
If you want to move, remove or customize any of the provided segments in the copy, you can do that by updating the segment dictionary in the theme you want to customize. A segment dictionary looks like this:
{
"name": "segment_name"
...
}
You can move the segment dictionaries around to change the segment positions, or remove the entire dictionary to remove the segment from the prompt or statusline.
Note
It’s essential that the contents of all your configuration files
is valid JSON! It’s strongly recommended that you run your configuration
files through jsonlint
after changing them.
Note
If your modifications appear not to work, run powerline-lint script. This script should show you the location of the error.
Some segments need a user configuration to work properly. Here’s a couple of segments that you may want to customize right away:
- E-mail alert segment
You have to set your username and password (and possibly server/port) for the e-mail alert segment. If you’re using GMail it’s recommended that you generate an application-specific password for this purpose.
Open a theme file, scroll down to the
email_imap_alert
segment and set yourusername
andpassword
. The server defaults to GMail’s IMAP server, but you can set the server/port by adding aserver
and aport
argument.- Weather segment
The weather segment will try to find your location using a GeoIP lookup, so unless you’re on a VPN you probably won’t have to change the location query.
If you want to change the location query or the temperature unit you’ll have to update the segment arguments. Open a theme file, scroll down to the weather segment and update it to include unit/location query arguments:
{ "name": "weather", "priority": 50, "args": { "unit": "F", "location_query": "oslo, norway" } },
References¶
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 used terminal emulator supports 24-bit colors.
This variable is forced to be
false
if term_escape_style option is set to"fbterm"
or if it is set to"auto"
and powerline detected fbterm.
term_escape_style
Defines what escapes sequences should be used. Accepts three variants:
Variant Description auto xterm
orfbterm
depending on$TERM
variable value:TERM=fbterm
impliesfbterm
escaping style, all other values selectxterm
escaping.xterm Uses \e[{fb};5;{color}m
for colors ({fb}
is either38
(foreground) or48
(background)). Should be used for most terminals.fbterm Uses \e[{fb};{color}}
for colors ({fb}
is either1
(foreground) or2
(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).
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 how logs will be handled. There are three variants here:
- 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.
- Logging class name and module. If module name is absent, it is
equivalent to
- Absent. In this case logging will be done to stderr: equivalent to
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 toNone
. 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 andascii
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}
, wherematcher_name
is eithermatcher_module.module_attribute
ormodule_attribute
(matcher_module
defaults topowerline.matchers.vim
) andmodule_attribute
should point to a function that returns boolean value indicating that current buffer has (not) matched conditions. There is an exception formatcher_name
though: if it is__tabline__
no functions are loaded. This special theme is used fortabline
Vim option.For shell and ipython it is a simple
{prompt_type : theme_name}
, whereprompt_type
is a string with no special meaning (specifically it does not refer to any Python function). Shell hascontinuation
, andselect
prompts with rather self-explanatory names, IPython hasin2
,out
andrewrite
prompts (refer to IPython documentation for more details) whilein
prompt is the default.For wm (lemonbar only) it is a dictionary
{output : theme_name}
that maps thexrandr
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.
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 gradients are defined from least alert color to most alert or non-alert colors are used.
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
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.
attrs
List of attributes. Valid values are one or more of
bold
,italic
andunderline
. 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:
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 |
powerline_unicode7 | Theme with powerline dividers and unicode-7 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 |
powerline_terminus | Like unicode_terminus, but with powerline symbols |
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.
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 thesoft
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 insegment_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 aright
lists, consisting of segment dictionaries. Shell themes may also containabove
list of dictionaries. Each item inabove
list may haveleft
andright
keys like this dictionary, but noabove
key.above
list is used for multiline shell configurations.left
andright
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
orsegment_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_groups option.
segment_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 andfunction
andsegment_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 ifwidth
key was not specified or if segment provides its own function forauto
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 thealign
property.
priority
Optional segment priority. Segments with priority
None
(the default priority, represented bynull
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). Withoutinclude_modes
it acts like a list with all possible modes (segment is included in all modes). When there are bothexclude_modes
overridesinclude_modes
.
exclude_function
,include_function
Function name in a form
{name}
or{module}.{name}
(in the first form{module}
defaults topowerline.selectors.{ext}
). Determines under which condition specific segment will be included or excluded. By default segment is always included and never excluded.exclude_function
overridesinclude_function
.Note
Options exclude_/include_modes complement
exclude_/include_functions
: segment will be included if it is included by eitherinclude_mode
orinclude_function
and will be excluded if it is excluded by eitherexclude_mode
orexclude_function
.
display
- Boolean. If false disables displaying of the segment.
Defaults to
True
.
segments
- A list of subsegments.
Segment reference¶
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¶
Common segments¶
-
powerline.segments.common.vcs.
branch
(ignore_statuses=(), status_colors=False)¶ Return the current VCS branch.
Parameters: - status_colors (bool) – Determines whether repository status will be used to determine highlighting. Default: False.
- ignore_statuses (list) – List of statuses which will not result in repo being marked as dirty. Most
useful is setting this option to
["U"]
: this will ignore repository which has just untracked files (i.e. repository with modified, deleted or removed files will be marked as dirty, while just untracked files will make segment show clean repository). Only applicable ifstatus_colors
option is True.
Highlight groups used:
branch_clean
,branch_dirty
,branch
.
-
powerline.segments.common.vcs.
stash
()¶ Return the number of current VCS stash entries, if any.
Highlight groups used:
stash
.
-
powerline.segments.common.sys.
cpu_load_percent
(interval=1, format=u'{0:.0f}%', update_first=True)¶ Return the average CPU load as a percentage.
Requires the
psutil
module.Parameters: format (str) – Output format. Accepts measured CPU load as the first argument. Highlight groups used:
cpu_load_percent_gradient
(gradient) orcpu_load_percent
.
-
powerline.segments.common.sys.
system_load
(short=False, track_cpu_count=False, threshold_bad=2, threshold_good=1, format=u'{avg:.1f}')[source]¶ Return system load average.
Highlights using
system_load_good
,system_load_bad
andsystem_load_ugly
highlighting groups, depending on the thresholds passed to the function.Parameters: - format (str) – format string, receives
avg
as an argument - threshold_good (float) – threshold for gradient level 0: any normalized load average below this value will have this gradient level.
- threshold_bad (float) – threshold for gradient level 100: any normalized load average above this
value will have this gradient level. Load averages between
threshold_good
andthreshold_bad
receive gradient level that indicates relative position in this interval: (100 * (cur-good) / (bad-good)
). Note: both parameters are checked against normalized load averages. - track_cpu_count (bool) – if True powerline will continuously poll the system to detect changes in the number of CPUs.
- short (bool) – if True only the sys load over last 1 minute will be displayed.
Divider highlight group used:
background:divider
.Highlight groups used:
system_load_gradient
(gradient) orsystem_load
.- format (str) – format string, receives
-
powerline.segments.common.sys.
uptime
(shorten_len=3, seconds_format=u' {seconds:d}s', minutes_format=u' {minutes:d}m', hours_format=u' {hours:d}h', days_format=u'{days:d}d')[source]¶ Return system uptime.
Parameters: - days_format (str) – day format string, will be passed
days
as the argument - hours_format (str) – hour format string, will be passed
hours
as the argument - minutes_format (str) – minute format string, will be passed
minutes
as the argument - seconds_format (str) – second format string, will be passed
seconds
as the argument - shorten_len (int) – shorten the amount of units (days, hours, etc.) displayed
Divider highlight group used:
background:divider
.- days_format (str) – day format string, will be passed
-
powerline.segments.common.net.
external_ip
(interval=300, query_url=u'http://ipv4.icanhazip.com/')¶ Return external IP address.
Parameters: query_url (str) – URI to query for IP address, should return only the IP address as a text string
Suggested URIs:
- http://ipv4.icanhazip.com/
- http://ipv6.icanhazip.com/
- http://icanhazip.com/ (returns IPv6 address if available, else IPv4)
Divider highlight group used:
background:divider
.
-
powerline.segments.common.net.
hostname
(exclude_domain=False, only_if_ssh=False)[source]¶ Return the current hostname.
Parameters: - only_if_ssh (bool) – only return the hostname if currently in an SSH session
- exclude_domain (bool) – return the hostname without domain if there is one
-
powerline.segments.common.net.
internal_ip
(ipv=4, interface=u'auto')[source]¶ Return internal IP address
Requires
netifaces
module to work properly.Parameters: - interface (str) –
Interface on which IP will be checked. Use
auto
to automatically detect interface. In this case interfaces with lower numbers will be preferred over interfaces with similar names. Order of preference based on names:eth
andenp
followed by number or the end of string.ath
,wlan
andwlp
followed by number or the end of string.teredo
followed by number or the end of string.- Any other interface that is not
lo*
. lo
followed by number or the end of string.
Use
default_gateway
to detect the interface based on the machine’s default gateway (i.e., the router to which it is connected). - ipv (int) – 4 or 6 for ipv4 and ipv6 respectively, depending on which IP address you need exactly.
- interface (str) –
-
powerline.segments.common.net.
network_load
(interval=1, update_first=True, interface=u'auto', si_prefix=False, suffix=u'B/s', sent_format=u'UL {value:>8}', recv_format=u'DL {value:>8}')¶ Return the network load.
Uses the
psutil
module if available for multi-platform compatibility, falls back to reading/sys/class/net/interface/statistics/rx,tx_bytes
.Parameters: - interface (str) – Network interface to measure (use the special value “auto” to have powerline try to auto-detect the network interface).
- suffix (str) – String appended to each load string.
- si_prefix (bool) – Use SI prefix, e.g. MB instead of MiB.
- recv_format (str) – Format string that determines how download speed should look like. Receives
value
as argument. - sent_format (str) – Format string that determines how upload speed should look like. Receives
value
as argument. - recv_max (float) – Maximum number of received bytes per second. Is only used to compute gradient level.
- sent_max (float) – Maximum number of sent bytes per second. Is only used to compute gradient level.
Divider highlight group used:
network_load:divider
.Highlight groups used:
network_load_sent_gradient
(gradient) ornetwork_load_recv_gradient
(gradient) ornetwork_load_gradient
(gradient),network_load_sent
ornetwork_load_recv
ornetwork_load
.
-
powerline.segments.common.env.
cwd
(ellipsis=u'...', use_path_separator=False, dir_limit_depth=None, dir_shorten_len=None, shorten_home=True)¶ Return the current working directory.
Returns a segment list to create a breadcrumb-like effect.
Parameters: - dir_shorten_len (int) – shorten parent directory names to this length (e.g.
/long/path/to/powerline
→/l/p/t/powerline
) - dir_limit_depth (int) – limit directory depth to this number (e.g.
/long/path/to/powerline
→⋯/to/powerline
) - use_path_separator (bool) – Use path separator in place of soft divider.
- shorten_home (bool) – Shorten home directory to
~
. - ellipsis (str) – Specifies what to use in place of omitted directories. Use None to not show this subsegment at all.
Divider highlight group used:
cwd:divider
.Highlight groups used:
cwd:current_folder
orcwd
. It is recommended to define all highlight groups.- dir_shorten_len (int) – shorten parent directory names to this length (e.g.
-
powerline.segments.common.env.
environment
(variable=None)[source]¶ Return the value of any defined environment variable
Parameters: variable (string) – The environment variable to return if found
-
powerline.segments.common.env.
user
(hide_domain=False, hide_user=None)[source]¶ Return the current user.
Parameters: - hide_user (str) – Omit showing segment for users with names equal to this string.
- hide_domain (bool) – Drop domain component if it exists in a username (delimited by ‘@’).
Highlights the user with the
superuser
if the effective user ID is 0.Highlight groups used:
superuser
oruser
. It is recommended to define all highlight groups.
-
powerline.segments.common.env.
virtualenv
(ignore_conda=False, ignore_venv=False)[source]¶ Return the name of the current Python or conda virtualenv.
Parameters: - ignore_venv (bool) – Whether to ignore virtual environments. Default is False.
- ignore_conda (bool) – Whether to ignore conda environments. Default is False.
-
powerline.segments.common.bat.
battery
(offline=u' ', online=u'C', empty_heart=u'O', full_heart=u'O', gamify=False, steps=5, format=u'{ac_state} {capacity:3.0%}')[source]¶ Return battery charge status.
Parameters: - format (str) – Percent format in case gamify is False. Format arguments:
ac_state
which is equal to eitheronline
oroffline
string arguments andcapacity
which is equal to current battery capacity in interval [0, 100]. - steps (int) – Number of discrete steps to show between 0% and 100% capacity if gamify is True.
- gamify (bool) – Measure in hearts (♥) instead of percentages. For full hearts
battery_full
highlighting group is preferred, for empty hearts there isbattery_empty
.battery_online
orbattery_offline
group will be used for leading segment containingonline
oroffline
argument contents. - full_heart (str) – Heart displayed for “full” part of battery.
- empty_heart (str) – Heart displayed for “used” part of battery. It is also displayed using another gradient level and highlighting group, so it is OK for it to be the same as full_heart as long as necessary highlighting groups are defined.
- online (str) – Symbol used if computer is connected to a power supply.
- offline (str) – Symbol used if computer is not connected to a power supply.
battery_gradient
andbattery
groups are used in any case, first is preferred.Highlight groups used:
battery_full
orbattery_gradient
(gradient) orbattery
,battery_empty
orbattery_gradient
(gradient) orbattery
,battery_online
orbattery_ac_state
orbattery_gradient
(gradient) orbattery
,battery_offline
orbattery_ac_state
orbattery_gradient
(gradient) orbattery
.- format (str) – Percent format in case gamify is False. Format arguments:
-
powerline.segments.common.wthr.
weather
(interval=600, update_first=True, location_query=None, temp_hottest=40, temp_coldest=-30, temp_format=None, unit=u'C', icons=None)¶ Return weather from Yahoo! Weather.
Uses GeoIP lookup from http://geoip.nekudo.com to automatically determine your current location. This should be changed if you’re in a VPN or if your IP address is registered at another location.
Returns a list of colorized icon and temperature segments depending on weather conditions.
Parameters: - unit (str) – temperature unit, can be one of
F
,C
orK
- location_query (str) – location query for your current location, e.g.
oslo, norway
- icons (dict) – dict for overriding default icons, e.g.
{'heavy_snow' : u'❆'}
- temp_format (str) – format string, receives
temp
as an argument. Should also hold unit. - temp_coldest (float) – coldest temperature. Any temperature below it will have gradient level equal to zero.
- temp_hottest (float) – hottest temperature. Any temperature above it will have gradient level equal
to 100. Temperatures between
temp_coldest
andtemp_hottest
receive gradient level that indicates relative position in this interval (100 * (cur-coldest) / (hottest-coldest)
).
Divider highlight group used:
background:divider
.Highlight groups used:
weather_conditions
orweather
,weather_temp_gradient
(gradient) orweather
. Also usesweather_conditions_{condition}
for all weather conditions supported by Yahoo.- unit (str) – temperature unit, can be one of
-
powerline.segments.common.time.
date
(istime=False, format=u'%Y-%m-%d')[source]¶ Return the current date.
Parameters: - format (str) – strftime-style date format string
- istime (bool) – If true then segment uses
time
highlight group.
Divider highlight group used:
time:divider
.Highlight groups used:
time
ordate
.
-
powerline.segments.common.mail.
email_imap_alert
(username, password, interval=60, update_first=True, use_ssl=None, folder=u'INBOX', port=993, server=u'imap.gmail.com', max_msgs=None)¶ Return unread e-mail count for IMAP servers.
Parameters: - username (str) – login username
- password (str) – login password
- server (str) – e-mail server
- port (int) – e-mail server port
- folder (str) – folder to check for e-mails
- max_msgs (int) – Maximum number of messages. If there are more messages then max_msgs then it
will use gradient level equal to 100, otherwise gradient level is equal to
100 * msgs_num / max_msgs
. If not present gradient is not computed. - use_ssl (bool) – If
True
then use SSL connection. IfFalse
then do not use it. Default isTrue
if port is equal to 993 andFalse
otherwise.
Highlight groups used:
email_alert_gradient
(gradient),email_alert
.
-
powerline.segments.common.players.
clementine
(state_symbols={u'fallback': u'', u'pause': u'~', u'stop': u'X', u'play': u'>'}, format=u'{state_symbol} {artist} - {title} ({total})')¶ Return clementine player information
Requires
dbus
python module.This player segment should be added like this:
{ "function": "powerline.segments.common.players.clementine", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player_fallback
orplayer
,player_play
orplayer
,player_pause
orplayer
,player_stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
cmus
(state_symbols={u'fallback': u'', u'pause': u'~', u'stop': u'X', u'play': u'>'}, format=u'{state_symbol} {artist} - {title} ({total})')¶ Return CMUS player information
Requires cmus-remote command be acessible from $PATH.
This player segment should be added like this:
{ "function": "powerline.segments.common.players.cmus", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player_fallback
orplayer
,player_play
orplayer
,player_pause
orplayer
,player_stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
dbus_player
(player_name, state_symbols={u'fallback': u'', u'pause': u'~', u'stop': u'X', u'play': u'>'}, format=u'{state_symbol} {artist} - {title} ({total})')¶ Return generic dbus player state
- Requires
dbus
python module. Only for players that support specific protocol - (e.g. like
spotify()
andclementine()
).
This player segment should be added like this:
{ "function": "powerline.segments.common.players.dbus_player", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player_fallback
orplayer
,player_play
orplayer
,player_pause
orplayer
,player_stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known. - player_name (str) – Player name. Used in error messages only.
- bus_name (str) – Dbus bus name.
- player_path (str) – Path to the player on the given bus.
- iface_prop (str) – Interface properties name for use with dbus.Interface.
- iface_player (str) – Player name.
- Requires
-
powerline.segments.common.players.
itunes
(state_symbols={u'fallback': u'', u'pause': u'~', u'stop': u'X', u'play': u'>'}, format=u'{state_symbol} {artist} - {title} ({total})')¶ Return iTunes now playing information
Requires
osascript
.This player segment should be added like this:
{ "function": "powerline.segments.common.players.itunes", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player_fallback
orplayer
,player_play
orplayer
,player_pause
orplayer
,player_stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
mocp
(state_symbols={u'fallback': u'', u'pause': u'~', u'stop': u'X', u'play': u'>'}, format=u'{state_symbol} {artist} - {title} ({total})')¶ Return MOC (Music On Console) player information
Requires version >= 2.3.0 and
mocp
executable in$PATH
.This player segment should be added like this:
{ "function": "powerline.segments.common.players.mocp", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player_fallback
orplayer
,player_play
orplayer
,player_pause
orplayer
,player_stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
mpd
(state_symbols={u'fallback': u'', u'pause': u'~', u'stop': u'X', u'play': u'>'}, format=u'{state_symbol} {artist} - {title} ({total})', port=6600, password=None, host=u'localhost')¶ Return Music Player Daemon information
Requires
mpd
Python module (e.g.python-mpd2
orpython-mpd
Python package) or alternatively thempc
command to be acessible from $PATH.This player segment should be added like this:
{ "function": "powerline.segments.common.players.mpd", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player_fallback
orplayer
,player_play
orplayer
,player_pause
orplayer
,player_stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known. - host (str) – Host on which mpd runs.
- password (str) – Password used for connecting to daemon.
- port (int) – Port which should be connected to.
- format (str) –
-
powerline.segments.common.players.
rdio
(state_symbols={u'fallback': u'', u'pause': u'~', u'stop': u'X', u'play': u'>'}, format=u'{state_symbol} {artist} - {title} ({total})')¶ Return rdio player information
Requires
osascript
available in $PATH.This player segment should be added like this:
{ "function": "powerline.segments.common.players.rdio", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player_fallback
orplayer
,player_play
orplayer
,player_pause
orplayer
,player_stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
rhythmbox
(state_symbols={u'fallback': u'', u'pause': u'~', u'stop': u'X', u'play': u'>'}, format=u'{state_symbol} {artist} - {title} ({total})')¶ Return rhythmbox player information
Requires
rhythmbox-client
available in $PATH.This player segment should be added like this:
{ "function": "powerline.segments.common.players.rhythmbox", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player_fallback
orplayer
,player_play
orplayer
,player_pause
orplayer
,player_stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
spotify
(state_symbols={u'fallback': u'', u'pause': u'~', u'stop': u'X', u'play': u'>'}, format=u'{state_symbol} {artist} - {title} ({total})')¶ Return spotify player information
Requires
dbus
python module.This player segment should be added like this:
{ "function": "powerline.segments.common.players.spotify", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player_fallback
orplayer
,player_play
orplayer
,player_pause
orplayer
,player_stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
spotify_apple_script
(state_symbols={u'fallback': u'', u'pause': u'~', u'stop': u'X', u'play': u'>'}, format=u'{state_symbol} {artist} - {title} ({total})')¶ Return spotify player information
Requires
osascript
available in $PATH.This player segment should be added like this:
{ "function": "powerline.segments.common.players.spotify_apple_script", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player_fallback
orplayer
,player_play
orplayer
,player_pause
orplayer
,player_stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
spotify_dbus
(state_symbols={u'fallback': u'', u'pause': u'~', u'stop': u'X', u'play': u'>'}, format=u'{state_symbol} {artist} - {title} ({total})')¶ Return spotify player information
Requires
dbus
python module.This player segment should be added like this:
{ "function": "powerline.segments.common.players.spotify", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player_fallback
orplayer
,player_play
orplayer
,player_pause
orplayer
,player_stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
i3wm segments¶
-
powerline.segments.i3wm.
mode
(names={u'default': None})[source]¶ Returns current i3 mode
Parameters: names (dict) – Specifies the string to show for various modes. Use null
to hide a mode (default
is hidden by default).Highligh groups used:
mode
-
powerline.segments.i3wm.
scratchpad
(icons={u'fresh': u'O', u'changed': u'X'})[source]¶ Returns the windows currently on the scratchpad
Parameters: icons (dict) – Specifies the strings to show for the different scratchpad window states. Must contain the keys fresh
andchanged
.Highlight groups used:
scratchpad
orscratchpad:visible
,scratchpad
orscratchpad:focused
,scratchpad
orscratchpad:urgent
.
-
powerline.segments.i3wm.
workspace
(strip=False, workspace=None)[source]¶ Return the specified workspace name
Parameters: - workspace (str) – Specifies which workspace to show. If unspecified, may be set by the
list_workspaces
lister if used, otherwise falls back to currently focused workspace. - strip (bool) – Specifies whether workspace numbers (in the
1: name
format) should be stripped from workspace names before being displayed. Defaults to false.
Highlight groups used:
workspace
orw_visible
,workspace
orw_focused
,workspace
orw_urgent
.- workspace (str) – Specifies which workspace to show. If unspecified, may be set by the
-
powerline.segments.i3wm.
workspaces
(strip=0, output=None, only_show=None)[source]¶ Return list of used workspaces
Parameters: - only_show (list) – Specifies which workspaces to show. Valid entries are
"visible"
,"urgent"
and"focused"
. If omitted ornull
all workspaces are shown. - output (str) – May be set to the name of an X output. If specified, only workspaces on that output are shown. Overrides automatic output detection by the lemonbar renderer and bindings.
- strip (int) – Specifies how many characters from the front of each workspace name should be stripped (e.g. to remove workspace numbers). Defaults to zero.
Highlight groups used:
workspace
orw_visible
,workspace
orw_focused
,workspace
orw_urgent
.- only_show (list) – Specifies which workspaces to show. Valid entries are
PDB segments¶
-
powerline.segments.pdb.
current_code_name
()[source]¶ Displays name of the code object of the current frame
-
powerline.segments.pdb.
current_context
()[source]¶ Displays currently executed context name
This is similar to
current_code_name()
, but gives more details.Currently it only gives module file name if code_name happens to be
<module>
.
Shell segments¶
-
powerline.segments.shell.
continuation
(renames={}, right_align=False, omit_cmdsubst=True)[source]¶ Display parser state.
Parameters: - omit_cmdsubst (bool) – Do not display cmdsubst parser state if it is the last one.
- right_align (bool) – Align to the right.
- renames (dict) – Rename states:
{old_name : new_name}
. Ifnew_name
isNone
then given state is not displayed.
Highlight groups used:
continuation
,continuation:current
.
-
powerline.segments.shell.
cwd
(ellipsis=u'...', use_path_separator=False, dir_limit_depth=None, dir_shorten_len=None, use_shortened_path=True)¶ Return the current working directory.
Returns a segment list to create a breadcrumb-like effect.
Parameters: - dir_shorten_len (int) – shorten parent directory names to this length (e.g.
/long/path/to/powerline
→/l/p/t/powerline
) - dir_limit_depth (int) – limit directory depth to this number (e.g.
/long/path/to/powerline
→⋯/to/powerline
) - use_path_separator (bool) – Use path separator in place of soft divider.
- use_shortened_path (bool) – Use path from shortened_path
--renderer-arg
argument. If this argument is presentshorten_home
argument is ignored. - shorten_home (bool) – Shorten home directory to
~
. - ellipsis (str) – Specifies what to use in place of omitted directories. Use None to not show this subsegment at all.
Divider highlight group used:
cwd:divider
.Highlight groups used:
cwd:current_folder
orcwd
. It is recommended to define all highlight groups.- dir_shorten_len (int) – shorten parent directory names to this length (e.g.
-
powerline.segments.shell.
jobnum
(show_zero=False)[source]¶ Return the number of jobs.
Parameters: show_zero (bool) – If False (default) shows nothing if there are no jobs. Otherwise shows zero for no jobs.
-
powerline.segments.shell.
last_pipe_status
()[source]¶ Return last pipe status.
Highlight groups used:
exit_fail
,exit_success
-
powerline.segments.shell.
last_status
()[source]¶ Return last exit code.
Highlight groups used:
exit_fail
-
powerline.segments.shell.
mode
(default=None, override={u'vicmd': u'COMMND', u'viins': u'INSERT'})[source]¶ Return the current mode.
Parameters: - override (dict) – dict for overriding mode strings.
- default (str) – If current mode is equal to this string then this segment will not get
displayed. If not specified the value is taken from
$POWERLINE_DEFAULT_MODE
variable. This variable is set by zsh bindings for any mode that does not start fromvi
.
Tmux segments¶
Vim segments¶
-
powerline.segments.vim.
branch
(ignore_statuses=(), status_colors=False)¶ Return the current working branch.
Parameters: - status_colors (bool) – Determines whether repository status will be used to determine highlighting. Default: False.
- ignore_statuses (bool) – List of statuses which will not result in repo being marked as dirty. Most
useful is setting this option to
["U"]
: this will ignore repository which has just untracked files (i.e. repository with modified, deleted or removed files will be marked as dirty, while just untracked files will make segment show clean repository). Only applicable ifstatus_colors
option is True.
Highlight groups used:
branch_clean
,branch_dirty
,branch
.Divider highlight group used:
branch:divider
.
-
powerline.segments.vim.
bufnr
(show_current=True)[source]¶ Show buffer number
Parameters: show_current (bool) – If False do not show current window number.
-
powerline.segments.vim.
csv_col_current
(name_format=u' ({column_name:.15})', display_name=u'auto')[source]¶ Display CSV column number and column name
Requires filetype to be set to
csv
.Parameters: - or str name (bool) – May be
True
,False
and"auto"
. In the first case value from the first raw will always be displayed. In the second case it will never be displayed. In thi last casecsv.Sniffer().has_header()
will be used to detect whether current file contains header in the first column. - name_format (str) – String used to format column name (in case
display_name
is set toTrue
or"auto"
). Acceptscolumn_name
keyword argument.
Highlight groups used:
csv:column_number
orcsv
,csv:column_name
orcsv
.- or str name (bool) – May be
-
powerline.segments.vim.
file_directory
(shorten_home=False, shorten_cwd=True, shorten_user=True, remove_scheme=True)[source]¶ Return file directory (head component of the file path).
Parameters: - remove_scheme (bool) – Remove scheme part from the segment name, if present. See documentation of file_scheme segment for the description of what scheme is. Also removes the colon.
- shorten_user (bool) – Shorten
$HOME
directory to~/
. Does not work for files with scheme. - shorten_cwd (bool) – Shorten current directory to
./
. Does not work for files with scheme present. - shorten_home (bool) – Shorten all directories in
/home/
to~user/
instead of/home/user/
. Does not work for files with scheme present.
-
powerline.segments.vim.
file_encoding
(segment_info)[source]¶ Return file encoding/character set.
Returns: file encoding/character set or None if unknown or missing file encoding Divider highlight group used:
background:divider
.
-
powerline.segments.vim.
file_format
(segment_info)[source]¶ Return file format (i.e. line ending type).
Returns: file format or None if unknown or missing file format Divider highlight group used:
background:divider
.
-
powerline.segments.vim.
file_name
(no_file_text=u'[No file]', display_no_file=False)[source]¶ Return file name (tail component of the file path).
Parameters: - display_no_file (bool) – display a string if the buffer is missing a file name
- no_file_text (str) – the string to display if the buffer is missing a file name
Highlight groups used:
file_name_no_file
orfile_name
,file_name
.
-
powerline.segments.vim.
file_scheme
()[source]¶ Return the protocol part of the file.
Protocol is the part of the full filename just before the colon which starts with a latin letter and contains only latin letters, digits, plus, period or hyphen (refer to RFC3986 for the description of URI scheme). If there is no such a thing
None
is returned, effectively removing segment.Note
Segment will not check whether there is
//
just after the colon or if there is at least one slash after the scheme. Reason: it is not always present. E.g. when opening file inside a zip archive file name will look likezipfile:/path/to/archive.zip::file.txt
.file_scheme
segment will catchzipfile
part here.
-
powerline.segments.vim.
file_size
(si_prefix=False, suffix=u'B')[source]¶ Return file size in &encoding.
Parameters: - suffix (str) – string appended to the file size
- si_prefix (bool) – use SI prefix, e.g. MB instead of MiB
Returns: file size or None if the file isn’t saved or if the size is too big to fit in a number
-
powerline.segments.vim.
file_type
(segment_info)[source]¶ Return file type.
Returns: file type or None if unknown file type Divider highlight group used:
background:divider
.
-
powerline.segments.vim.
file_vcs_status
()[source]¶ Return the VCS status for this buffer.
Highlight groups used:
file_vcs_status
.
-
powerline.segments.vim.
line_percent
(gradient=False)[source]¶ Return the cursor position in the file as a percentage.
Parameters: gradient (bool) – highlight the percentage with a color gradient (by default a green to red gradient) Highlight groups used:
line_percent_gradient
(gradient),line_percent
.
-
powerline.segments.vim.
mode
(override=None)[source]¶ Return the current vim mode.
If mode (returned by
mode()
VimL function, see:h mode()
in Vim) consists of multiple characters and necessary mode is not known to powerline then it will fall back to mode with last character(s) ignored.Parameters: override (dict) – dict for overriding default mode strings, e.g. { 'n': 'NORM' }
-
powerline.segments.vim.
modified_buffers
(join_str=u', ', text=u'+ ')[source]¶ Return a comma-separated list of modified buffers.
Parameters: - text (str) – text to display before the modified buffer list
- join_str (str) – string to use for joining the modified buffer list
-
powerline.segments.vim.
modified_indicator
(text=u'+')[source]¶ Return a file modified indicator.
Parameters: text (string) – text to display if the current buffer is modified
-
powerline.segments.vim.
paste_indicator
(text=u'PASTE')[source]¶ Return a paste mode indicator.
Parameters: text (string) – text to display if paste mode is enabled
-
powerline.segments.vim.
position
(gradient=False, position_strings={u'top': u'Top', u'all': u'All', u'bottom': u'Bot'})[source]¶ Return the position of the current view in the file as a percentage.
Parameters: - position_strings (dict) – dict for translation of the position strings, e.g.
{"top":"Oben", "bottom":"Unten", "all":"Alles"}
- gradient (bool) – highlight the percentage with a color gradient (by default a green to red gradient)
Highlight groups used:
position_gradient
(gradient),position
.- position_strings (dict) – dict for translation of the position strings, e.g.
-
powerline.segments.vim.
readonly_indicator
(text=u'RO')[source]¶ Return a read-only indicator.
Parameters: text (string) – text to display if the current buffer is read-only
-
powerline.segments.vim.
stash
()¶ Return the number of stashes in the current working branch.
Highlight groups used:
stash
.
-
powerline.segments.vim.
tab
(end=False)[source]¶ Mark start of the clickable region for tabpage
Parameters: end (bool) – In place of starting region for the current tab end it. No highlight groups are used (literal segment).
-
powerline.segments.vim.
tab_modified_indicator
(text=u'+')[source]¶ Return a file modified indicator for tabpages.
Parameters: text (string) – text to display if any buffer in the current tab is modified Highlight groups used:
tab_modified_indicator
ormodified_indicator
.
-
powerline.segments.vim.
tabnr
(show_current=True)[source]¶ Show tabpage number
Parameters: show_current (bool) – If False do not show current tabpage number. This is default because tabnr is by default only present in tabline.
-
powerline.segments.vim.
trailing_whitespace
()[source]¶ Return the line number for trailing whitespaces
It is advised not to use this segment in insert mode: in Insert mode it will iterate over all lines in buffer each time you happen to type a character which may cause lags. It will also show you whitespace warning each time you happen to type space.
Highlight groups used:
trailing_whitespace
orwarning
.
-
powerline.segments.vim.
virtcol_current
(gradient=True)[source]¶ Return current visual column with concealed characters ingored
Parameters: gradient (bool) – Determines whether it should show textwidth-based gradient (gradient level is virtcol * 100 / textwidth
).Highlight groups used:
virtcol_current_gradient
(gradient),virtcol_current
orcol_current
.
-
powerline.segments.vim.
visual_range
(V_text=u'L:{rows}', v_text_multiline=u'L:{rows}', v_text_oneline=u'C:{vcols}', CTRL_V_text=u'{rows} x {vcols}')[source]¶ Return the current visual selection range.
Parameters: - CTRL_V_text (str) – Text to display when in block visual or select mode.
- v_text_oneline (str) – Text to display when in charaterwise visual or select mode, assuming selection occupies only one line.
- v_text_multiline (str) – Text to display when in charaterwise visual or select mode, assuming selection occupies more then one line.
- V_text (str) – Text to display when in linewise visual or select mode.
All texts are format strings which are passed the following parameters:
Parameter Description sline Line number of the first line of the selection eline Line number of the last line of the selection scol Column number of the first character of the selection ecol Column number of the last character of the selection svcol Virtual column number of the first character of the selection secol Virtual column number of the last character of the selection rows Number of lines in the selection cols Number of columns in the selection vcols Number of virtual columns in the selection
-
powerline.segments.vim.
window_title
()[source]¶ Return the window title.
This currently looks at the
quickfix_title
window variable, which is used by Syntastic and Vim itself.It is used in the quickfix theme.
-
powerline.segments.vim.
winnr
(show_current=True)[source]¶ Show window number
Parameters: show_current (bool) – If False do not show current window number.
-
powerline.segments.vim.plugin.ale.
ale
(warn_format=u'WARN: ln {first_line} ({num}) ', err_format=u'ERR: ln {first_line} ({num}) ')[source]¶ Show whether ALE has found any errors or warnings
Parameters: - err_format (str) – Format string for errors.
- warn_format (str) – Format string for warnings.
Highlight groups used:
ale:warning
orwarning
,ale:error
orerror
.
-
powerline.segments.vim.plugin.syntastic.
syntastic
(warn_format=u'WARN: \ue0a1 {first_line} ({num}) ', err_format=u'ERR: \ue0a1 {first_line} ({num}) ')[source]¶ Show whether syntastic has found any errors or warnings
Parameters: - err_format (str) – Format string for errors.
- warn_format (str) – Format string for warnings.
Highlight groups used:
syntastic:warning
orwarning
,syntastic:error
orerror
.
-
powerline.segments.vim.plugin.commandt.
finder
()[source]¶ Display Command-T finder name
Requires $command_t.active_finder and methods (code above may monkey-patch $command_t to add them). All Command-T finders have
CommandT::
module prefix, but it is stripped out (actually, anyCommandT::
substring will be stripped out).Highlight groups used:
commandt:finder
.
-
powerline.segments.vim.plugin.commandt.
path
()[source]¶ Display path used by Command-T
Requires $command_t.active_finder and .path methods (code above may monkey-patch $command_t to add them).
$command_t.active_finder is required in order to omit displaying path for finders
MRUBufferFinder
,BufferFinder
,TagFinder
andJumpFinder
(pretty much any finder, exceptFileFinder
).Highlight groups used:
commandt:path
.
-
powerline.segments.vim.plugin.tagbar.
current_tag
(flags=u's')[source]¶ Return tag that is near the cursor.
Parameters: flags (str) – Specifies additional properties of the displayed tag. Supported values:
- s - display complete signature
- f - display the full hierarchy of the tag
- p - display the raw prototype
More info in the official documentation (search for “tagbar#currenttag”).
-
powerline.segments.vim.plugin.capslock.
capslock_indicator
(text=u'CAPS')[source]¶ Shows the indicator if tpope/vim-capslock plugin is enabled
Note
In the current state plugin automatically disables itself when leaving insert mode. So trying to use this segment not in insert or replace modes is useless.
Parameters: text (str) – String to show when software capslock presented by this plugin is active.
Lister reference¶
Listers are special segment collections which allow to show some list of
segments for each entity in the list of entities (multiply their segments list
by a list of entities). E.g. powerline.listers.vim.tablister
presented with
powerline.segments.vim.tabnr
and ….file_name
as segments will emit
segments with buffer names and tabpage numbers for each tabpage shown by vim.
Listers appear in configuration as irregular segments having segment_list
as
their type and segments
key with a list of segments (a bit more details in
Themes section of configuration reference).
More information in Writing listers section.
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
andbufnr
keys set to buffer-specific ones,window
,winnr
andwindow_id
keys set to None.Adds one of
buf:
,buf_nc:
,buf_mod:
, orbuf_nc_mod
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
andbufnr
keys set to tab-local ones and additionaltabpage
andtabnr
keys.Adds either
tab:
ortab_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.
Pdb listers¶
-
powerline.listers.pdb.
frame_lister
(maxframes=3, full_stack=False)[source]¶ List all frames in segment_info format
Parameters: - full_stack (bool) – If true, then all frames in the stack are listed. Normally N first frames are discarded where N is a number of frames present at the first invocation of the prompt minus one.
- maxframes (int) – Maximum number of frames to display.
i3wm listers¶
-
powerline.listers.i3wm.
workspace_lister
(output=None, only_show=None)[source]¶ List all workspaces in segment_info format
Sets the segment info values of
workspace
andoutput
to the name of the i3 workspace and thexrandr
output respectively and the keys"visible"
,"urgent"
and"focused"
to a boolean indicating these states.Parameters: - only_show (list) – Specifies which workspaces to list. Valid entries are
"visible"
,"urgent"
and"focused"
. If omitted ornull
all workspaces are listed. - output (str) – May be set to the name of an X output. If specified, only workspaces
on that output are listed. Overrides automatic output detection by
the lemonbar renderer and bindings. Set to
false
to force all workspaces to be shown.
- only_show (list) – Specifies which workspaces to list. Valid entries are
Selector functions¶
Selector functions are functions that return True
or False
depending on
application state. They are used for exclude_function and include_function
segment options.
Local configuration overrides¶
Depending on the application used it is possible to override configuration. Here is the list:
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
- Dictionary mapping theme names to theme overrides, recursively merged with
contents of
powerline/themes/vim/key.json
. Note that this way some value (e.g. segment) in a list cannot be redefined, 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.
g:powerline_use_var_handler
This variable may be set to either 0 or 1. If it is set to 1 then Vim will save log in
g:powerline_log_messages
variable in addition to whatever was configured in log_* options. Level is always log_level, same for format.Warning
This variable is deprecated. Use log_file option in conjunction with
powerline.vim.VimVarHandler
class and Vim config overrides variable. Using this is also the only variant to make saving into the environment variable the only place where log is saved or save into different variable.
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-override=KEY.NESTED_KEY=VALUE
Overrides options from
powerline/config.json
.KEY.KEY2.KEY3=VALUE
is a shortcut forKEY={"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-override=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
.
Warning
Such overrides are suggested for testing purposes only. Use Environment variables overrides for other purposes.
Environment variables overrides¶
All bindings that use POWERLINE_COMMAND
environment variable support taking
overrides from environment variables. In this case overrides should look like
the following:
OVERRIDE='key1.key2.key3=value;key4.key5={"value":1};key6=true;key1.key7=10'
. This will be parsed into
{
"key1": {
"key2": {
"key3": "value"
},
"key7": 10,
},
"key4": {
"key5": {
"value": 1,
},
},
"key6": True,
}
. Rules:
- Environment variable must form a semicolon-separated list of key-value pairs:
key=value;key2=value2
. - Keys are always dot-separated strings that must not contain equals sign (as
well as semicolon) or start with an underscore. They are interpreted
literally and create a nested set of dictionaries:
k1.k2.k3
creates{"k1":{"k2":{}}}
and inside the innermost dictionary last key (k3
in the example) is contained with its value. - Value may be empty in which case they are interpreted as an order to remove
some value:
k1.k2=
will form{"k1":{"k2":REMOVE_THIS_KEY}}
nested dictionary wherek2
value is a special value that tells dictionary-merging function to removek2
rather then replace it with something. - Value may be a JSON strings like
{"a":1}
(JSON dictionary),["a",1]
(JSON list),1
or-1
(JSON number),"abc"
(JSON string) ortrue
,false
andnull
(JSON boolean objects andNull
object from JSON). General rule is that anything starting with a digit (U+0030 till U+0039, inclusive), a hyphenminus (U+002D), a quotation mark (U+0022), a left curly bracket (U+007B) or a left square bracket (U+005B) is considered to be some JSON object, same for exact valuestrue
,false
andnull
. - Any other value is considered to be literal string:
k1=foo:bar
parses to{"k1": "foo:bar"}
.
The following environment variables may be used for overrides according to the above rules:
POWERLINE_CONFIG_OVERRIDES
- Overrides values from
powerline/config.json
. POWERLINE_THEME_OVERRIDES
Overrides values from
powerline/themes/ext/key.json
. Top-level key is treated as a name of the theme for which overrides are used: e.g. to disable cwd segment defined inpowerline/themes/shell/default.json
one needs to use:POWERLINE_THEME_OVERRIDES=default.segment_data.cwd.display=false
Additionally one environment variable is a usual colon-separated list of
directories: POWERLINE_CONFIG_PATHS
. This one defines paths which will be
searched for configuration. Empty paths in POWERLINE_CONFIG_PATHS
are
ignored.
Note
Overrides from environment variables have lower priority then Powerline script overrides. Latter are suggested for tests only.
Zsh/zpython overrides¶
Here overrides are controlled by similarly to the powerline script, but values are taken from zsh variables. Environment variable overrides are also supported: if variable is a string this variant is used.
POWERLINE_CONFIG_OVERRIDES
- Overrides options from
powerline/config.json
. Should be a zsh associative array with keys equal toKEY.NESTED_KEY
and values being JSON strings. PairKEY.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_OVERRIDES
- Overrides options from
powerline/themes/shell/*.json
. Should be a zsh associative array with keys equal toTHEME_NAME.KEY.NESTED_KEY
and values being JSON strings. Is processed like the abovePOWERLINE_CONFIG_OVERRIDES
, but only subdictionaries forTHEME_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 variable without is set without quotes:
POWERLINE_CONFIG_PATHS=( ~/example )
. In addition to arrays usual colon-separated “array” string can be used:POWERLINE_CONFIG_PATHS=$HOME/path1:$HOME/path2
.
Ipython overrides¶
Ipython overrides depend on ipython version. Before ipython-0.11 additional
keyword arguments should be passed to setup() function. After ipython-0.11
c.Powerline.KEY
should be used. 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. config_paths
- Sets directories where configuration should be read from. If present, no
default locations are searched for configuration. No expansions are
performed thus paths starting with
~/
cannot be used: useos.path.expanduser()
.
Prompt command¶
In addition to the above configuration options $POWERLINE_COMMAND
environment variable can be used to tell shell or tmux to use specific powerline
implementation and $POWERLINE_CONFIG_COMMAND
to tell zsh or tmux where
powerline-config
script is located. This is mostly useful for putting
powerline into different directory.
Note
$POWERLINE_COMMAND
is always treated as one path in shell bindings, so
path with spaces in it may be used. To specify additional arguments one may
use $POWERLINE_COMMAND_ARGS
, but note that this variable exists for
testing purposes only and may be removed. One should use Environment
variable overrides instead.
To disable prompt in shell, but still have tmux support or to disable tmux
support environment variables $POWERLINE_NO_{SHELL}_PROMPT
and
$POWERLINE_NO_{SHELL}_TMUX_SUPPORT
can be used (substitute {SHELL}
with
the name of the shell (all-caps) that should be affected (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.
In order to keep shell prompt, but avoid launching Python twice to get unused
above lines in tcsh $POWERLINE_NO_TCSH_ABOVE
or
$POWERLINE_NO_SHELL_ABOVE
variable should be set.
In order to remove additional space from the end of the right prompt in fish
that was added in order to support multiline prompt $POWERLINE_NO_FISH_ABOVE
or $POWERLINE_NO_SHELL_ABOVE
variable should be set.
PDB overrides¶
Like shell bindings PDB bindings take overrides from environment variables.
Developer guide¶
Writing segments¶
Each powerline segment is a callable object. It is supposed to be either
a Python function or powerline.segments.Segment
class. As a callable
object it should receive the following arguments:
Note
All received arguments are keyword arguments.
pl
- A
powerline.PowerlineLogger
instance. It must be used every time something needs to be logged. segment_info
A dictionary. It is only received if callable has
powerline_requires_segment_info
attribute.Refer to segment_info detailed description for further details.
create_watcher
- Function that will create filesystem watcher once called. Which watcher will be created exactly is controlled by watcher configuration option.
And also any other argument(s) specified by user in args key (no additional arguments by default).
Note
For powerline-lint to work properly the following things may be needed:
- If segment is a
powerline.segments.Segment
instance and used arguments are scattered over multiple methodspowerline.segments.Segment.argspecobjs()
should be overridden in subclass to tell powerline-lint which objects should be inspected for arguments. - If segment takes some arguments that are never listed, but accessed via
kwargs.get()
or previous function cannot be used for whatever reasonpowerline.segments.Segment.additional_args()
should be overridden in subclass. - If user is expected to use one name for
multiple segments which cannot be linked to the segment function
automatically by powerline-lint (e.g. because there are no instances of
the segments in question in the default configuration)
powerline.lint.checks.register_common_name()
function should be used.
Object representing segment may have the following attributes used by powerline:
powerline_requires_segment_info
- This attribute controls whether segment will receive
segment_info
argument: if it is present argument will be received. powerline_requires_filesystem_watcher
- This attribute controls whether segment will receive
create_watcher
argument: if it is present argument will be received. powerline_segment_datas
- This attribute must be a dictionary containing
top_theme: segment_data
mapping wheretop_theme
is any theme name (it is expected that all of the names from top-level themes list are present) andsegment_data
is a dictionary like the one that is contained inside segment_data dictionary in configuration. This attribute should be used to specify default theme-specific values for third-party segments: powerline theme-specific values go directly to top-level themes.
startup
This attribute must be a callable which accepts the following keyword arguments:
pl
:powerline.PowerlineLogger
instance which is to be used for logging.shutdown_event
:Event
object which will be set when powerline will be shut down.- Any arguments found in user configuration for the given segment (i.e. args key).
This function is called at powerline startup when using long-running processes (e.g. powerline in vim, in zsh with libzpython, in ipython or in powerline daemon) and not called when
powerline-render
executable is used (more specific: whenpowerline.Powerline
constructor received truerun_once
argument).
shutdown
This attribute must be a callable that accepts no arguments and shuts down threads and frees any other resources allocated in
startup
method of the segment in question.This function is not called when
startup
method is not called.
expand
This attribute must be a callable that accepts the following keyword arguments:
pl
:powerline.PowerlineLogger
instance which is to be used for logging.amount
: integer number representing amount of display cells result must occupy.Warning
“Amount of display cells” is not number of Unicode codepoints, string length, or byte count. It is suggested that this function should look something like
return (' ' * amount) + segment['contents']
where' '
may be replaced with anything that is known to occupy exactly one display cell.segment
: segment dictionary.Any arguments found in user configuration for the given segment (i.e. args key).
It must return new value of contents key.
truncate
Like expand function, but for truncating segments. Here
amount
means the number of display cells which must be freed.This function is called for all segments before powerline starts purging them to free space.
This callable object should may return either a string (unicode
in Python2
or str
in Python3, not str
in Python2 or bytes
in Python3) object
or a list of dictionaries. String object is a short form of the following return
value:
[{
'contents': original_return,
'highlight_groups': [segment_name],
}]
Returned list is a list of segments treated independently, except for draw_inner_divider key.
All keys in segments returned by the function override those obtained from configuration and have the same meaning.
Detailed description of used dictionary keys:
contents
- Text displayed by segment. Should be a
unicode
(Python2) orstr
(Python3) instance. literal_contents
Text that needs to be output literally (i.e. without passing through
powerline.renderer.strwidth()
to determine length, throughpowerline.renderer.escape()
to escape special characters and throughpowerline.renderer.hl()
to highlight it). Should be a tuple(contents_length, contents)
wherecontents_length
is an integer andcontents
is aunicode
(Python2) orstr
(Python3) instance.If this key is present and its second value is true then other contents keys (contents, after, before) will be ignored.
Note
If target is inclusion of the segment in powerline upstream all segment functions that output only subsegments with
literal_contents
key must contain the following string in documentation:No highlight groups are used (literal segment).
String must be present on the separate line.
draw_hard_divider
,draw_soft_divider
,draw_inner_divider
- Determines whether given divider should be drawn. All have the same meaning as the similar keys in configuration (draw_inner_divider).
highlight_groups
Determines segment highlighting. Refer to themes documentation for more details.
Defaults to the name of the segment.
Note
If target is inclusion of the segment in powerline upstream all used highlighting groups must be specified in the segment documentation in the form:
Highlight groups used: ``g1``[ or ``g2``]*[, ``g3`` (gradient)[ or ``g4``]*]*.
I.e. use:
Highlight groups used: ``foo_gradient`` (gradient) or ``foo``, ``bar``.
to specify that the segment uses either
foo_gradient
group orfoo
group andbar
group meaning thatpowerline-lint
will check that at least one of the first two groups is defined (and iffoo_gradient
is defined it must use at least one gradient color) and third group is defined as well.All groups must be specified on one line.
divider_highlight_group
Determines segment divider highlight group. Only applicable for soft dividers: colors for hard dividers are determined by colors of adjacent segments.
Note
If target is inclusion of the segment in powerline upstream used divider highlight group must be specified in the segment documentation in the form:
Divider highlight group used: ``group``. This text must not wrap and all divider highlight group names are supposed to end with ``:divider``: e.g. ``cwd:divider``.
gradient_level
First and the only key that may not be specified in user configuration. It determines which color should be used for this segment when one of the highlighting groups specified by highlight_groups was defined to use the color gradient.
This key may have any value from 0 to 100 inclusive, value is supposed to be an
int
orfloat
instance.No error occurs if segment has this key, but no used highlight groups use gradient color.
_*
- Keys starting with underscore are reserved for powerline and must not be returned.
__*
- Keys starting with two underscores are reserved for the segment functions, specifically for expand function.
Segment dictionary¶
Segment dictionary contains the following keys:
All keys returned by segment function (if it was used).
All of the following keys:
name
Segment name: value of the name key or function name (last component of the function key). May be
None
.type
Segment type. Always represents actual type and is never
None
.highlight_groups
,divider_highlight_group
Used highlight groups. May be
None
.highlight_group_prefix
If this key is present then given prefix will be prepended to each highlight group (both regular and divider) used by this segment in a form
{prefix}:{group}
(note the colon). This key is mostly useful for segment listers.
before
,after
Value of before or after configuration options. May be
None
as well as an empty string.contents_func
Function used to get segment contents. May be
None
.
contents
Actual segment contents, excluding dividers and before/after. May be
None
.priority
Segment priority. May be
None
for no priority (such segments are always shown).draw_soft_divider
,draw_hard_divider
,draw_inner_divider
side
Segment side:
right
orleft
.display_condition
Contains function that takes three position parameters:
powerline.PowerlineLogger
instance, segment_info dictionary and current mode and returns eitherTrue
orFalse
to indicate whether particular segment should be processed.This key is constructed based on exclude_/include_modes keys and exclude_/include_function keys.
width
,align
Width and align options. May be
None
.expand
,truncate
Partially applied expand or truncate function. Accepts
pl
,amount
andsegment
positional parameters, keyword parameters from args key were applied.startup
Partially applied startup function. Accepts
pl
andshutdown_event
positional parameters, keyword parameters from args key were applied.shutdown
Shutdown function. Accepts no argument.
Segments layout¶
Powerline segments are all located in one of the powerline.segments
submodules. For extension-specific segments powerline.segments.{ext}
module
should be used (e.g. powerline.segments.shell
), for extension-agnostic there
is powerline.segments.common
.
Plugin-specific segments (currently only those that are specific to vim plugins)
should live in powerline.segments.{ext}.plugin.{plugin_name}
: e.g.
powerline.segments.vim.plugin.gundo
.
Segment information used in various extensions¶
Each segment_info
value should be a dictionary with at least the following
keys:
environ
Current environment, may be an alias to
os.environ
. Is guaranteed to have__getitem__
andget
methods and nothing more.Warning
os.environ
must not ever be used:- If segment is run in the daemon this way it will get daemon’s environment which is not correct.
- If segment is run in Vim or in zsh with libzpython
os.environ
will contain Vim or zsh environ at the moment Python interpreter was loaded.
getcwd
- Function that returns current working directory being called with no
arguments.
os.getcwd
must not be used for the same reasons the use ofos.environ
is forbidden, except that current working directory is valid in Vim and zsh (but not in daemon). home
- Current home directory. May be false.
Vim¶
Vim segment_info
argument is a dictionary with the following keys:
window
vim.Window
object.vim.current.window
orvim.windows[number - 1]
may be used to obtain such object. May be a false object, in which case any of this object’s properties must not be used.winnr
- Window number. Same as
segment_info['window'].number
assuming Vim is new enough forvim.Window
object to havenumber
attribute. window_id
- Internal powerline window id, unique for each newly created window. It is safe to assume that this ID is hashable and supports equality comparison, but no other assumptions about it should be used. Currently uses integer numbers incremented each time window is created.
buffer
vim.Buffer
object. One may be obtained usingvim.current.buffer
,segment_info['window'].buffer
orvim.buffers[some_number]
. Note that in the latter case depending on vim versionsome_number
may bebufnr
or the internal Vim buffer index which is not buffer number. For this reason to getvim.Buffer
object other then stored insegment_info
dictionary iteration overvim.buffers
and checking theirnumber
attributes should be performed.bufnr
- Buffer number.
tabpage
vim.Tabpage
object. One may be obtained usingvim.current.tabpage
orvim.tabpages[number - 1]
. May be a false object, in which case no object’s properties can be used.tabnr
- Tabpage number.
mode
- Current mode.
encoding
- Value of
&encoding
from the time when powerline was initialized. It should be used to convert return values.
Note
Segment generally should not assume that it is run for the current window,
current buffer or current tabpage. “Current window” and “current buffer”
restrictions may be ignored if window_cached
decorator is used, “current
tabpage” restriction may be safely ignored if segment is not supposed to be
used in tabline.
Warning
Powerline is being tested with vim-7.0.112 (some minor sanity check) and
latest Vim. This means that most of the functionality like
vim.Window.number
, vim.*.vars
, vim.*.options
or even dir(vim
object)
should be avoided in segments that want to be included in the
upstream.
Shell¶
args
Parsed shell arguments: a
argparse.Namespace
object. Check outpowerline-render --help
for the list of all available arguments. Currently it is expected to contain at least the following attributes:last_exit_code
- Exit code returned by last shell command. Is either one integer,
sig{name}
orsig{name}+core
(latter two are only seen inrc
shell). last_pipe_status
- List of exit codes returned by last programs in the pipe or some false
object. Only available in
zsh
andrc
. Is a list of either integers,sig{name}
orsig{name}+core
(latter two are only seen inrc
shell). jobnum
- Number of background jobs.
renderer_arg
Dictionary containing some keys that are additional arguments used by shell bindings. This attribute must not be used directly: all arguments from this dictionary are merged with
segment_info
dictionary. Known to have at least the following keys:client_id
Identifier unique to one shell instance. Is used to record instance state by powerline daemon. In tmux this is the same as pane_id.
It is not guaranteed that existing client ID will not be retaken when old shell with this ID quit: usually process PID is used as a client ID.
It is also not guaranteed that client ID will be process PID, number or something else at all. It is guaranteed though that client ID will be some hashable object which supports equality comparison.
local_theme
- Local theme that will be used by shell. One should not rely on the existence of this key.
pane_id
- Identifier unique to each tmux pane. Is always an integer, optional.
Obtained by using
tmux display -p '#D'
, then all leading spaces and per cent signs are stripped and the result is converted into an integer.
Other keys, if any, are specific to segments.
Ipython¶
ipython
Some object which has
prompt_count
attribute. Currently it is guaranteed to have only this attribute.Attribute
prompt_count
contains the so-called “history count” (equivalent to\N
inin_template
).
Pdb¶
pdb
- Currently active
pdb.Pdb
instance. curframe
- Frame which will be run next. Note: due to the existence of
powerline.listers.pdb.frame_lister()
one must not usesegment_info['pdb'].curframe
. initial_stack_length
- Equal to the length of
pdb.Pdb.stack
at the first invocation of the prompt decremented by one.
i3wm¶
mode
- Currently active i3 mode (as a string).
output
xrandr
output name currently drawing to. Currently only available in lemonbar bindings.workspace
- dictionary containing the workspace name under the key
"name"
and boolean values for the"visible"
,"urgent"
and"focused"
keys, indicating the state of the workspace. Currently only provided by thepowerline.listers.i3wm.workspace_lister()
lister.
Segment class¶
-
class
powerline.segments.
Segment
[source]¶ Base class for any segment that is not a function
Required for powerline.lint.inspect to work properly: it defines methods for omitting existing or adding new arguments.
Note
Until python-3.4
inspect.getargspec
does not support querying callable classes for arguments of their__call__
method, requiring to use this method directly (i.e. before 3.4 you should writegetargspec(obj.__call__)
in place ofgetargspec(obj)
).-
static
additional_args
()[source]¶ Returns a list of (additional argument name[, default value]) tuples.
-
static
PowerlineLogger class¶
-
class
powerline.
PowerlineLogger
(use_daemon_threads, logger, ext)[source]¶ Proxy class for logging.Logger instance
It emits messages in format
{ext}:{prefix}:{message}
where{ext}
- is a used powerline extension (e.g. “vim”, “shell”, “ipython”).
{prefix}
- is a local prefix, usually a segment name.
{message}
- is the original message passed to one of the logging methods.
Each of the methods (
critical
,exception
,info
,error
,warn
,debug
) expects to receive message in anstr.format
format, not in printf-like format.Log is saved to the location specified by user.
Writing listers¶
Listers provide a way to show some segments multiple times: once per each entity (buffer, tabpage, etc) lister knows. They are functions which receive the following arguments:
pl
- A
powerline.PowerlineLogger
class instance. It must be used for logging. segment_info
Base segment info dictionary. Lister function or class must have
powerline_requires_segment_info
to receive this argument.Warning
Listers are close to useless if they do not have access to this argument.
Refer to segment_info detailed description for further details.
draw_inner_divider
- If False (default) soft dividers between segments in the listed group will
not be drawn regardless of actual segment settings. If True they will be
drawn, again regardless of actual segment settings. Set it to
None
in order to respect segment settings.
And also any other argument(s) specified by user in args key (no additional arguments by default).
Listers must return a sequence of pairs. First item in the pair must contain
a segment_info
dictionary specific to one of the listed entities.
Second item must contain another dictionary: it will be used to modify the resulting segment. In addition to usual keys that describe segment the following keys may be present (it is advised that only the following keys will be used):
priority_multiplier
- Value (usually a
float
) used to multiply segment priority. It is useful for finer-grained controlling which segments disappear first: e.g. when listing tab pages make first disappear directory names of the tabpages which are most far away from current tabpage, then (when all directory names disappeared) buffer names. Check out existing listers implementation inpowerline/listers/vim.py
.
Local themes¶
From the user point of view local themes are the regular themes with a specific scope where they are applied (i.e. specific vim window or specific kind of prompt). Used themes are defined in local_themes key.
Vim local themes¶
Vim is the only available extension that has a wide variaty of options for local themes. It is the only extension where local theme key refers to a function as described in local_themes value documentation.
This function always takes a single value named matcher_info
which is the
same dictionary as segment_info dictionary. Unlike
segments it takes this single argument as a positional argument, not as
a keyword one.
Matcher function should return a boolean value: True
if theme applies for
the given matcher_info
dictionary or False
if it is not. When one of the
matcher functions returns True
powerline takes the corresponding theme at
uses it for the given window. Matchers are not tested in any particular order.
In addition to local_themes configuration key
developer of some plugin which wishes to support powerline without including his
code in powerline tree may use
powerline.vim.VimPowerline.add_local_theme()
method. It accepts two
arguments: matcher name (same as in local_themes) and dictionary with theme. This dictionary is merged
with top theme and
powerline/themes/vim/__main__.json
. Note that if user already specified
the matcher in his configuration file KeyError
is raised.
Other local themes¶
Except for Vim only IPython and shells have local themes. Unlike Vim these themes are names with no special meaning (they do not refer to or cause loading of any Python functions):
Extension | Theme name | Description |
Shell | continuation | Shown for unfinished command (unclosed quote, unfinished cycle). |
select | Shown for select command available in some shells. |
|
IPython | in2 | Continuation prompt: shown for unfinished (multiline) expression, unfinished class or function definition. |
out | Displayed before the result. | |
rewrite | Displayed before the actually executed code when
autorewrite IPython feature is enabled. |
Creating new powerline extension¶
Powerline extension is a code that tells powerline how to highlight and display segments in some set of applications. Specifically this means
Creating a
powerline.Powerline
subclass that knows how to obtain local configuration overrides. It also knows how to load local themes, but not when to apply them.Instance of this class is the only instance that interacts directly with bindings code, so it has a proxy
powerline.Powerline.render()
andpowerline.Powerline.shutdown()
methods and other methods which may be useful for bindings.This subclass must be placed directly in
powerline
directory (e.g. inpowerline/vim.py
) and named likeVimPowerline
(version of the file name without directory and extension and first capital letter +Powerline
). There is no technical reason for naming classes like this.Creating a
powerline.renderer.Renderer
subclass that knows how to highlight a segment or reset highlighting to the default value (only makes sense in prompts). It is also responsible for selecting local themes and computing text width.This subclass must be placed directly in
powerline/renderers
directory (for powerline extensions developed for a set of applications usepowerline/renderers/ext/*.py
) and named likeExtRenderer
orAppPromptRenderer
. For technical reasons the class itself must be referenced inrenderer
module attribute thus allowing only one renderer per one module.Creating an extension bindings. These are to be placed in
powerline/bindings/ext
and may contain virtually anything which may be required for powerline to work inside given applications, assuming it does not fit in other places.
Powerline class¶
-
class
powerline.
Powerline
(*args, **kwargs)[source]¶ Main powerline class, entrance point for all powerline uses. Sets powerline up and loads the configuration.
Parameters: - ext (str) – extension used. Determines where configuration files will
searched and what renderer module will be used. Affected: used
ext
dictionary frompowerline/config.json
, location of themes and colorschemes, render module (powerline.renders.{ext}
). - renderer_module (str) – Overrides renderer module (defaults to
ext
). Should be the name of the package imported like this:powerline.renderers.{render_module}
. If this parameter contains a dotpowerline.renderers.
is not prepended. There is also a special case for renderers defined in toplevel modules:foo.
(note: dot at the end) tries to get renderer from modulefoo
(becausefoo
(without dot) tries to get renderer from modulepowerline.renderers.foo
). When.foo
(with leading dot) variant is usedrenderer_module
will bepowerline.renderers.{ext}{renderer_module}
. - run_once (bool) – Determines whether
render()
method will be run only once during python session. - logger (Logger) – If present no new logger will be created and the provided logger will be used.
- use_daemon_threads (bool) – When creating threads make them daemon ones.
- shutdown_event (Event) – Use this Event as shutdown_event instead of creating new event.
- config_loader (ConfigLoader) – Instance of the class that manages (re)loading of the configuration.
-
create_logger
()[source]¶ Create logger
This function is used to create logger unless it was already specified at initialization.
Returns: Three objects: logging.Logger
instance.PowerlineLogger
instance.- Function, output of
gen_module_attr_getter()
.
-
create_renderer
(load_main=False, load_colors=False, load_colorscheme=False, load_theme=False)[source]¶ (Re)create renderer object. Can be used after Powerline object was successfully initialized. If any of the below parameters except
load_main
is True renderer object will be recreated.Parameters: - load_main (bool) – Determines whether main configuration file (
config.json
) should be loaded. If appropriate configuration changes impliesload_colorscheme
andload_theme
and recreation of renderer object. Won’t trigger recreation if only unrelated configuration changed. - load_colors (bool) – Determines whether colors configuration from
colors.json
should be (re)loaded. - load_colorscheme (bool) – Determines whether colorscheme configuration should be (re)loaded.
- load_theme (bool) – Determines whether theme configuration should be reloaded.
- load_main (bool) – Determines whether main configuration file (
-
static
do_setup
()[source]¶ Function that does initialization
Should be overridden by subclasses. May accept any number of regular or keyword arguments.
-
static
get_config_paths
()[source]¶ Get configuration paths.
Should be overridden in subclasses in order to provide a way to override used paths.
Returns: list of paths
-
static
get_encoding
()¶ Get encoding used by the current application
Usually returns encoding of the current locale.
-
static
get_local_themes
(local_themes)[source]¶ Get local themes. No-op here, to be overridden in subclasses if required.
Parameters: local_themes (dict) – Usually accepts {matcher_name : theme_name}
. May also receive None in case there is no local_themes configuration.Returns: anything accepted by self.renderer.get_theme
and processable byself.renderer.add_local_theme
. Renderer module is determined by__init__
arguments, refer to its documentation.
-
init
(ext, renderer_module=None, run_once=False, logger=None, use_daemon_threads=True, shutdown_event=None, config_loader=None)[source]¶ Do actual initialization.
__init__ function only stores the arguments and runs this function. This function exists for powerline to be able to reload itself: it is easier to make
__init__
store arguments and call overriddableinit
than tell developers that each time they override Powerline.__init__ in subclasses they must store actual arguments.
-
load_colors_config
()[source]¶ Get colorscheme.
Returns: dictionary with colors configuration.
-
load_colorscheme_config
(name)[source]¶ Get colorscheme.
Parameters: name (str) – Name of the colorscheme to load. Returns: dictionary with colorscheme configuration.
-
load_config
(cfg_path, cfg_type)[source]¶ Load configuration and setup watches
Parameters: - cfg_path (str) – Path to the configuration file without any powerline configuration
directory or
.json
suffix. - cfg_type (str) – Configuration type. May be one of
main
(forconfig.json
file),colors
,colorscheme
,theme
.
Returns: dictionary with loaded configuration.
- cfg_path (str) – Path to the configuration file without any powerline configuration
directory or
-
load_main_config
()[source]¶ Get top-level configuration.
Returns: dictionary with top-level configuration.
-
load_theme_config
(name)[source]¶ Get theme configuration.
Parameters: name (str) – Name of the theme to load. Returns: dictionary with theme configuration
-
reload
()[source]¶ Reload powerline after update.
Should handle most (but not all) powerline updates.
Purges out all powerline modules and modules imported by powerline for segment and matcher functions. Requires defining
setup
function that updates reference to main powerline object.Warning
Not guaranteed to work properly, use it at your own risk. It may break your python code.
-
render
(*args, **kwargs)[source]¶ Update/create renderer if needed and pass all arguments further to
self.renderer.render()
.
-
render_above_lines
(*args, **kwargs)[source]¶ Like .render(), but for
self.renderer.render_above_lines()
-
setup
(*args, **kwargs)[source]¶ Setup the environment to use powerline.
Must not be overridden by subclasses. This one only saves setup arguments for
reload()
method and callsdo_setup()
.
-
setup_components
(components)[source]¶ Run component-specific setup
Parameters: components (set) – Set of the enabled componets or None. Should be overridden by subclasses.
-
shutdown
(set_event=True)[source]¶ Shut down all background threads.
Parameters: set_event (bool) – Set
shutdown_event
and callrenderer.shutdown
which should shut down all threads. Set it to False unless you are exiting an application.If set to False this does nothing more then resolving reference cycle
powerline → config_loader → bound methods → powerline
by unsubscribing from config_loader events.
- ext (str) – extension used. Determines where configuration files will
searched and what renderer module will be used. Affected: used
Renderer class¶
-
class
powerline.renderer.
Renderer
(theme_config, local_themes, theme_kwargs, pl, ambiwidth=1, **options)[source]¶ Object that is responsible for generating the highlighted string.
Parameters: - theme_config (dict) – Main theme configuration.
- local_themes – Local themes. Is to be used by subclasses from
.get_theme()
method, base class only records this parameter to a.local_themes
attribute. - theme_kwargs (dict) – Keyword arguments for
Theme
class constructor. - pl (PowerlineLogger) – Object used for logging.
- ambiwidth (int) – Width of the characters with east asian width unicode attribute equal to
A
(Ambigious). - options (dict) – Various options. Are normally not used by base renderer, but all options are recorded as attributes.
-
do_render
(mode, width, side, line, output_raw, output_width, segment_info, theme)[source]¶ Like Renderer.render(), but accept theme in place of matcher_info
-
get_segment_info
(segment_info, mode)[source]¶ Get segment information.
Must return a dictionary containing at least
home
,environ
andgetcwd
keys (see documentation forsegment_info
attribute). This implementation mergessegment_info
dictionary passed to.render()
method with.segment_info
attribute, preferring keys from the former. It also replacesgetcwd
key with function returningsegment_info['environ']['PWD']
in casePWD
variable is available.Parameters: segment_info (dict) – Segment information that was passed to .render()
method.Returns: dict with segment information.
-
get_theme
(matcher_info)[source]¶ Get Theme object.
Is to be overridden by subclasses to support local themes, this variant only returns
.theme
attribute.Parameters: matcher_info – Parameter matcher_info
that.render()
method received. Unused.
-
hl
(contents, fg=None, bg=None, attrs=None)[source]¶ Output highlighted chunk.
This implementation just outputs
hlstyle()
joined withcontents
.
-
static
hl_join
()¶ Join a list of rendered segments into a resulting string
This method exists to deal with non-string render outputs, so segments may actually be not an iterable with strings.
Parameters: segments (list) – Iterable containing rendered segments. By “rendered segments” Renderer.hl()
output is meant.Returns: Results of joining these segments.
-
hlstyle
(bg=None, attrs=None)[source]¶ Output highlight style string.
Assuming highlighted string looks like
{style}{contents}
this method should output{style}
. If it is called without arguments this method is supposed to reset style to its default.
-
render
(mode=None, width=None, side=None, line=0, output_raw=False, output_width=False, segment_info=None, matcher_info=None)[source]¶ Render all segments.
When a width is provided, low-priority segments are dropped one at a time until the line is shorter than the width, or only segments with a negative priority are left. If one or more segments with
"width": "auto"
are provided they will fill the remaining space until the desired width is reached.Parameters: - mode (str) – Mode string. Affects contents (colors and the set of segments) of rendered string.
- width (int) – Maximum width text can occupy. May be exceeded if there are too much non-removable segments.
- side (str) – One of
left
,right
. Determines which side will be rendered. If not present all sides are rendered. - line (int) – Line number for which segments should be obtained. Is counted from zero (botmost line).
- output_raw (bool) – Changes the output: if this parameter is
True
then in place of one string this method outputs a pair(colored_string, colorless_string)
. - output_width (bool) – Changes the output: if this parameter is
True
then in place of one string this method outputs a pair(colored_string, string_width)
. Returns a three-tuple ifoutput_raw
is alsoTrue
:(colored_string, colorless_string, string_width)
. - segment_info (dict) – Segment information. See also
get_segment_info()
method. - matcher_info – Matcher information. Is processed in
get_segment_info()
method.
-
render_above_lines
(**kwargs)[source]¶ Render all segments in the {theme}/segments/above list
Rendering happens in the reversed order. Parameters are the same as in .render() method.
Yield: rendered line.
-
segment_info
= {u'environ': <environ dictionary>, u'getcwd': <built-in function getcwdu>, u'home': <home directory>}¶ Basic segment info
Is merged with local segment information by
get_segment_info()
method. Keys:environ
- Object containing environment variables. Must define at least the
following methods:
.__getitem__(var)
that raisesKeyError
in case requested environment variable is not present,.get(var, default=None)
that works likedict.get
and be able to be passed toPopen
. getcwd
- Function that returns current working directory. Will be called without
any arguments, should return
unicode
or (in python-2) regular string. home
- String containing path to home directory. Should be
unicode
or (in python-2) regular string orNone
.
-
shutdown
()[source]¶ Prepare for interpreter shutdown. The only job it is supposed to do is calling
.shutdown()
method for all theme objects. Should be overridden by subclasses in case they support local themes.
-
strwidth
(s)¶ Function that returns string width.
Is used to calculate the place given string occupies when handling
width
argument to.render()
method. Must take east asian width into account.Parameters: string (unicode) – String whose width will be calculated. Returns: unsigned integer.
Tips and tricks for powerline developers¶
Profiling powerline in Vim¶
Given that current directory is the root of the powerline repository the following command may be used:
vim --cmd 'let g:powerline_pyeval="powerline#debug#profile_pyeval"' \
--cmd 'set rtp=powerline/bindings/vim' \
-c 'runtime! plugin/powerline.vim' \
{other arguments if needed}
After some time run :WriteProfiling {filename}
Vim command. Currently this
only works with recent Vim and python-2*. It should be easy to modify
powerline/bindings/vim/autoload/powerline/debug.vim
to suit other
needs.
Troubleshooting¶
System-specific issues¶
Troubleshooting on Linux¶
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
andLC_*
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 orxterm*utf8
property set to1
or2
in~/.Xresources
(applied withxrdb
). Note that in caseuxterm
is used configuration is done viauxterm*…
properties and notxterm*…
.In any case the only absolute requirement is launching xterm with UTF-8 locale.
If you are using bitmap font make sure that
/etc/fonts/conf.d/70-no-bitmaps.conf
does not exist. If it does check out your distribution documentation to find a proper way to remove it (so that it won’t reappear after update). E.g. in Gentoo this is:eselect fontconfig disable 70-no-bitmaps.conf
(currently this only removes the symlink from
/etc/fonts/conf.d
). Also check out that no other fontconfig file does not haverejectfont
tag that tells fontconfig to disable bitmap fonts (they are referenced as not scalable).
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 am seeing strange blocks in place of playing/paused/stopped signs¶
If you are using powerline_unicode7
top-level theme then symbols for player segments are taken
from U+23F4–U+23FA range which is missing from most fonts. You may fix the issue
by using Symbola font (or any other font
which contains these glyphs).
If your terminal emulator is using fontconfig library then you can create a fontconfig configuration file with the following contents:
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
<alias>
<family>Terminus</family>
<prefer><family>Symbola</family></prefer>
</alias>
</fontconfig>
(replace Terminus
with the name of the font you are using). Exact sequence
of actions you need to perform is different across distributions, most likely it
will work if you put the above xml into
/etc/fonts/conf.d/99-prefer-symbola.conf
. On Gentoo you need to put it
into /etc/fonts/conf.d/99-prefer-symbola.conf
and run:
eselect fontconfig enable 99-prefer-symbola
.
Warning
This answer is only applicable if you use powerline_unicode7
theme or if
you configured powerline to use the same characters yourself.
Troubleshooting on OS X¶
I can’t see any fancy symbols, what’s wrong?¶
- If you’re using iTerm2, please update to this revision or newer. Also make sure that Preferences>Profiles>Text>Non-ASCII Font is the same as your main Font.
- You need to set your
LANG
andLC_*
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.
- If you’re using transparency, check “Keep background colors opaque”.
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 thepowerline
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.
I receive “FSEventStreamStart: register_with_server: ERROR” with status_colors¶
This is a known libuv issue that
happens if one is trying to watch too many files. It should be fixed in
libuv-0.12. Until then it is suggested to either disable status_colors
(from
powerline.segments.common.vcs.branch()
) or choose stat-based watcher
(will have effectively the same effect as disabling status_colors
).
Common issues¶
After an update something stopped working¶
Assuming powerline was working before update and stopped only after there are two possible explanations:
- You have more then one powerline installation (e.g.
pip
andVundle
installations) and you have updated only one. - Update brought some bug to powerline.
In the second case you, of course, should report the bug to powerline bug tracker. In the first you should make sure you either have only one powerline installation or you update all of them simultaneously (beware that in the second case you are not supported). To diagnose this problem you may do the following:
If this problem is observed within the shell make sure that
python -c 'import powerline; print (powerline.__file__)'
which should report something like
/usr/lib64/python2.7/site-packages/powerline/__init__.pyc
(if powerline is installed system-wide) or/home/USER/.../powerline/__init__.pyc
(if powerline was cloned somewhere, e.g. in/home/USER/.vim/bundle/powerline
) reports the same location you use to source in your shell configuration: in first case it should be some location in/usr
(e.g./usr/share/zsh/site-contrib/powerline.zsh
), in the second it should be something like/home/USER/.../powerline/bindings/zsh/powerline.zsh
. If this is true it may be a powerline bug, but if locations do not match you should not report the bug until you observe it on configuration where locations do match.If this problem is observed specifically within bash make sure that you clean
$POWERLINE_COMMAND
and$PROMPT_COMMAND
environment variables on startup or, at least, that it was cleaned after update. While different$POWERLINE_COMMAND
variable should not cause any troubles most of time (and when it will cause troubles are rather trivial) spoiled$PROMPT_COMMAND
may lead to strange error messages or absense of exit code reporting.These are the sources which may keep outdated environment variables:
- Any command launched from any application inherits its environment unless
callee explicitly requests to use specific environment. So if you did
exec bash
after update it is rather unlikely to fix the problem. - More interesting: tmux is a client-server application, it keeps one
server instance per one user. You probably already knew that, but there is
an interesting consequence: once tmux server was started it inherits its
environment from the callee and keeps it forever (i.e. until server is
killed). This environment is then inherited by applications you start with
tmux new-session
. Easiest solution is to kill tmux withtmux kill-server
, but you may also usetmux set-environment -u
to unset offending variables. - Also check When using z powerline shows wrong number of jobs: though
this problem should not be seen after update only, it contains another
example of
$PROMPT_COMMAND
spoiling results.
- Any command launched from any application inherits its environment unless
callee explicitly requests to use specific environment. So if you did
If this problem is observed within the vim instance you should check out the output of the following Ex mode commands
python import powerline as pl ; print (pl.__file__) python3 import powerline as pl ; print (pl.__file__)
One (but not both) of them will most likely error out, this is OK. The same rules apply as in the 1), but in place of sourcing you should seek for the place where you modify runtimepath vim option. If you install powerline using VAM then no explicit modifications of runtimpath were performed in your vimrc (runtimepath is modified by VAM in this case), but powerline will be placed in
plugin_root_dir/powerline
where {plugin_root_dir} is stored in VAM settings dictionary: do echo g:vim_addon_manager.plugin_root_dir.
There is a hint if you want to place powerline repository somewhere, but still make powerline package importable anywhere: use
pip install --user --editable path/to/powerline
Shell issues¶
Pipe status segment displays only last value in bash¶
Make sure that powerline command that sets prompt appears the very first in
$PROMPT_COMMAND
. To do this powerline.sh
needs to be sourced the very
last, after all other users of $PROMPT_COMMAND
.
Bash prompt stopped updating¶
Make sure that powerline commands appear in $PROMPT_COMMAND
: some users of
$PROMPT_COMMAND
have a habit of overwriting the value instead of
prepending/appending to it. All powerline commands start with _powerline
or
powerline
, e.g. _powerline_set_prompt
.
Bash prompt does not show last exit code¶
There are two possibilities here:
You are using
default
theme in place ofdefault_leftonly
. Unlikedefault_leftonly
default
theme was designed for shells with right prompt support (e.g. zsh, tcsh, fish) and status in question is supposed to be shown on the right side which bash cannot display.There is some other user of
$PROMPT_COMMAND
which prepended to this variable, but did not bother keeping the exit code. For the best experience powerline must appear first in$PROMPT_COMMAND
which may be achieved by sourcing powerline bindings the last.Note
Resourcing bash bindings will not resolve the problem unless you clear powerline commands from
$PROMPT_COMMAND
first.
When sourcing shell bindings it complains about missing command or file¶
If you are using pip
based installation do not forget to add pip-specific
executable path to $PATH
environment variable. This path usually looks
something like $HOME/.local/bin
(linux) or
$HOME/Library/Python/{python_version}/bin
(OS X). One may check out where
powerline-config
script was installed by using pip show -f
powerline-status | grep powerline-config
(does not always work).
I am suffering bad lags before displaying shell prompt¶
To get rid of these lags there currently are two options:
- Run
powerline-daemon
. Powerline does not automatically start it for you. - Compile and install
libzpython
module that lives in https://bitbucket.org/ZyX_I/zpython. This variant is zsh-specific.
Prompt is spoiled after completing files in ksh¶
This is exactly why powerline has official mksh support, but not official ksh support. If you know the solution feel free to share it in powerline bug tracker.
When using z powerline shows wrong number of jobs¶
This happens because z is launching some jobs in
the background from $POWERLINE_COMMAND
and these jobs fail to finish before
powerline prompt is run.
Solution to this problem is simple: be sure that z.sh
is sourced
strictly after powerline/bindings/bash/powerline.sh
. This way background
jobs are spawned by z after powerline has done
its job.
When using shell I do not see powerline fancy characters¶
If your locale encoding is not unicode (any encoding that starts with “utf” or “ucs” will work, case is ignored) powerline falls back to ascii-only theme. You should set up your system to use unicode locale or forget about powerline fancy characters.
Urxvt unicode3 and frills¶
Make sure that, whatever urxvt package you’re installing, both the unicode3
and frills features are enabled at compile time. Run
urxvt --help 2>&1 | grep options:
to get a list of enabled options.
This should contain at least frills, unicode3 and optionally iso14755
if you want to input Unicode characters as well.
Compiler flags example:
–enable-frills –enable-unicode3
As long as your terminal emulator is compiled without unicode rendering, no amount of configuration will make it display unicode characters. They’re being considered ‘unnecessary features’, but they add negligible overhead to the size of the installed package (~100KB).
Vim issues¶
My vim statusline has strange characters like ^B
in it!¶
- Please add
set encoding=utf-8
to yourvimrc
.
My vim statusline has a lot of ^
or underline characters in it!¶
You need to configure the
fillchars
setting to disable statusline fillchars (see:h 'fillchars'
for details). Add this to yourvimrc
to solve this issue:set fillchars+=stl:\ ,stlnc:\
My vim statusline is not displayed completely and has too much spaces¶
- Be sure you have
ambiwidth
option set tosingle
. - Alternative: set ambiwidth to 2, remove fancy
dividers (they suck when
ambiwidth
is set to double).
Powerline loses color after editing vimrc¶
If your vimrc has something like
autocmd! BufWritePost ~/.vimrc :source ~/.vimrc
used to automatically source vimrc after saving it then you must add nested
after pattern (vimrc
in this case):
autocmd! BufWritePost ~/.vimrc nested :source ~/.vimrc
. Alternatively move :colorscheme
command out of the vimrc to the file which
will not be automatically resourced.
Observed problem is that when you use :colorscheme
command existing
highlighting groups are usually cleared, including those defined by powerline.
To workaround this issue powerline hooks Colorscheme
event, but when you
source vimrc with BufWritePost
(or any other) event, but without nested
this event is not launched. See also autocmd-nested Vim
documentation.
Powerline loses color after saving any file¶
It may be one of the incarnations of the above issue: specifically minibufexpl is known to trigger it. If you are using minibufexplorer you should set
let g:miniBufExplForceSyntaxEnable = 1
variable so that this issue is not triggered. Complete explanation:
- When MBE autocommand is executed it launches
:syntax enable
Vim command… - … which makes Vim source
syntax/syntax.vim
file … - … which in turn sources
syntax/synload.vim
… - … which executes
:colorscheme
command. Normally this command triggersColorscheme
event, but in the first point minibufexplorer did set up autocommands that missnested
attribute meaning that no events will be triggered when processing MBE events.
Note
This setting was introduced in version 6.3.1 of minibufexpl and removed in version 6.5.0 of its successor minibufexplorer. It is highly advised to use the latter because minibufexpl was last updated late in 2004.
Tips and tricks¶
Vim¶
Useful settings¶
You may find the following vim settings useful when using the Powerline statusline:
set laststatus=2 " Always display the statusline in all windows
set showtabline=2 " Always display the tabline, even if there is only one tab
set noshowmode " Hide the default mode text (e.g. -- INSERT -- below the statusline)
Rxvt-unicode¶
Terminus font and urxvt¶
The Terminus fonts does not have the powerline glyphs and unless someone submits
a patch to the font author, it is unlikely to happen. However, Andre Klärner
came up with this work around: In your ~/.Xdefault
file add the following:
urxvt*font: xft:Terminus:pixelsize=12,xft:Inconsolata\ for\ Powerline:pixelsize=12
This will allow urxvt to fallback onto the Inconsolata fonts in case it does not find the right glyphs within the terminus font.
Source Code Pro font and urxvt¶
Much like the terminus font that was mentioned above, a similar fix can be applied to the Source Code Pro fonts.
In the ~/.Xdefaults
add the following:
URxvt*font: xft:Source\ Code\ Pro\ Medium:pixelsize=13:antialias=true:hinting=true,xft:Source\ Code\ Pro\ Medium:pixelsize=13:antialias=true:hinting=true
I noticed that Source Code Pro has the glyphs there already, but the pixel size of the fonts play a role in whether or not the > or the < separators showing up or not. Using font size 12, glyphs on the right hand side of the powerline are present, but the ones on the left don’t. Pixel size 14, brings the reverse problem. Font size 13 seems to work just fine.
Reloading powerline after update¶
Once you have updated powerline you generally have the following options:
Restart the application you are using it in. This is the safest one. Will not work if the application uses
powerline-daemon
.For shell and tmux bindings (except for zsh with libzpython): do not do anything if you do not use
powerline-daemon
, runpowerline-daemon --replace
if you do.Use powerline reloading feature.
Warning
This feature is an unsafe one. It is not guaranteed to work always, it may render your Python constantly error out in place of displaying powerline and sometimes may render your application useless, forcing you to restart.
Do not report any bugs occurred when using this feature unless you know both what caused it and how this can be fixed.
When using zsh with libzpython use
powerline-reload
Note
This shell function is only defined when using libzpython.
When using IPython use
%powerline reload
When using Vim use
py powerline.reload() " or (depending on Python version you are using) py3 powerline.reload()
License and credits¶
Powerline is licensed under the MIT license.
Contributors¶
- List of contributors
- The glyphs in the font patcher are created by Fabrizio Schiavi, creator of the excellent coding font Pragmata Pro.
Powerline shell commands’ manual pages¶
powerline-config manual page¶
Synopsis¶
powerline-config [-pPATH]… tmux ACTION ( [-s |n )]
powerline-config [-pPATH]… shell ACTION [COMPONENT] [-sSHELL]
Description¶
- -p, --config-path PATH
- Path to configuration directory. If it is present then configuration files will only be seeked in the provided path. May be provided multiple times to search in a list of directories.
- -h, --help
- Display help and exit.
Arguments specific to tmux subcommand¶
- ACTION
- If action is
source
then version-specific tmux configuration files are sourced, if it issetenv
then special (prefixed with_POWERLINE
) tmux global environment variables are filled with data from powerline configuration. Actionsetup
is just doingsetenv
thensource
. - -s, --source
- When using
setup
: always use configuration file sourcing. By default this is determined automatically based on tmux version: this is the default for tmux 1.8 and below. - -n, --no-source
- When using
setup
: in place of sourcing directly execute configuration files. That is, read each needed powerline-specific configuration file, substitute$_POWERLINE_…
variables with appropriate values and runtmux config line
. This is the default behaviour for tmux 1.9 and above. - -h, --help
- Display help and exit.
Arguments specific to shell subcommand¶
- ACTION
- If action is
command
then preferred powerline command is output, if it isuses
then powerline-config script will exit with 1 if specified component is disabled and 0 otherwise. - COMPONENT
- Only applicable for
uses
subcommand: makespowerline-config
exit with 0 if specific component is enabled and with 1 otherwise.tmux
component stands for tmux bindings (e.g. those that notify tmux about current directory changes),prompt
component stands for shell prompt. - -s, --shell SHELL
- Shell for which query is run
- -h, --help
- Display help and exit.
Author¶
Written by Kim Silkebækken, Nikolay Pavlov, Kovid Goyal and contributors. The glyphs in the font patcher are created by Fabrizio Schiavi.
Reporting bugs¶
Report powerline-config bugs to https://github.com/powerline/powerline/issues.
See also¶
powerline(1)
powerline-daemon manual page¶
Synopsis¶
powerline-daemon [--quiet] [--socket=S] ( [--kill] | (
[--foreground] | [--replace] ) )
Description¶
- --quiet, -q
- Without other options: do not complain about already running powerline-daemon instance. Will still exit with 1. With
--kill
and--replace
: do not show any messages. With--foreground
: ignored. Does not silence exceptions in any case. - --socket, -s S
- Specify socket which will be used for connecting to daemon.
- --kill, -k
- Kill an already running instance.
- --foreground, -f
- Run in the foreground (don’t daemonize).
- --replace, -r
- Replace an already running instance.
- -h, --help
- Display help and exit.
Author¶
Written by Kim Silkebækken, Nikolay Pavlov, Kovid Goyal and contributors. The glyphs in the font patcher are created by Fabrizio Schiavi.
Reporting bugs¶
Report powerline-daemon bugs to https://github.com/powerline/powerline/issues.
See also¶
powerline(1)
powerline-lint manual page¶
Synopsis¶
powerline-lint [-pPATH]… [-d]
Description¶
- -p, --config-path PATH
- Paths where configuration should be checked, in order. You must supply all paths necessary for powerline to work, checking partial (e.g. only user overrides) configuration is not supported.
- -d, --debug
- Display additional information. Used for debugging
powerline-lint
itself, not for debugging configuration. - -h, --help
- Display help and exit.
Author¶
Written by Kim Silkebækken, Nikolay Pavlov, Kovid Goyal and contributors. The glyphs in the font patcher are created by Fabrizio Schiavi.
Reporting bugs¶
Report powerline-lint bugs to https://github.com/powerline/powerline/issues.
See also¶
powerline(1), powerline-config(1)
powerline manual page¶
Synopsis¶
powerline EXT [SIDE] [-rMODULE] [-wWIDTH] [--last-exit-code=INT]
[--last-pipe-status=LIST] [--jobnum=INT]
[-cKEY.KEY=VALUE]… [-tTHEME.KEY.KEY=VALUE]… [-RKEY=VAL]…
[-pPATH]… [--socket=ADDRESS]
Description¶
- EXT
- Extension: application for which powerline command is launched (usually
shell
ortmux
). Also supportswm.
extensions:wm.awesome
. - SIDE
- Side:
left
andright
represent left and right side respectively,above
emits lines that are supposed to be printed just above the prompt andaboveleft
is like concatenatingabove
withleft
with the exception that only one Python instance is used in this case. May be omitted forwm.*
extensions. - -r, --renderer-module MODULE
- Renderer module. Usually something like
.bash
or.zsh
(with leading dot) which ispowerline.renderers.{ext}{MODULE}
, may also be full module name (must contain at least one dot or end with a dot in case it is top-level module) orpowerline.renderers
submodule (in case there are no dots). - -w, --width WIDTH
- Maximum prompt with. Triggers truncation of some segments.
- --last-exit-code INT
- Last exit code.
- --last-pipe-status LIST
- Like above, but is supposed to contain space-separated array of statuses, representing exit statuses of commands in one pipe.
- --jobnum INT
- Number of jobs.
- -c, --config-override KEY.KEY=VALUE
- Configuration overrides for
config.json
. Is translated to a dictionary and merged with the dictionary obtained from actual JSON configuration: KEY.KEY=VALUE is translated to{"KEY": {"KEY": VALUE}}
and then merged recursively. VALUE may be any JSON value, values that are notnull
,true
,false
, start with digit,{
,[
are treated like strings. If VALUE is omitted then corresponding key is removed. - -t, --theme-override THEME.KEY.KEY=VALUE
- Like above, but theme-specific. THEME should point to an existing and used theme to have any effect, but it is fine to use any theme here.
- -R, --renderer-arg KEY=VAL
- Like above, but provides argument for renderer. Is supposed to be used only by shell bindings to provide various data like last-exit-code or last-pipe-status (they are not using
--renderer-arg
for historical resons:--renderer-arg
was added later). - -p, --config-path PATH
- Path to configuration directory. If it is present then configuration files will only be seeked in the provided path. May be provided multiple times to search in a list of directories.
- --socket ADDRESS
- Socket address to use in daemon clients. Is always UNIX domain socket on linux and file socket on Mac OS X. Not used here, present only for compatibility with other powerline clients. This argument must always be the first one and be in a form
--socket ADDRESS
: no=
or short form allowed (in other powerline clients, not here). - -h, --help
- Display help and exit.
Author¶
Written by Kim Silkebækken, Nikolay Pavlov, Kovid Goyal and contributors. The glyphs in the font patcher are created by Fabrizio Schiavi.
Reporting bugs¶
Report powerline bugs to https://github.com/powerline/powerline/issues.
See also¶
powerline-daemon(1), powerline-config(1)