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:

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

2. If variable $XDG_CONFIG_DIRS is set and non-empty then to any directory/powerline where {directory} is a directory listed in a colon-separated $XDG_CONFIG_DIRS list. Directories are checked in reverse order.

3. 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 your username and password. The server defaults to GMail’s IMAP server, but you can set the server/port by adding a server and a port 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.

It is using OpenWeatherMap as a provider, which can be configured with a personal API key. These can be generated here

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 or api key arguments:

{
    "name": "weather",
    "priority": 50,
    "args": {
        "unit": "F",
        "location_query": "oslo, norway",
        "weather_api_key": "your_api_key"
    }
},

References

• Configuration reference
  • Main configuration
    • Common configuration
    • Extension-specific configuration
  • Color definitions
  • Colorschemes
  • Themes
• Segment reference
  • Segments
  • Available segments
    • Common segments
      • VCS submodule
        • BranchSegment
        • StashSegment
        • branch()
        • stash()
      • System properties
        • CPULoadPercentSegment
        • cpu_load_percent()
        • system_load()
        • uptime()
      • Network
        • ExternalIpSegment
        • NetworkLoadSegment
        • external_ip()
        • hostname()
        • internal_ip()
        • network_load()
      • Current environment
        • CwdSegment
          • CwdSegment.argspecobjs()
          • CwdSegment.omitted_args()
        • cwd()
        • environment()
        • user()
        • virtualenv()
      • Battery
        • battery()
      • Weather
        • WeatherSegment
        • weather()
      • Date and time
        • date()
        • fuzzy_time()
      • Mail
        • EmailIMAPSegment
        • email_imap_alert()
      • Media players
        • ClementinePlayerSegment
        • CmusPlayerSegment
          • CmusPlayerSegment.get_player_status()
        • DbusPlayerSegment
        • ITunesPlayerSegment
        • MocPlayerSegment
          • MocPlayerSegment.get_player_status()
        • MpdPlayerSegment
        • PlayerSegment
          • PlayerSegment.argspecobjs()
          • PlayerSegment.omitted_args()
        • RDIOPlayerSegment
        • RhythmboxPlayerSegment
        • SpotifyAppleScriptPlayerSegment
        • SpotifyDbusPlayerSegment
        • clementine()
        • cmus()
        • dbus_player()
        • itunes()
        • mocp()
        • mpd()
        • rdio()
        • rhythmbox()
        • spotify()
        • spotify_apple_script()
        • spotify_dbus()
    • i3wm segments
      • active_window()
      • mode()
      • scratchpad()
      • workspace()
      • workspaces()
    • PDB segments
      • current_code_name()
      • current_context()
      • current_file()
      • current_line()
      • stack_depth()
    • Shell segments
      • ShellCwdSegment
      • continuation()
      • cwd()
      • jobnum()
      • last_pipe_status()
      • last_status()
      • mode()
    • Tmux segments
      • attached_clients()
    • Vim segments
      • VimBranchSegment
      • VimStashSegment
      • branch()
      • bufnr()
      • col_current()
      • csv_col_current()
      • file_bom()
      • file_directory()
      • file_encoding()
      • file_format()
      • file_name()
      • file_scheme()
      • file_size()
      • file_type()
      • file_vcs_status()
      • line_count()
      • line_current()
      • line_percent()
      • mode()
      • modified_buffers()
      • modified_indicator()
      • paste_indicator()
      • position()
      • readonly_indicator()
      • stash()
      • tab()
      • tab_modified_indicator()
      • tabnr()
      • trailing_whitespace()
      • virtcol_current()
      • visual_range()
      • window_title()
      • winnr()
      • Plugin-specific segments
        • Asynchronous Linter Engine (ALE) segments
          • ale()
        • Syntastic segments
          • syntastic()
        • Command-T segments
          • finder()
          • path()
        • Tagbar segments
          • current_tag()
        • NERDTree segments
          • nerdtree()
        • Capslock segments
          • capslock_indicator()
• Lister reference
  • Vim listers
    • bufferlister()
    • tablister()
  • Pdb listers
    • frame_lister()
  • i3wm listers
    • output_lister()
    • workspace_lister()
• Selector functions
  • Available selectors
    • Vim selectors
      • single_tab()
• Local configuration overrides
  • Vim overrides
    • VimVarHandler
  • Powerline script overrides
  • Environment variables overrides
  • Zsh/zpython overrides
  • Ipython overrides
  • Prompt command
  • PDB overrides