{"id":13415374,"url":"https://github.com/erikw/tmux-powerline","last_synced_at":"2025-05-13T19:16:00.559Z","repository":{"id":3584171,"uuid":"4647320","full_name":"erikw/tmux-powerline","owner":"erikw","description":"⚡️ A tmux plugin giving you a hackable status bar consisting of dynamic \u0026 beautiful looking powerline segments, written purely in bash.","archived":false,"fork":false,"pushed_at":"2025-04-21T17:41:23.000Z","size":1347,"stargazers_count":3561,"open_issues_count":7,"forks_count":520,"subscribers_count":68,"default_branch":"main","last_synced_at":"2025-04-28T10:56:04.616Z","etag":null,"topics":["bash","configuration","dynamic","hacktoberfest","powerline","segments","shell","statusbar","tmux","tmux-plugin","tmux-plugins","tmux-powerline","tmux-status","tmux-theme","tpm"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/erikw.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-06-13T06:51:01.000Z","updated_at":"2025-04-28T08:25:55.000Z","dependencies_parsed_at":"2024-03-11T07:30:53.847Z","dependency_job_id":"72392bee-c88d-4760-ad10-66066a6849ab","html_url":"https://github.com/erikw/tmux-powerline","commit_stats":{"total_commits":818,"total_committers":124,"mean_commits":6.596774193548387,"dds":0.5660146699266504,"last_synced_commit":"6aea97f0da6fcbf961ade75ccf2d63083f818540"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikw%2Ftmux-powerline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikw%2Ftmux-powerline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikw%2Ftmux-powerline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikw%2Ftmux-powerline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erikw","download_url":"https://codeload.github.com/erikw/tmux-powerline/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010822,"owners_count":21999002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","configuration","dynamic","hacktoberfest","powerline","segments","shell","statusbar","tmux","tmux-plugin","tmux-plugins","tmux-powerline","tmux-status","tmux-theme","tpm"],"created_at":"2024-07-30T21:00:47.806Z","updated_at":"2025-05-13T19:16:00.536Z","avatar_url":"https://github.com/erikw.png","language":"Shell","funding_links":[],"categories":["Alternative Engines","Shell","Mac OSX","\u003ca name=\"tools\"\u003e\u003c/a\u003eTools and session management"],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable first-line-heading --\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg alt=\"log\" width=\"80%\" src=\"img/logo.png\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003ci\u003eEmpowering your tmux (status bar) experience!\u003c/i\u003e\n    \u003ca href=\"https://x.com/intent/post?text=%E2%9A%A1%EF%B8%8Ftmux-powerline%E2%9A%A1%EF%B8%8F:%20A%20tmux%20plugin%20for%20a%20hackable%20status%20bar%20consisting%20of%20segments\u0026url=https%3A%2F%2Fgithub.com%2Ferikw%2Ftmux-powerline\u0026via=erik_westrup\u0026hashtags=tmux%2Ctmux_powerline%2Cstatusbar\" title=\"Post on X\"\u003e\u003cimg src=\"https://img.shields.io/twitter/url/http/shields.io.svg?style=social\" alt=\"Post on X\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003chr\u003e\n\n\u003cp align=\"center\"\u003e\n   \u003cimg src=\"https://img.shields.io/github/stars/erikw/tmux-powerline?style=social\" alt=\"GitHub Stars\"  /\u003e\n   \u003cimg src=\"https://img.shields.io/github/forks/erikw/tmux-powerline?style=social\" alt=\"GitHub Forks\"  /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003c!-- Ref: https://dev.to/azure/adding-a-github-codespace-button-to-your-readme-5f6l --\u003e\n    \u003ca href=\"https://github.com/codespaces/new?hide_repo_select=true\u0026ref=main\u0026repo=4647320\" title=\"Open in GitHub Codespaces\" \u003e\u003cimg alt=\"Open in GitHub Codespaces\" src=\"https://github.com/codespaces/badge.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c!-- markdownlint-disable no-empty-links --\u003e\n[![Lint Full](https://github.com/erikw/tmux-powerline/actions/workflows/linter-full.yml/badge.svg)](https://github.com/erikw/tmux-powerline/actions/workflows/linter-full.yml)\n[![SLOC](https://sloc.xyz/github/erikw/tmux-powerline?lower=true)](#)\n[![Number of programming languages used](https://img.shields.io/github/languages/count/erikw/tmux-powerline)](#)\n[![Top programming languages used](https://img.shields.io/github/languages/top/erikw/tmux-powerline)](#)\n[![Open issues](https://img.shields.io/github/issues/erikw/tmux-powerline)](https://github.com/erikw/tmux-powerline/issues)\n[![Closed issues](https://img.shields.io/github/issues-closed/erikw/tmux-powerline?color=success)](https://github.com/erikw/tmux-powerline/issues?q=is%3Aissue+is%3Aclosed)\n[![Closed PRs](https://img.shields.io/github/issues-pr-closed/erikw/tmux-powerline?color=success)](https://github.com/erikw/tmux-powerline/pulls?q=is%3Apr+is%3Aclosed)\n[![License](https://img.shields.io/badge/license-BSD--3-blue)](LICENSE.txt)\n[![OSS Lifecycle](https://img.shields.io/osslifecycle/erikw/tmux-powerline)](https://github.com/Netflix/osstracker)\n[![Latest tag](https://img.shields.io/github/v/tag/erikw/tmux-powerline)](https://github.com/erikw/tmux-powerline/tags)\n\u003cbr\u003e\n\u003c!-- markdownlint-enable no-empty-links --\u003e\n\n[![Contributors](https://img.shields.io/github/contributors/erikw/tmux-powerline)](https://github.com/erikw/tmux-powerline/graphs/contributors) including these top contributors:\n\u003ca href=\"https://github.com/erikw/tmux-powerline/graphs/contributors\"\u003e\n\u003cimg alt=\"Top Contributors\" src=\"https://contrib.rocks/image?repo=erikw/tmux-powerline\u0026max=36\"/\u003e\n\u003c/a\u003e\n\n\n# Intro\ntmux-powerline is a tmux \u003ca title=\"Tmux Plugin Manager\" href=\"https://github.com/tmux-plugins/tpm\"\u003etpm\u003c/a\u003e plugin that gives you a slick and hackable powerline status bar consisting of segments. It's easily extensible with custom segments and themes.\nThe plugin itself is implemented purely in bash thus minimizing system requirements. However you can make segments in any language you want (with a shell wrapper).\n\nSome examples of segments available that you can add to your tmux status bar are (full list [here](https://github.com/erikw/tmux-powerline/tree/main/segments)):\n* LAN \u0026 WAN IP addresses\n* Now Playing for MPD, Spotify (GNU/Linux native or wine, macOS), iTunes (macOS), Rhythmbox, Banshee, MOC, Audacious, Rdio (macOS), cmus, Pithos and Last.fm (last scrobbled track).\n* New mail count for GMail, Maildir, mbox, mailcheck, and Apple Mail\n* GNU/Linux and macOS battery status (uses [richo/dotfiles/bin/battery](https://github.com/richoH/dotfiles/blob/master/bin/battery))\n* Weather in Celsius, Fahrenheit and Kelvin using Yahoo Weather\n* System load, cpu usage and uptime\n* Git, SVN and Mercurial branch in CWD\n* Date and time\n* Hostname\n* tmux info\n* tmux mode indicator (normal/prefix, mouse, copy modes)\n* CWD in pane\n* Current X keyboard layout\n* Network download/upload speed\n* Earthquake warnings\n\n# Screenshots\n**Full screenshot**\n\n\u003ca href=\"img/full.png\" title=\"Full screenshot\"\u003e\u003cimg src=\"img/full.png\" width=\"850\" alt=\"Full screenshot\"\u003e\u003c/a\u003e\n\n**left-status**\n\nCurrent tmux session, window and pane, hostname and LAN \u0026 WAN IP address.\n\n![left-status](img/left-status.png)\n\n**right-status**\n\nNew mails, now playing, average load, weather, date and time.\n\n![right-status](img/right-status.png)\n\nNow I've read my inbox so the mail segment disappears!\n\n![right-status, no mail](img/right-status_no_mail.png)\n\nAfter pausing the music there's no need for showing the Now Playing segment anymore. Also the weather has become much nicer!\n\n![right-status, no mpd](img/right-status_no_mpd.png)\n\nLaptop mode: a battery segment.\n\n![right-status, weather and battery](img/right-status_weather_battery.png)\n\n**dual-line status**\n\n![dual-line status bar](img/dual-line-status-bar.png)\n\n# Co-Maintainer\n[@xx4h](https://github.com/xx4h) is helping out developing, maintaining and managing this project!\n\n# Requirements\nRequirements for the lib to work are:\n* `tmux -V` \u003e= 2.9\n* `bash --version` \u003e= 3.2 (Does not have to be your default shell.)\n* Nerd Font. Follow instructions at [Font Installation](https://github.com/ryanoasis/nerd-fonts?tab=readme-ov-file#font-installation). However you can use other substitute symbols as well; see `config.sh`.\n\n## Segment Requirements\nSome segments have their own requirements. If you enable them in your theme, make sure all requirements are met for those.\n\n* **dropbox_status.sh**: `dropbox-cli`\n* **github_notifications.sh**: `jq`\n* **ifstat.sh**: `ifstat` (there is a simpler segment `ifstat_sys.sh` not using ifstat)\n* **mailcount.sh**\n   * gmail: `wget`\n   * mailcheck: [mailcheck](http://packages.debian.org/sid/mailcheck)\n* **now_playing.sh**\n   * mpd: [libmpdclient](http://sourceforge.net/projects/musicpd/files/libmpdclient/)\n   * last.fm: `jq`, `curl`\n* **rainbarf.sh**: [rainbarf](https://github.com/creaktive/rainbarf)\n* **tmux_mem_cpu_load.sh**: [tmux-mem-cpu-load](https://github.com/thewtex/tmux-mem-cpu-load)\n* **wan_ip.sh**: `curl`\n* **weather.sh**:\n   * Provider *yrno*: `jq`, `curl`\n* **xkb_layout.sh**: X11, XKB\n\n# Installation\n1. Install [tpm](https://github.com/tmux-plugins/tpm) and make sure it's working.\n2. Install tmux-powerline as a plugin by adding a line to `tmux.conf`:\n     ```conf\n      set -g @plugin 'erikw/tmux-powerline'\n     ```\n3. Install the plugin with `\u003cprefix\u003eI`, unless you changed [tpm's keybindings](https://github.com/tmux-plugins/tpm#key-bindings).\n   * The default powerline should already be visible now!\n4. Continue to the [Configuration](#configuration) section below.\n\n\u003e [!NOTE]\n\u003e Note that tpm plugins should be at the bottom of you `tmux.conf`. This plugin will then override some tmux settings like `status-left`, `status-right` etc. If you had already set those in your tmux config, it is a good opportunity to remove or comment those out.\n\u003e Take a look at [main.tmux](https://github.com/erikw/tmux-powerline/blob/main/main.tmux) for exactly which settings are overridden.\n\n\n# Configuration\ntmux-powerline stores the custom config, themes and segments at `$XDG_CONFIG_HOME/tmux-powerline/`.\n\nTo make the following example easier, let's assume the following:\n* `$XDG_CONFIG_HOME` has the default value of `~/.config`\n* tmux-powerline was installed to the XDG path `~/.config/tmux/plugins/tmux-powerline`\n\nAdapt the commands below if your paths differs from this.\n\n## Configuration File\nStart by generating your own configuration file:\n```shell\n~/.config/tmux/plugins/tmux-powerline/generate_config.sh\nmv ~/.config/tmux-powerline/config.sh.default ~/.config/tmux-powerline/config.sh\n$EDITOR ~/.config/tmux-powerline/config.sh\n```\n\nGo through the default config and adjust to your needs!\n\n## Custom Theme\nThe theme is specified by setting the environment variable `$TMUX_POWERLINE_THEME` in the config file above. It will use a default theme and you probably want to use your own. The default config have set the custom theme path to be `~/.config/tmux-powerline/themes/`.\n\nMake a copy of the default theme and make your own, say `my-theme`:\n```shell\nmkdir -p ~/.config/tmux-powerline/themes\ncp ~/.config/tmux/plugins/tmux-powerline/themes/default.sh ~/.config/tmux-powerline/themes/my-theme.sh\n$EDITOR ~/.config/tmux-powerline/themes/my-theme.sh\n```\n\n\u003e [!IMPORTANT]\n\u003e Remember to update the configuration file to use the new theme by setting `TMUX_POWERLINE_THEME=my-theme`\n\n## Custom Segments\nIn the same was as themes, you can create your own segments at `TMUX_POWERLINE_DIR_USER_SEGMENTS` which defaults to `~/.config/tmux-powerline/segments`.\n\nTo get started, copy an existing segment that is similar to the segment that you want to create.\n```shell\nmkdir -p ~/.config/tmux-powerline/segments\ncp ~/.config/tmux/plugins/tmux-powerline/segments/date.sh ~/.config/tmux-powerline/segments/my-segment.sh\n$EDITOR ~/.config/tmux-powerline/segments/my-segment.sh\n```\n\nNow you can add `my-segment` to your own theme!\n\nAlso see [How to make a segment](#how-to-make-a-segment) below for more details.\n\n\n# Debugging\nSome segments might not work on your system for various reasons such as missing programs or different versions not having the same options. To find out which segment is not working it may help to enable the debug setting in `~/.config/tmux-powerline/config.sh`.\nHowever this may not be enough to determine the error so you can inspect all executed bash commands (will be a long output) by doing\n\n```shell\nbash -x powerline.sh (left|right)\n```\n\nTo debug smaller portions of code, say if you think the problem lies in a specific segment, insert these lines at the top and bottom of the relevant code portions e.g. inside a function:\n\n```bash\nset -x\nexec 2\u003e/tmp/tmux-powerline.log\n\u003ccode to debug\u003e\nset +x\n```\n\nand then inspect the outputs like\n\n```shell\nless /tmp/tmux-powerline.log\ntail -f /tmp/tmux-powerline.log # or follow output like this.\n```\n\n\nYou can also enable the debug mode in your config file. Look for the `TMUX_POWERLINE_DEBUG_MODE_ENABLED` environment variable and set it to `true`.\n\nIf you can not solve the problems you can post an [issue](https://github.com/erikw/tmux-powerline/issues?state=open) and be sure to include relevant information about your system and script output (from bash -x) and/or screenshots if needed.\nBe sure to search in the [resolved issues](https://github.com/erikw/tmux-powerline/issues?page=1\u0026state=closed) section for similar problems you're experiencing before posting.\n\n\n\n## Common Problems\n### Nothing is Displayed\nYou have edited `~/.tmux.conf` but no powerline is displayed. This might be because tmux is not aware of the changes so you have to restart your tmux session or reloaded that file by typing this on the command-line (or in tmux command mode with `prefix :`)\n\n```shell\ntmux source-file ~/.tmux.conf\n```\n\n### Multiple lines in bash or no powerline in Zsh using iTerm (macOS)\nIf your tmux looks like [this](https://github.com/erikw/tmux-powerline/issues/125) then you may have to in iTerm uncheck [Unicode East Asian Ambiguous characters are wide] in Preferences -\u003e Settings -\u003e Advanced.\n\n\n# Hacking (Development)\n\u003e [!IMPORTANT]\n\u003e Please read and follow the [CONTRIBUTING.md](CONTRIBUTING.md) guidelines!\n\nThis project can only gain positively from contributions. Fork today and make your own enhancements and segments to share back!\n\n## Codespaces Devcontainer\nYou can fork this project and then start coding right away with GitHub Codespaces as this project is set up to install all development dependencies and install tmux-powerline on the devcontainer. See [devcontainer.json](.devcontainer/devcontainer.json) and [devcontainer_postCreateCommand.sh](scripts/devcontainer_postCreateCommand.sh). After starting the devcontainer, just type `tmux` in the terminal and you should see a working tmux-powerline already to start playing with.\n\n\u003e [!IMPORTANT]\n\u003e If you have set up your own dotfiles to be installed with GitHub Codespaces, and there was some tmux config files installed from your dotfiles to the devcontainer, then you might have to run this script to wipe your config in favour of the setup provided by this repo's initialization:\n\u003e \n\u003e ```shell\n\u003e ./scripts/devcontainer_postCreateCommand.sh\n\u003e ```\n\n## How To Make a Segment\nPlease section *How To Make a Segment* at [CONTRIBUTING.md](CONTRIBUTING.md#how-to-make-a-segment).\n\n\n\n# Releasing\nCreate a new version of this project by using [semver-cli](https://github.com/maykonlsf/semver-cli).\n\n```shell\nvi CHANGELOG.md\nsemver up minor\nver=$(semver get release)\ngit commit -am \"Bump version to $ver\" \u0026\u0026 git tag $ver \u0026\u0026 git push --atomic origin main $ver\n```\n\n# More tmux Plugins\nI have another tmux plugin that might interest you:\n* [tmux-dark-notify](https://github.com/erikw/tmux-dark-notify) - A plugin that make tmux's theme follow macOS dark/light mode.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferikw%2Ftmux-powerline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferikw%2Ftmux-powerline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferikw%2Ftmux-powerline/lists"}