Install & Compatibility
Where this runs
tested against v0.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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
powerline-shell --version
Debug
Known issues
breakingPowerline-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.fixInstall 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'.
affects: All versions
gotchaThe 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.fixEnsure 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.
affects: All versions
breakingThe default location for `powerline-shell`'s configuration file changed to `~/.config/powerline-shell/config.json`. Older installations might look for configuration in different paths.fixEnsure your custom configuration file is located at `~/.config/powerline-shell/config.json`. If migrating, copy your existing configuration to this new path.
affects: <=0.6.x (transition to 0.7.x)
gotchaWhile generally performant, complex segments or operations within very large or deeply nested version control repositories can occasionally introduce noticeable lag in prompt rendering.fixReview 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.
affects: All versions
Upgrade
Version history
0.7.0latest on PyPI · released Sep 16, 2018
Audit
Dependencies
pythonrequiredCore interpreter requirement (2.6+ or 3.2+)
psutiloptionalRequired for segments like cpu_percent
pygit2optionalRequired for Git repositories (or git executable)
hgliboptionalRequired for Mercurial repositories (or mercurial executable)
bzroptionalRequired for Bazaar repositories