Introduction to Polybar
Polybar has become one of the most popular options among Linux users looking for a light, highly configurable and visually attractive state bar. Unlike other simpler solutions, Polybar allows you to create multiple bars, place modules in any position and adapt the appearance by using configuration files written in a simple but powerful language. In this article we will explore from basic installation to advanced customization, showing practical examples that will help you get the most out of this tool.
What is Polybar and why use it?
Polybar is a status bar written in C and designed to operate with the most common window managers, such as i3, Sway, bspwm, OpenBox and many others. Its main advantage is the separation between logic and presentation: modules that show information (clock, CPU use, network, volume, etc.) are independent of the design, allowing to change colors, sources, spacing and animations without touching the underlying code. In addition, Polybar supports multiple monitors, vertical or horizontal bar, and can release custom scripts to show any data you can think of.
Installation in the most used distributions
Before you start the configuration, you need to install Polybar. Fortunately, most major distributions include it in their official repositories.
- Ubuntu and Debian:
sudo apt install polybar - Arch Linux:
sudo pacman -S polybar - Fedora:
sudo dnf install polybar - openSUSE:
sudo zypper install polybar
If you prefer to compile from the source code to get the latest version, the official repository in GitHub provides clear instructions and a compilation script that depends on packages such as cmake, pkg-config, libxcb, xproto, xcb-util, xcb-util-image, xcb-util-wm, xcb-util-xrm, i3-wm (optional) and libmpdclient.
Basic structure of the configuration file
The main configuration file is found in~/.config/polybar/config(or~/.config/polybar/config.iniin some versions). This file is divided into sections that define colors, sources, modules and bars.
Section [colors]
This section defines the colors that will be used along the bar. For example:
[colors] background = # 2222foreground = # ddddddprimary = # ff55secondary = # 55ffff
The values can be expressed in hexadecimal format, RGB or using color names recognized by X11.
Section [bar / example]
Each bar is defined under a section whose name begins withbar/. Within it are specified attributes such as position, size, source and modules to be shown to the left, center and right.
[bar / example] width = 100% height = 27offset-x = 0offsety = 0radius = 0fixed-center = truebackground = ${colors.background} foreground = ${colors.foreground} font-0 = JetBrains Mono: size = 10: antialias = true; 0font-1 = Font Awesome 5 Free: size = 10: antialias = true; 0modules-left = xwindowmodules-center = date modules-right = cpu memory wlan volume battery bring -position = righttra-pating = 2
In this example, the bar occupies the full width of the screen, has a height of 27 pixels and shows the name of the active window on the left, the date in the center and several system indicators on the right.
Most useful modules and how to configure them
Polybar includes a wide variety of integrated modules. Some of the most used are:
xwindow: shows the title of the window currently focused.date: shows the date and time with customizable format.cpu: shows the use of CPU as a percentage.memory: shows RAM consumption.wlan: shows the state of wireless connection and signal intensity.volume: controls the sound volume and shows the current level.battery: shows the battery load level (useful in laptops).mpd: integrates the Music Player Daemon.custom/script: allows you to run any script and show your output.
Each module has its own configuration options. For example, the date module can be customised as follows:
[module / date] type = internal / dateinterval = 5format-prefix = '📅 'format-prefix-foreground = ${colors.secondary} date-alt = '% Y-% m-% d% H:% M:% S'
The CPU module can be shown with a color gradient according to use:
[module / cpu] type = internal / cpuinterval = 2format-prefix = '💡 'format-prefix-foreground = ${colors.primary} label =% percentage% label-background = ${colors.background}
Visual themes and styles
One of Polybar's greatest strengths is the ease of changing its appearance through themes. A theme is only a set of values for the color, source and spaced sections. Many users share their topics in repositories likepolybar-themesin GitHub.
To apply a theme, simply copy the contents of the fileconfig.iniof the theme chosen to your own~/.config/polybar/configand reboot Polybar. Some popular themes include:
Forest: green and brown colors that remember a forest.Nord: cold palette inspired by the Nord theme, ideal for development environments.Material: based on Google's material design, with shadows and living accents.
If you prefer to create your own theme, start by defining a color palette in the section[colors], choose a legible source (e.g. JetBrains Mono, Fira Code or Noto Sans) and adjust the space between modules by using the parametersspacingandmodule-margin.
Advanced configuration: multiple monitors and Wayland
Polybar works in both X11 and Wayland, although Wayland requires the use of a compatible composer such as Sway or Hyprland. To specify in which monitor a bar should appear, the variable is usedmonitorinside the bar section.
[bar / primary] monitor = HDMI-1width = 100% height = 28
In multi-monitor settings, you can create a bar for each output by simply doubling the sectionbar/and changing the value ofmonitor. In addition, Polybar supports the vertical bar by settingorientation = verticaland adjusting the width and height as necessary.
In Wayland, some modules that depend on X11 (such asxwindow) may not be available; instead, specific Wayland modules may be used assway/workspaceorhyprland/workspaceaccording to the composer you use.
Communication via IPC and polybar-msg
Polybar includes a process-to-process communication interface (IPC) that allows you to send commands to an executing instance without reboot. The commandpolybar-msgis the most common tool for it.
Some useful examples:
- Reset a specific bar:
polybar-msg cmd restart - Show or hide the bar:
polybar-msg cmd showorpolybar-msg cmd hide - Update a module in real time:
polybar-msg hook module-name 1where the number corresponds to the hook identifier defined in the configuration. - Get information about the executing body:
polybar-msg -p /tmp/polybar-mypid.ipc cmd version
To enable the IPC, make sure the bar section includesenable-ipc = true. Then the socket is created in the time route indicated by the environment variableXDG_RUNTIME_DIRor/tmp.
Custom scripts and the custom / script module
One of the most powerful ways to extend Polybar is through the modulecustom/script. This module runs a command or script in a defined interval and shows its output in the bar.
Example of a script showing CPU temperature:
[module / cpu-temp] type = custom / scriptexec = sensors | awk '/ Core 0 / {print $3} 'interval = 5format-prefix ='🌡️ 'format-prefix-foreground = ${colors.primary}
Another useful example is a script that indicates if there are outstanding updates in an Arch-based system:
[module / updates] type = custom / scriptelecc = checkupdates | wc -linterval = 300format-prefix = '📦 'format-prefix-foreground = ${colors.secondary} label =% output%
Remember that scripts must return only text; any error output will be hidden unless you explicitly redirectstderrastdout. In addition, you can use the variableclick-left, click-rightorclick-middleto associate actions to the clicks on the module.
Automatic launch and instance management
For Polybar to start along with your session, you can add a line to your window manager autostart file or file~/.xinitrc.
In i3, for example, is added to the file~/.config/i3/config:
exec _ always --no-startup-id polybar topbarexec _ always --no-startup-id polybar bottombar
In Sway, syntax is similar:
exec _ always --no-startup-id polybar topbarexec _ always --no-startup-id polybar bottombar
If you prefer to use a launch script to close previous instances and launch new ones, you can create a file~/.config/polybar/launch.shwith the following content:
#! / usr / bin / env bash # Finish bars already in execution $UID -x polybar > / dev / null; do sleep 0.5; do # Throw the desired bars aspolybar topbar & polybar bottombar &
Then make it executable withchmod +x ~/.config/polybar/launch.shAnd add it to your autostart.
Common problem solution
If when you start Polybar you see errors in the terminal, check the following points:
- Source not found:Make sure the source name and route are correct. You can list the available sources with
fc-list. - Unrecognized module:verify that the name of the module matches exactly those available in the documentation (
man polybaror the official wiki). - Colors not applicable:check that there are no syntax errors in the section
[colors](e.g. lack of point and coma or use of unallowed characters). - Barra does not appear on the right monitor:use the variable
monitorwithin the bar section to specify the output name (can be obtained withxrandrin X11 orwlr-randrin Wayland). - The script module does not show output:verify that the script returns standard text and that the path is absolute or relative to the home directory. Add
exec = /ruta/al/script.shand test the script manually in the terminal.
Conclusion
Polybar offers a unique combination of flexibility, low resource consumption and an aesthetic that can be adapted to any workflow. From a simple watch bar and CPU use to a complete panel with multiple modules, custom scripts and elaborate themes, the tool is adjusted to both beginners and advanced users who want to have full control over their Linux desktop environment. We invite you to experiment with the settings shown, explore community themes and create your own bar that reflects exactly what you need to see at every moment.
