{"id":6035,"library":"powerline-shell","title":"powerline-shell","description":"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.","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/b-ryan/powerline-shell","tags":["shell","prompt","bash","zsh","fish","customization","cli","terminal"],"install":[{"cmd":"pip install powerline-shell","lang":"bash","label":"Install using pip"},{"cmd":"git clone --depth=1 https://github.com/powerline/fonts.git\ncd fonts\n./install.sh\ncd ..\nrm -rf fonts","lang":"bash","label":"Install Powerline Fonts (recommended for glyphs)"}],"dependencies":[{"reason":"Core interpreter requirement (2.6+ or 3.2+)","package":"python","optional":false},{"reason":"Required for segments like cpu_percent","package":"psutil","optional":true},{"reason":"Required for Git repositories (or git executable)","package":"pygit2","optional":true},{"reason":"Required for Mercurial repositories (or mercurial executable)","package":"hglib","optional":true},{"reason":"Required for Bazaar repositories","package":"bzr","optional":true}],"imports":[{"note":"powerline-shell generates shell prompts; it's not a library for direct Python code import and execution in typical application development.","symbol":"powerline_shell","correct":"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."}],"quickstart":{"code":"# 1. Install powerline-shell (if not already done)\npip install powerline-shell\n\n# 2. Install Powerline-compatible fonts (if not already done)\n# This is crucial for correct symbol rendering. Restart your terminal after installing.\ngit clone --depth=1 https://github.com/powerline/fonts.git\ncd fonts\n./install.sh\ncd ..\nrm -rf fonts\n\n# 3. Configure your shell (example for Bash - add to ~/.bashrc)\n# Find your powerline-shell.py path, e.g., using 'pip show powerline-shell' and looking at 'Location'\n# Example path: $HOME/.local/bin/powerline-shell\n\n# Ensure .local/bin is in PATH for pip-installed executables\nexport PATH=\"$PATH:$HOME/.local/bin\"\n\nfunction _update_ps1() {\n    PS1=$(powerline-shell $?)\n}\n\nif [[ $TERM != linux && ! $PROMPT_COMMAND =~ _update_ps1 ]]; then\n    PROMPT_COMMAND=\"_update_ps1; $PROMPT_COMMAND\"\nfi\n\n# 4. Apply changes (or open a new terminal)\nsource ~/.bashrc\n\n# 5. (Optional) Customize by copying the default config to your home directory\n# and editing ~/.config/powerline-shell/config.json\nmkdir -p ~/.config/powerline-shell\ncp $(pip show powerline-shell | grep Location | cut -d ' ' -f 2)/powerline_shell/config.json.dist ~/.config/powerline-shell/config.json","lang":"bash","description":"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."},"warnings":[{"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'.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your custom configuration file is located at `~/.config/powerline-shell/config.json`. If migrating, copy your existing configuration to this new path.","message":"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.","severity":"breaking","affected_versions":"<=0.6.x (transition to 0.7.x)"},{"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.","message":"While generally performant, complex segments or operations within very large or deeply nested version control repositories can occasionally introduce noticeable lag in prompt rendering.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}