README.md
1<p align="center">
2 <img src="banner.png" alt="Polybar">
3</p>
4
5<p align="center">
6A fast and easy-to-use tool for creating status bars.
7</p>
8
9<p align="center">
10<a href="https://github.com/polybar/polybar/releases"><img src="https://img.shields.io/github/release/polybar/polybar.svg"></a>
11<a href="https://github.com/polybar/polybar/actions?query=workflow%3ACI"><img src="https://github.com/polybar/polybar/workflows/CI/badge.svg"></a>
12<a href="https://polybar.readthedocs.io"><img src="https://readthedocs.org/projects/polybar/badge/?version=latest"></a>
13<a href="https://gitter.im/polybar/polybar"><img src="https://badges.gitter.im/polybar/polybar.svg"></a>
14<a href="https://codecov.io/gh/polybar/polybar/branch/master"><img src="https://codecov.io/gh/polybar/polybar/branch/master/graph/badge.svg"></a>
15<a href="https://github.com/polybar/polybar/blob/master/LICENSE"><img src="https://img.shields.io/github/license/polybar/polybar.svg"></a>
16<a href="https://www.codetriage.com/polybar/polybar"><img src="https://www.codetriage.com/polybar/polybar/badges/users.svg"></a>
17</p>
18
19**Polybar** aims to help users build beautiful and highly customizable status bars
20for their desktop environment, without the need of having a black belt in shell scripting.
21Here are a few screenshots showing you what it can look like:
22
23[](https://i.imgur.com/xvlw9iH.png)
24[](https://i.imgur.com/cYQOuRr.png)
25[](https://i.imgur.com/A6spiZZ.png)
26[](https://i.imgur.com/TY5a5r9.png)
27
28You can find polybar configs for these example images (and other configs) [here](https://github.com/jaagr/dots/tree/master/.local/etc/themer/themes).
29
30## Table of Contents
31
32* [Introduction](#introduction)
33* [Getting Help](#getting-help)
34* [Contributing](#contributing)
35* [Getting started](#getting-started)
36 * [Installation](#installation)
37 * [Configuration](#configuration)
38 * [Running](#running)
39* [Community](#community)
40* [Contributors](#contributors)
41* [License](#license)
42
43
44## Introduction
45
46The main purpose of **Polybar** is to help users create awesome status bars.
47It has built-in functionality to display information about the most commonly used services.
48Some of the services included so far:
49
50- Systray icons
51- Window title
52- Playback controls and status display for [MPD](https://www.musicpd.org/) using [libmpdclient](https://www.musicpd.org/libs/libmpdclient/)
53- [ALSA](https://www.alsa-project.org/main/index.php/Main_Page) and [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/) volume controls
54- Workspace and desktop panel for [bspwm](https://github.com/baskerville/bspwm) and [i3](https://github.com/i3/i3)
55- Workspace module for [EWMH compliant](https://specifications.freedesktop.org/wm-spec/wm-spec-1.3.html#idm140130320786080) window managers
56- Keyboard layout and indicator status
57- CPU and memory load indicator
58- Battery display
59- Network connection details
60- Backlight level
61- Date and time label
62- Time-based shell script execution
63- Command output tailing
64- User-defined menu tree
65- Inter-process messaging
66- And more...
67
68[See the wiki for more details](https://github.com/polybar/polybar/wiki).
69
70## Getting Help
71
72If you find yourself stuck, have a look at our [Support](SUPPORT.md) page for resources where you can find help.
73
74## Contributing
75
76Read our [contributing guidelines](CONTRIBUTING.md) for how to get started with contributing to polybar.
77
78## Getting started
79
80<a href="https://repology.org/metapackage/polybar">
81 <img src="https://repology.org/badge/vertical-allrepos/polybar.svg" alt="Packaging status" align="right">
82</a>
83
84Polybar was already packaged for the distros listed below.
85If you can't find your distro here, you will have to [build from source](https://github.com/polybar/polybar/wiki/Compiling).
86
87If you are using **Debian** (unstable or testing), you can install [polybar](https://tracker.debian.org/pkg/polybar) using `sudo apt install polybar`.
88If you are using **Debian** (buster/stable), you need to enable [backports](https://wiki.debian.org/Backports) and then install using `sudo apt -t buster-backports install polybar`.
89
90If you are using **Arch Linux**, you can install the AUR package [polybar-git](https://aur.archlinux.org/packages/polybar-git/) to get the latest version, or
91[polybar](https://aur.archlinux.org/packages/polybar/) for the latest stable release.
92
93If you are using **Void Linux**, you can install [polybar](https://github.com/void-linux/void-packages/blob/master/srcpkgs/polybar/template) using `xbps-install -S polybar`.
94
95If you are using **NixOS**, polybar is available in both the stable and unstable channels and can be installed with the command `nix-env -iA nixos.polybar`.
96
97If you are using **Slackware**, polybar is available from the [SlackBuilds](https://slackbuilds.org/repository/14.2/desktop/polybar/) repository.
98
99If you are using **Source Mage GNU/Linux**, polybar spell is available in test grimoire and can be installed via `cast polybar`.
100
101If you are using **openSUSE**, polybar is available from [OBS](https://build.opensuse.org/package/show/X11:Utilities/polybar/) repository. Package is available for openSUSE Leap 15.1, openSUSE Leap 15.2 and Tumbleweed.
102
103If you are using **FreeBSD**, [polybar](https://svnweb.freebsd.org/ports/head/x11/polybar/) can be installed using `pkg install polybar`. Make sure you are using the `latest` package branch.
104
105If you are using **Gentoo**, both release and git-master versions are available in the [main](https://packages.gentoo.org/packages/x11-misc/polybar) repository.
106
107If you are using **Fedora**, you can install [polybar](https://src.fedoraproject.org/rpms/polybar) using `sudo dnf install polybar`.
108
109### Installation
110
111The [compiling page](https://github.com/polybar/polybar/wiki/Compiling) on the
112wiki describes all steps necessary to build and install polybar.
113
114### Configuration
115
116Details on how to setup and configure the bar and each module have been moved to [the wiki](https://github.com/polybar/polybar/wiki/Configuration).
117
118#### Install the example configuration
119Run the following inside the build directory:
120~~~ sh
121$ make userconfig
122~~~
123Or you can copy the example config from `/usr/share/doc/polybar/config` or ` /usr/local/share/doc/polybar/config` (depending on your install parameters)
124
125#### Launch the example bar
126 ~~~ sh
127 $ polybar example
128 ~~~
129
130### Running
131
132[See the wiki for details on how to run polybar](https://github.com/polybar/polybar/wiki).
133
134## Community
135Want to get in touch?
136
137* Join our Gitter room at [gitter.im/polybar/polybar](https://gitter.im/polybar/polybar)
138* We have our own subreddit at [r/polybar](https://www.reddit.com/r/polybar).
139* Chat with us in the `#polybar` IRC channel on the `chat.freenode.net` server.
140
141## Contributors
142
143### Owner
144* Michael Carlberg [**@jaagr**](https://github.com/jaagr/)
145
146### Maintainers
147* [**@NBonaparte**](https://github.com/NBonaparte)
148* Chase Geigle [**@skystrife**](https://github.com/skystrife)
149* Patrick Ziegler [**@patrick96**](https://github.com/patrick96)
150
151### Logo Design by
152* [**@Tobaloidee**](https://github.com/Tobaloidee)
153
154
155### [All Contributors](https://github.com/polybar/polybar/graphs/contributors)
156
157## License
158
159Polybar is licensed under the MIT license. [See LICENSE for more information](https://github.com/polybar/polybar/blob/master/LICENSE).
160
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
