Publicación
- 6 min read
Polybar: guía de instalación mínima de Polybar para Linux

Casi todos los tutoriales de polybar asumen que ya vives en un window manager de mosaico y sabes qué es una sección de barra. Este no. Instalas polybar, pegas un archivo de configuración, la ejecutas y haces que sobreviva a un reinicio.
Dos cosas antes de empezar, porque ahorran horas:
- Polybar es solo para X11. En Wayland (sway, Hyprland, GNOME en Wayland) no funciona. Ahí la alternativa habitual es Waybar.
- El config de abajo usa el módulo de bspwm, así que asume bspwm. Si usas i3 hay un cambio de una línea más adelante.
Al terminar tendrás una barra de 28 píxeles con los workspaces a la izquierda, la fecha al centro y CPU, RAM, batería, wifi, volumen y bandeja del sistema a la derecha.
Instalación
Elige tu distribución.
Arch Linux:
sudo pacman -S polybar
Debian y Ubuntu (en Ubuntu el paquete está en universe):
sudo apt update && sudo apt install polybar
Fedora:
sudo dnf install polybar
openSUSE:
sudo zypper install polybar
Void:
sudo xbps-install -S polybar
Alpine:
sudo apk add polybar
NixOS, o cualquier distro con Nix instalado:
nix profile install nixpkgs#polybar
Comprueba que quedó instalada:
polybar --version
Si tu distribución no la empaqueta, compila desde el código fuente. La página de compilación del wiki lista las dependencias, que en la práctica son cmake, pkg-config, python3 y las librerías de xcb.
Dónde vive el archivo de configuración
Polybar lee la primera ruta que exista, en este orden:
$XDG_CONFIG_HOME/polybar/config
$XDG_CONFIG_HOME/polybar/config.ini
$HOME/.config/polybar/config
$HOME/.config/polybar/config.ini
/etc/xdg/polybar/config.ini
/etc/polybar/config.ini
En una instalación normal eso significa ~/.config/polybar/config.ini. Créalo:
mkdir -p ~/.config/polybar
$EDITOR ~/.config/polybar/config.ini
Si tu distro ya dejó un archivo en /etc/polybar/config.ini, no edites ese. Las actualizaciones del paquete lo sobrescriben. Cópialo a tu carpeta personal y trabaja ahí.
El config
Pega esto tal cual:
[bar/main]
width=100%
height=28
radius=0
fixed-center=true
background=#222222
foreground=#eeeeee
line-size=2
border-size=0
padding-left=1
padding-right=1
module-margin=1
font-0=sans:size=10;2
modules-left=bspwm
modules-center=date
modules-right=cpu memory battery wlan pulseaudio tray
#tray-position=right
#tray-padding=2
cursor-click=pointer
cursor-scroll=ns-resize
[module/bspwm]
type=internal/bspwm
label-focused=%name%
label-focused-foreground=#222222
label-focused-background=#eeeeee
label-focused-padding=2
label-occupied=%name%
label-occupied-foreground=#eeeeee
label-occupied-padding=2
label-urgent=%name%
label-urgent-foreground=#ffffff
label-urgent-background=#cc3333
label-urgent-padding=2
label-empty=%name%
label-empty-foreground=#666666
label-empty-padding=2
[module/cpu]
type=internal/cpu
interval=2
format-prefix="CPU"
format-prefix-padding=1
label=%percentage:2%%
[module/memory]
type=internal/memory
interval=2
format-prefix="RAM"
format-prefix-padding=1
label=%percentage_used:2%%
[module/battery]
type=internal/battery
battery=BAT1
adapter=ACAD
poll-interval=5
format-charging=<label-charging>
format-discharging=<label-discharging>
format-full=<label-full>
label-charging="BAT %percentage%%"
label-discharging="BAT %percentage%%"
label-full="BAT FULL"
[module/wlan]
type=internal/network
interface=wlan0
interval=3
format-connected=<label-connected>
format-disconnected=<label-disconnected>
label-connected="WiFi %essid%"
label-disconnected="WiFi OFF"
[module/pulseaudio]
type=internal/pulseaudio
format-volume=<label-volume>
format-muted=<label-muted>
label-volume="VOL %percentage%%"
label-muted="MUTE"
[module/date]
type=internal/date
interval=1
date=%d/%m/%Y
time=%H:%M
label=%date% %time%
[module/tray]
type=internal/tray
tray-spacing=4
Una comprobación de versión antes de seguir, porque cambia las líneas de la bandeja. [module/tray] con type=internal/tray necesita polybar 3.7 o superior. Debian 12 y Ubuntu 24.04 todavía traen 3.6.3, donde ese tipo de módulo no existe: polybar escribe un error en el log y la bandeja simplemente no aparece nunca. En 3.6 y anteriores, quita tray de modules-right y descomenta tray-position=right. Para eso están exactamente esas dos líneas antiguas del principio. Confirma tu versión con polybar --version.
Los cuatro valores que van a estar mal en tu máquina
Polybar no se cae cuando un módulo apunta a hardware que no existe. El módulo simplemente desaparece, y tú te quedas veinte minutos pensando que polybar está roto. Revisa esto antes de quejarte de cualquier otra cosa.
Batería y adaptador. battery=BAT1 y adapter=ACAD son nombres de archivos en sysfs. Mira los tuyos:
ls /sys/class/power_supply/
Las parejas habituales son BAT0 con AC, o BAT1 con ADP1. Si tu portátil tiene dos baterías verás BAT0 y BAT1.
Interfaz de red. interface=wlan0 es el esquema de nombres antiguo. Comprueba el nombre real:
ip -br link
Los sistemas modernos te dan algo como wlp2s0, o enp3s0 para ethernet. Pon la inalámbrica en interface=.
El módulo de workspaces. modules-left=bspwm es el módulo de bspwm. Si usas i3, reemplaza el bloque [module/bspwm] completo por:
[module/i3]
type=internal/i3
format=<label-state> <label-mode>
y cambia modules-left=bspwm por modules-left=i3. En cualquier otro window manager, quítalo de modules-left.
La fuente. font-0=sans:size=10;2 se resuelve por fontconfig, así que funciona en casi todas partes, pero sans no trae iconos. Si más adelante quieres glifos de Nerd Font, declara una fuente parcheada como segunda entrada:
font-0=JetBrainsMono Nerd Font:size=10;2
font-1=JetBrainsMono Nerd Font:style=Bold:size=10;2
Mira qué tienes instalado con fc-list : family | sort -u.
Ejecutarla
polybar main
main es el nombre que va después de bar/ en [bar/main]. Si tu config define una sola barra, polybar a secas también funciona.
Flags que vas a usar de verdad:
polybar -mlista los monitores conectados.polybar -Mincluye los clonados.polybar -l info mainimprime el log. Ahí aparecen mensajes comoBattery BAT1 not found, y es la vía más rápida para saber por qué no sale la barra.polybar -r mainrecarga sola cuando guardas el archivo de configuración, que es mucho mejor que matar el proceso y volver a lanzarlo mientras ajustas colores.
El log no es opcional. Casi todas las preguntas de “la barra no aparece” se responden con una línea de ahí.
Arrancarla en cada encendido
Polybar es un cliente X normal. No necesita systemd, necesita arrancar después del window manager. Dónde lo pongas depende de tu WM.
bspwm. Añade esto a ~/.config/bspwm/bspwmrc, que debe ser ejecutable (chmod +x ~/.config/bspwm/bspwmrc):
pgrep -x polybar > /dev/null || polybar main &
El pgrep importa. Sin él, cada recarga de bspwm lanza otra polybar, y a la tercera recarga tienes tres barras apiladas una encima de otra sin entender por qué.
i3. En ~/.config/i3/config:
exec_always --no-startup-id polybar main
Usa exec_always, no exec. exec corre una sola vez al iniciar sesión, así que un i3-msg restart te deja sin barra.
Openbox. En ~/.config/openbox/autostart:
polybar main &
X plano con startx. En ~/.xinitrc, antes de la línea que arranca tu WM:
polybar main &
exec bspwm
Varios monitores. Lanza un proceso por monitor. Añade monitor = ${env:MONITOR:} a [bar/main] y recorre la lista:
polybar -m | cut -d: -f1 | while read -r m; do
MONITOR="$m" polybar main &
done
Cuando algo falla
La barra no aparece nunca. Ejecuta polybar -l info main en una terminal. O la ruta del config está mal, o la sección de barra no se llama main.
La barra tapa las ventanas, o las ventanas tapan la barra. Con bspwm añade wm-restack = bspwm a [bar/main]. Algunos window managers minimalistas necesitan override-redirect = true y un margen configurado de su lado.
Falta un módulo. El valor del que depende está mal: nombre de batería, de adaptador, de interfaz o el socket del window manager. El log te dice cuál.
La bandeja está vacía. Polybar dibuja iconos de bandeja XEmbed. Las aplicaciones que solo publican elementos StatusNotifier necesitan un puente como snixembed para aparecer ahí.
El módulo de volumen no muestra nada. Necesita PulseAudio, o PipeWire con pipewire-pulse. Compruébalo con pactl info.
Los iconos salen como cuadrados vacíos. Tu fuente no tiene esos glifos. Instala una Nerd Font y añádela como font-0.
El texto se ve mal o cortado. Revisa dpi-x y dpi-y en [bar/main]. El ;2 al final de font-0 es el desplazamiento vertical de esa fuente, y es lo que mantiene el texto centrado dentro de la altura de la barra.
Eso es toda la barra
Tienes un config de 60 líneas que entiendes línea por línea, que es de lo que se trataba. Un rice copiado de una captura y que no puedes depurar es peor que una barra simple que sí controlas. Desde aquí, el siguiente paso útil es añadir un módulo a la vez, recargar con polybar -r main después de cada cambio y leer el log cuando un módulo se niegue a aparecer.
El wiki de polybar tiene una página por módulo. Los que más uso son internal/backlight, internal/temperature e internal/script, que es cómo metes en la barra cualquier otra cosa que quieras.