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 for you, but you should still skim through this guide so you know how the plugin works.

If you’re running a distribution without an official package you’ll have to follow the installation guide below:

Plugin installation

  1. Install Python 3.2+ or Python 2.6+.

  2. Install Powerline using the following command:

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

Note

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

Font installation

Powerline provides two ways of installing the required fonts on Linux. The recommended method is using fontconfig if your terminal emulator supports it. See the Application/terminal emulator feature support matrix for details about what features your terminal emulator supports.

Fontconfig

  1. Download the latest version of PowerlineSymbols and the latest version of the fontconfig file.
  2. Move PowerlineSymbols.otf to ~/.fonts/ (or another X font directory).
  3. Run fc-cache -vf ~/.fonts to update your font cache.
  4. Move 10-powerline-symbols.conf to either ~/.fonts.conf.d/ or ~/.config/fontconfig/conf.d/, depending on your fontconfig version.
  5. If you don’t see the arrow symbols, please close all instances of your terminal emulator or gvim. You may also have to restart X for the changes to take effect. If you still don’t see the arrow symbols, please submit an issue on GitHub.

Patched font

  1. Download the font of your choice from powerline-fonts. If you can’t find your preferred font in the powerline-fonts repo, you’ll have to patch your own font instead. See Font patching for instructions.
  2. Move your patched font to ~/.fonts/ (or another X font directory).
  3. Run fc-cache -vf ~/.fonts to update your font cache.
  4. Update Gvim or your terminal emulator to use the patched font. (the correct font usually ends with for Powerline).
  5. If you don’t see the arrow symbols, please close all instances of your terminal emulator or gvim. You may also have to restart X for the changes to take effect. If you still don’t see the arrow symbols, please submit an issue on GitHub.

Troubleshooting

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 (see Font patching).
  • You need to set your LANG and LC_* environment variables to a UTF-8 locale (e.g. LANG=en_US.utf8). Consult your Linux distro’s documentation for information about setting these variables correctly.
  • Make sure that vim is compiled with the --with-features=big flag.
  • If you’re using rxvt-unicode, make sure that it’s compiled with the --enable-unicode3 flag.

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’m using tmux and Powerline looks like crap, what’s wrong?

  • You need to tell tmux that it has 256-color capabilities. Add this to your .tmux.conf to solve this issue:

    set -g default-terminal "screen-256color"
    
  • If you’re using iTerm2, make sure that you have enabled the setting Set locale variables automatically in Profiles ‣ Terminal ‣ Environment.

I’m using tmux/screen and Powerline is colorless

  • If the above advices do not help, then you need to disable term_truecolor.
  • Alternative: set additional_escapes to "tmux" or "screen". Note that it is known to work perfectly in screen, but in tmux it may produce ugly spaces.

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 and Vundle 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:

  1. 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.

  2. 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

My vim statusline has strange characters like ^B in it!

  • Please add set encoding=utf-8 to your vimrc.

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 your vimrc to solve this issue:

    set fillchars+=stl:\ ,stlnc:\
    

My vim statusline is hidden/only appears in split windows!

  • Make sure that you have set laststatus=2 in your vimrc.

My vim statusline is not displayed completely and has too much spaces

  • Be sure you have ambiwidth option set to single.
  • Alternative: set ambiwidth to 2, remove fancy dividers (they suck when ambiwidth is set to double).

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.

I am suffering bad lags before displaying shell prompt

To get rid of these lags there currently are two options:

  • Take powerline-daemon script and one of powerline-client implementations from feature/daemon branch (all powerline-client implementations leave in client folder: you need to either compile powerline.c or install socat and use powerline.sh (powerline.py is much slower)). Fortunately this branch will be merged in the future.
  • Compile and install libzpython module that lives in https://bitbucket.org/ZyX_I/zpython. This variant is zsh-specific.