ALTTAB(1)

πŸ“¦
version 1.8.0 Β· 8 versions
, in ubuntu stonking

πŸ’– ALTTAB(1) β€” the task switcher, but make it a whole vibe πŸ’–

okay bestie, so you know alttab? That's the manual name, that's the whole thing, and it is literally the task switcher you've been looking for. Sit down, hydrate, we're doing this. 🫢

✨ NAME ✨

alttab β€” the task switcher. that's it, that's the name. iconic behaviour honestly πŸ‘‘

🌸 SYNOPSIS 🌸

alttab [-w N] [-d N] [-sc N] [-mk str] [-kk str] [-bk str] [-pk str]
[-nk str] [-ck str] [-dk str] [-mm N] [-bm N] [-t NxM] [-i NxM] [-vp
str] [-p str] [-s N] [-theme name] [-bg color] [-fg color] [-frame
color] [-inact color] [-min color] [-bc color] [-bw N] [-font name]
[-vertical] [-sortmin] [-e] [-b N] [-ns] [-v|-vv]

like, yes, that's a lot of flags. we're getting to every single one of them, don't even worry. πŸ’…

πŸ¦‹ DESCRIPTION πŸ¦‹

So. alttab is the task switcher, and it was designed specifically for minimalistic window managers β€” or for a standalone X11 session. It's giving "built for the simple life but refuses to be boring". 🌈

Here's the thing that makes it different: a lot of simple WMs ship with a task switcher baked in, and those ones are… fine? Whatever. But alttab is not like those, because it comes with a visual interface and, highkey the best part, a convenient tactile behaviour β€” meaning the way it actually works is that it switches windows when you release the Alt key. The way that it waits for you to let go?? Obsessed. That's the whole feel. πŸ˜­πŸ’–

And despite being ✨lightweight✨ and depending only on core X11 libs β€” no extra drama, no heavy dependencies, she travels light β€” it still lets you customise both the look and the behaviour. Customisable look, customisable behaviour, tiny footprint. main character energy fr fr. 🌟

ngl if your WM's built-in switcher is giving nothing, this is the moment. the vibe check has been passed. βœ…

more coming, bestie β€” do NOT go anywhere πŸ’œ

✨ OPTIONS ✨

okay bestie so literally most of these command line options have a corresponding X resource, so go peek at doc/alttab.ad for examples πŸ’…

  • -w NUMBER β€” resource: alttab.windowmanager β€” default: autodetect, fallback to 3

Controls how alttab gets the window list and sets focus. NUMBER has to be between 0 and 3:

  • 0 β€” No WM, raw X.

Set this value manually, because it is not autodetected. Only top-level viewable children of the root window get listed. Running -w 0 under a WM is discouraged: hidden windows or windows on another desktops will not be listed; instead, some strange windows may be included. 🫣

  • 1 β€” EWMH compatible.

The compatible WM list lives in SEE ALSO below. alttab functions in xmonad (EWMH must be allowed, details in doc/wm-setup.md), i3, evilwm, xfwm4, metacity, jwm, openbox, fluxbox, icewm, enlightenment, blackbox, aewm, fvwm, sawfish, bspwm. The following WMs support EWMH only partially but work in -w 1 mode too: dwm (issue #9), matchbox (issue #34), windowmaker (issue #9), xpra (issue #37), cwm (issue #35), ctwm (issue #39), lwm (issue #40), awesome (issue #41).

  • 2 β€” Ratpoison.

Alttab uses ratpoison's own remote control capability. Also, alttab registers itself in its "unmanaged list" automatically. iconic.

  • 3 β€” Ancient WM.

The fallback, and honestly worse than 0. It searches for application windows at random nodes of the window tree (because the WM is probably reparenting) and selects only those with a name, including non-viewable ones (because the WM is probably iconifying). May cause lag 😭. Tested in twm, flwm, wm2.

  • -d NUMBER β€” resource: alttab.desktops β€” default: 0

Shows windows belonging to desktops (workspaces, groups). NUMBER has to be between 0 and 4:

  • 0 β€” Current desktop.

This is default, although in a non EWMH-compatible WM, except ratpoison, it's effectively the same as 1.

  • 1 β€” All desktops.
  • 2 β€” All desktops, excluding the special (-1) one.

In various EWMH WMs this desktop may be designed hidden or containing sticky windows. In i3, it's "scratchpad".

  • 3 β€” All desktops, excluding current and special.
  • 4 β€” Special (-1) desktop only.
  • -sc NUMBER β€” resource: alttab.screens β€” default: 1

Shows windows belonging to xrandr/xinerama screens. NUMBER has to be 0 or 1:

  • 0 β€” Current screen.

As defined according to -vp pointer or -vp focus.

  • 1 β€” All screens.

This is default.

  • -mk str β€” resource: alttab.modifier.keysym β€” default: Alt_L (i.e. Left Alt)

Keysym of the main modifier. String or number accepted. Suitable examples: Control_L, Super_L.

  • -kk str β€” resource: alttab.key.keysym β€” default: Tab

Keysym of the main key. For example, grave (aka tilde), Escape.

  • -bk str β€” resource: alttab.backscroll.keysym β€” default: any Shift, according to ShiftMask

Keysym of the backward scroll key.

  • -pk str β€” resource: alttab.prevkey.keysym β€” default: no key assigned

Keysym of the auxiliary 'previous' key. For example, Left, H.

  • -nk str β€” resource: alttab.nextkey.keysym β€” default: no key assigned

Keysym of the auxiliary 'next' key. For example, Right, L.

  • -ck str β€” resource: alttab.cancelkey.keysym β€” default: Escape

Keysym of the auxiliary 'cancel' key.

  • -dk str β€” resource: alttab.killkey.keysym β€” default: k

Keysym of the key for killing the X client to which the currently selected window belongs. πŸ’€

  • -mm NUM β€” resource: alttab.modifier.mask

OBSOLETED, guessed from -mk instead.

  • -bm NUM β€” resource: alttab.backscroll.mask

OBSOLETED, guessed from -bk instead.

  • -t NNxMM β€” resource: alttab.tile.geometry β€” default: 112x128

Size of a single tile (mini-window). If the switcher doesn't fit the viewport (-vp), the tile may be thinner.

  • -i NNxMM β€” resource: alttab.icon.geometry β€” default: 32x32

Size of icons.

  • -vp str β€” resource: alttab.viewport β€” default: focus

Limits the viewport for the switcher. The switcher always has variable size and position, but tries to never break out of the -vp container, while -p specifies position relative to this container. Together these options allow for WM-independent multi-monitor support ✨. Possible values for -vp:

  • focus: in multihead configuration, the monitor which shows the largest part of the currently focused window. If this part is shared with other monitors, then the smallest of these monitors is chosen. In single head configuration: the geometry of the default root window.
  • pointer: the monitor which has the mouse pointer, otherwise the same as focus.

The "multihead" above means more than one active XRANDR output. They are detected at runtime, so hopefully monitors may be attached/detached without restarting alttab 🧚.

  • total: the geometry of the default root window.

If you specify this in a tiling multihead configuration, then the switcher will be drawn relative to the entire combined screen, crossing monitors' borders.

  • WxH+X+Y: specific position relative to the default root window.

This allows for static manual bounding if XRANDR detection fails. Suppose the X root window spans over two 2560Ρ…1440 monitors, resulting in a combined screen of 5120x1440 size. Then the switcher may be positioned at the center of the right monitor with -vp 2560x1440+2560+0 -p center.

  • -p str β€” resource: alttab.position β€” default: center

Position of switcher: "center", "none" or a specific position relative to the upper left corner of the viewport, in the form +X+Y.

  • -s NUMBER β€” resource: alttab.icon.source β€” default: 2

Source of icons. NUMBER has to be between 0 and 5:

  • 0 β€” Use icons from X11 window attributes only.
  • 1 β€” Load the icon from a file if it's not found in the window attributes.

Alttab searches for PNG and XPM icons in $XDG_DATA_DIRS and also under:

/usr/share/icons
/usr/local/share/icons
~/.icons
~/.local/share/icons

Directory structure should obey the freedesktop standard, but desktop files are ignored, and instead the file name is expected to be equal to the application class. That is, if alttab doesn't recognize an icon for a window of class foo, as obtained by 'xprop WM_CLASS', then just drop a 32x32 icon into /usr/local/share/icons/hicolor/32x32/apps/foo.png πŸŽ€.

Also, alttab scans for icons in legacy directories without the freedesktop directory structure:

/usr/share/pixmaps
~/.local/share/pixmaps
  • 2 β€” Prefer the icon from a file when it matches the requested size better (see the -i option).
  • 3 β€” Use icons from files only.
  • 4 β€” Don't draw icons.
  • 5 β€” Prefer the icon from X11 window attributes when it matches the requested size better.
  • -theme name β€” resource: alttab.theme β€” default: hicolor

Desktop theme for application icons. Used when -s is 1, 2 or 3.

The following six options accept color names or #rrggbb. The special value _rnd_low or _rnd_high produces a random color from the lower or upper RGB space respectively 🌈.

  • -bg color β€” resource: alttab.background β€” default: black

Tile background color.

  • -fg color β€” resource: alttab.foreground β€” default: grey

Foreground color.

  • -frame color β€” resource: alttab.framecolor β€” default: #a0abab

Color of the frame around the selected tile.

  • -inact color β€” resource: alttab.inactcolor β€” default: foreground color

Color of the frame around non-selected tiles.

  • -min color β€” resource: alttab.mincolor β€” default: frame color

In a stacking WM, the color of the frame for minimized windows.

  • -bc color β€” resource: alttab.bordercolor β€” default: black

Color of the extra border around the entire switcher. This border may look redundant. Do not confuse it with -frame.

  • -bw N β€” resource: alttab.borderwidth β€” default: 0 (no extra border)

Width of the extra border mentioned above.

  • -font name β€” resource: alttab.font β€” default: xft:sans-10

Label font name in the format xft:fontconfig_pattern, like in emacs and rxvt. See SEE ALSO for the fontconfig pattern. It's neither a GTK font pattern nor a legacy XLFD.

Your Xresources database probably already has *background, *foreground or *font wildcard definitions, which alttab will obey. Precedence order (preferred first):

  1. alttab.font resource,
  2. -font option,
  3. wildcard resource like *font in xfd: format.
  • -vertical β€” resource: alttab.vertical β€” default: no

Vertical layout.

  • -sortmin β€” resource: alttab.sortmin β€” default: no

Sort minimized windows last.

  • -e β€” resource: alttab.keep β€” default: no

On release of Alt, don't switch β€” keep showing the switcher. This allows for an external call: xdotool key alt+Tab . See doc/mobile.md for possible usage πŸ‘€.

  • -b NUMBER β€” resource: alttab.bottomline β€” default: 0

Content of the auxiliary line at the bottom of each tile. NUMBER has to be between 0 and 2:

  • 0 β€” Empty.
  • 1 β€” Name of the desktop to which the window belongs.
  • 2 β€” User name. Requires the _NET_WM_PID freedesktop property and the /proc file system.
  • -ns β€” resource: alttab.noskiptaskbar β€” default: no

Ignore an application's request of not including a window on a taskbar.

  • -v, -vv β€” resource: no β€” default: silent

Verbosity.

  • -h β€” short help

🌸 CAVEATS 🌸

Run alttab after the WM, or autodetection will fail. no cap, it really will πŸ™ˆ

πŸ‘‘ AUTHOR πŸ‘‘

Copyright 2017-2026 Alexander Kulak <sa-dev AT odd POINT systems>.

πŸ› REPORTING BUGS πŸ›

Please report issues on github https://github.com/sagb/alttab/issues. bestie we wanna hear it 🫢

πŸ’– SEE ALSO πŸ’–

EWMH compatible WM list https://en.wikipedia.org/wiki/Extended_Window_Manager_Hints#List_of_window_managers_that_support_Extended_Window_Manager_Hints.

Description of fontconfig pattern https://www.freedesktop.org/software/fontconfig/fontconfig-user.html.

and that's a wrap, bestie πŸ’… this whole thing is from the ALTTAB(1) page, July 2026 edition β€” go forth and tab through your windows like the main character you are πŸ‘‘βœ¨

πŸ“¦ where this page comes from