Troubleshooting

System-specific issues

• Linux
  • I can’t see any fancy symbols, what’s wrong?
  • The fancy symbols look a bit blurry or “off”!
  • I am seeing strange blocks in place of playing/paused/stopped signs
• OS X
  • I can’t see any fancy symbols, what’s wrong?
  • The colors look weird in the default OS X Terminal app!
  • The colors look weird in iTerm2!
  • Statusline is getting wrapped to the next line in iTerm2
  • I receive a NameError when trying to use Powerline with MacVim!
  • I receive an ImportError when trying to use Powerline on OS X!
  • I receive “FSEventStreamStart: register_with_server: ERROR” with 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 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 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 absence 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 with tmux kill-server, but you may also use tmux 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.

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

Tmux/screen-related issues

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.

• Make sure tmux knows that terminal it is running in support 256 colors. You may tell it tmux by using -2 option when launching it.

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.

  Warning

  Both tmux and screen are not resending sequences escaped in such a way. Thus even though additional escaping will work for the last shown prompt, highlighting will eventually go away when tmux or screen will redraw screen for some reason.

  E.g. in screen it will go away when you used copy mode and prompt got out of screen and in tmux it will go away immediately after you press <Enter>.

In tmux there is a green bar in place of powerline

In order for tmux bindings to work powerline-config script is required to be present in $PATH. Alternatively one may define $POWERLINE_CONFIG_COMMAND environment variable pointing to the location of the script. This variable must be defined prior to launching tmux server and in the environment where server is started from.

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 of default_leftonly. Unlike default_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. See installation instructions for more details.

• Compile and install libzpython module that lives in https://bitbucket.org/ZyX_I/zpython. This variant is zsh-specific.

• If you are a python package manager, be sure to set POWERLINE_COMMAND to your Powerline command. See installation instructions for details.

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

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:

1. When MBE autocommand is executed it launches :syntax enable Vim command…

2. … which makes Vim source syntax/syntax.vim file …

3. … which in turn sources syntax/synload.vim …

4. … which executes :colorscheme command. Normally this command triggers Colorscheme event, but in the first point minibufexplorer did set up autocommands that miss nested 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.