powerline-shell

0.7.0 · active · verified Tue Apr 14

Powerline-shell is a Python-based utility that generates a beautiful and highly customizable prompt for various shells including Bash, ZSH, Fish, and tcsh. It enhances the command-line experience by displaying contextual information such as version control status (Git, SVN, Mercurial), the current Python virtual environment, command exit codes, and a shortened current working directory. It is configured via a JSON file to define segments and themes. The current version is 0.7.0 and it is actively maintained.

Warnings

breaking Powerline-shell requires Powerline-patched fonts (e.g., from powerline/fonts repository or Nerd Fonts) to display symbols (arrows, branch icons) correctly. Without them, you will see broken characters or squares.
Fix: Install a Powerline-patched font and configure your terminal emulator to use it. Examples include 'Source Code Pro for Powerline' or 'DejaVu Sans Mono for Powerline'.
gotcha The order in which shell prompt commands (e.g., `_update_ps1` for Bash's `PROMPT_COMMAND`) are sourced can lead to unexpected behavior, such as incorrect exit codes or issues with certain segments.
Fix: Ensure that the `powerline-shell` prompt update function is set as the *first* item in `PROMPT_COMMAND` (for Bash) or sourced appropriately at the end of your shell configuration file (e.g., `.bashrc`, `.zshrc`) to prevent interference.
breaking The default location for `powerline-shell`'s configuration file changed to `~/.config/powerline-shell/config.json`. Older installations might look for configuration in different paths.
Fix: Ensure your custom configuration file is located at `~/.config/powerline-shell/config.json`. If migrating, copy your existing configuration to this new path.
gotcha While generally performant, complex segments or operations within very large or deeply nested version control repositories can occasionally introduce noticeable lag in prompt rendering.
Fix: Review and optimize your `config.json` by disabling less critical segments, adjusting parameters like `max_depth` for the `cwd` segment, or considering alternatives like `powerline-go` for extreme performance needs.

Install

pip install powerline-shell Install using pip
git clone --depth=1 https://github.com/powerline/fonts.git cd fonts ./install.sh cd .. rm -rf fonts Install Powerline Fonts (recommended for glyphs)

Imports

powerline_shell

powerline-shell is primarily configured via shell scripts and JSON files, not typically imported as a Python library for direct programmatic use. For extending it, segments are Python scripts located in powerline_shell/segments.

powerline-shell generates shell prompts; it's not a library for direct Python code import and execution in typical application development.

Quickstart

This quickstart demonstrates how to install powerline-shell, set up required fonts for proper rendering, and integrate it into a Bash shell environment. It also includes steps for initial configuration file setup for customization.

# 1. Install powerline-shell (if not already done)
pip install powerline-shell

# 2. Install Powerline-compatible fonts (if not already done)
# This is crucial for correct symbol rendering. Restart your terminal after installing.
git clone --depth=1 https://github.com/powerline/fonts.git
cd fonts
./install.sh
cd ..
rm -rf fonts

# 3. Configure your shell (example for Bash - add to ~/.bashrc)
# Find your powerline-shell.py path, e.g., using 'pip show powerline-shell' and looking at 'Location'
# Example path: $HOME/.local/bin/powerline-shell

# Ensure .local/bin is in PATH for pip-installed executables
export PATH="$PATH:$HOME/.local/bin"

function _update_ps1() {
    PS1=$(powerline-shell $?)
}

if [[ $TERM != linux && ! $PROMPT_COMMAND =~ _update_ps1 ]]; then
    PROMPT_COMMAND="_update_ps1; $PROMPT_COMMAND"
fi

# 4. Apply changes (or open a new terminal)
source ~/.bashrc

# 5. (Optional) Customize by copying the default config to your home directory
# and editing ~/.config/powerline-shell/config.json
mkdir -p ~/.config/powerline-shell
cp $(pip show powerline-shell | grep Location | cut -d ' ' -f 2)/powerline_shell/config.json.dist ~/.config/powerline-shell/config.json

view raw JSON →