evilwm(1)

📦
version 1.5 · 5 versions
, in ubuntu stonking

💖 evilwm(1) — the manual page rewrite bestie edition 💖

okay so literally welcome to the UNIX manual page for evilwm, and yes it's the General Commands Manual one. grab a snack. we're doing this. 🍓

✨ NAME ✨

evilwm — minimalist window manager for X11 👑

🫶 SYNOPSIS 🫶

evilwm [OPTION]

🌸 DESCRIPTION 🌸

evilwm is a minimalist window manager for the X Window System. it's giving less is more, and honestly? it ate.

the way that it does this: it features plenty of reconfigurable mouse and keyboard controls while providing a clean display, uncluttered by less useful window furniture (like title bars). no title bars. no drama. just vibes. ✨

💅 OPTIONS 💅

  • --display display — specifies the X display to run on. usually this can be inferred from the DISPLAY environment variable. lowkey it usually just knows. 🔮
  • --term termprog — specifies an alternative program to run when spawning a new terminal (defaults to xterm, or x-terminal-emulator in Debian). separate arguments with whitespace, and escape needed whitespace with a backslash. remember that special characters will also need to be protected from the shell — yes really, protect them, the shell is nosy. 🙈
  • --fn fontname — specify a font to use when resizing or displaying window titles.
  • --fg colour
  • --fc colour
  • --bg colour

frame colour of currently active, fixed active, and inactive windows respectively. either specify an X11 colour name like goldenrod, or a hex triplet like #DAA520. pick your palette, bestie 🎨

  • --bw borderwidth — width of window borders in pixels.
  • --snap distance — enable snap-to-border support. distance is the proximity in pixels to snap to. it just... glides into place. iconic. 🧲
  • --wholescreen — ignore monitor geometry and use the whole screen dimensions. this is the old behaviour from before multi-monitor support was implemented, and may still be useful, eg when one large monitor is driven from multiple outputs. throwback behaviour, but make it functional. 💫
  • --numvdesks columns[x*rows*] — virtual desktop layout, defaulting to 8x1. any more than eight virtual desktops will only be accessible by pagers or using Control+Alt+(Left/Right/Up/Down). so like, plan accordingly. 🗂️
  • --nosoliddrag — draw a window outline while moving or resizing. (ghost window mode. spooky. ethereal. 👻)
  • --mask1 modifier[+modifier]
  • --mask2 modifier[+modifier]
  • --altmask modifier[+modifier]

override the default keyboard modifiers used to grab keys for window manager functionality.

mask1 is used for most keyboard controls (default: control+alt), and mask2 is used for mouse button controls and cycling windows (default: alt). altmask is used to modify the behaviour of certain controls (default: shift). modifiers may be separated with + signs. valid modifiers are 'shift', 'control', 'alt', 'mod1'–'mod5'. (that's an en dash situation, iykyk.)

  • --bind key[+modifier]=[function[,flag]] — bind a key pressed with specified modifiers to a window manager function. key is an X11 keysym name, modifiers are as above, but may also include 'mask1', 'mask2' and 'altmask' to refer to the globally-configured combinations. see FUNCTIONS for a list of available functions and the flags they recognise. if function is empty, a bind is removed. ✂️
  • --bind button=[function[,flag]] — bind a mouse button to a window manager function. while modifiers can be specified, they will be ignored; the button on its own will trigger if pressed within a window's frame, or with 'mask2' held anywhere within a window. function and flags is as with key binds above. valid buttons are 'button1'–'button5'.
  • --app name/class — match an application by instance name and class (for help in finding these, use the xprop tool to extract the WM_CLASS property).

subsequent --geometry, --dock, --vdesk and --fixed options will apply to this match. so basically you set up the match once and everything after it sticks to it 🫶

  • -g, --geometry geometry — apply a geometry (using a standard X geometry string) to applications matching the last --app.
  • --ignore-position — ignores the user-specified position for a matched application. useful for some applications which abuse these hints to centre themselves without the user asking for it. rude apps being rude, we're ignoring them. 💀
  • --ignore-border — ignores the application-specified border width and use the default.
  • --dock — specify that application should be considered to be a dock, even if it lacks the appropriate property.
  • -v, --vdesk column[,row] — specify a default virtual desktop for applications matching the last --app. if row is not specified, column may instead refer to an absolute virtual desktop number (ignoring layout). note that column, row and absolute virtual desktop numbers are counted from zero. yes bestie, from zero. programmers. what can you do. 😭
  • -f, --fixed — specify that application is to start with a fixed client window.
  • -h, --help — show help
  • -V, --version — show program version

evilwm will also read options, one per line, from a file called .evilwmrc in the user's home directory. options listed in a configuration file should omit the leading dash(es). options specified on the command line override those found in the configuration file. (command line wins. main character energy. 👑)

🌈 USAGE 🌈

In evilwm, the focus follows the mouse pointer, and focus is not lost if you stray onto the root window. the current window border is shaded gold (unless it is fixed, in which case blue), with other windows left as a dark grey. truly a colour story. 💛💙🩶

You can use the mouse to manipulate windows either by click/dragging the single-pixel border (easier when they align with a screen edge), or by holding down Alt and doing so anywhere in the window. the controls are:

  • Button 1 — Move window. 🚚
  • Button 2 — Resize window. 📐
  • Button 3 — Lower window. ⬇️

Most keyboard controls are used by holding down Control and Alt, then pressing a key. available functions are:

  • Return — Spawn new terminal. 🖥️
  • Escape — Delete current window. hold Shift as well to force kill a client. (nuclear option, no cap.)
  • Insert — Lower current window.
  • H, J, K, L — Move window left, down, up or right (16 pixels). holding Shift resizes the window instead.
  • Y, U, B, N — Move window to the top-left, top-right, bottom-left or bottom-right of the current monitor. corner girlies rise 🦋
  • I — Show information about current window.
  • Equals — Maximise current window vertically on current monitor (toggle). holding Shift toggles horizontal maximization.
  • X — Maximise current window to current monitor (toggle).
  • D — Toggle visible state of docks, eg pagers and launch bars.

If compiled with virtual desktop support, these functions are also available:

  • F — Fix or unfix current window. fixed windows remain visible when you switch virtual desktop. they simply refuse to leave. 👑
  • 1—8 — Switch to specific virtual desktop (internally, desktops are numbered from zero, so this actually switches to desktops 0—7; this only becomes important if you use application matching).
  • Left — Switch one virtual desktop to the left.
  • Right — Switch one virtual desktop to the right.
  • Up — Switch one virtual desktop up (if more than one row was specified).
  • Down — Switch one virtual desktop down (if more than one row was specified).
  • A — Switch to the previously selected virtual desktop. (it's giving "go back, i forgot something" 🏃‍♀️)

In addition to the above, Alt+Tab can be used to cycle through windows.

To make evilwm reread its config, send a HUP signal to the process. to make it quit, kill it, ie send a TERM signal. that's it, that's the goodbye. 👋

🔥 FUNCTIONS 🔥

The keyboard and mouse button controls can be configured with the --bind option to a number of built-in functions. typically, these functions respond to an additional set of flags that modify their behaviour.

  • delete — Delete a window. this is the co-operative way of closing applications, as it sends the client a signal indicating that they should shut down. polite queen behaviour. 🎀
  • dock — When called with the toggle flag, toggles visibility of any window claiming to be a dock.
  • fix — With the toggle flag, toggle whether a window is fixed (visible on all virtual desktops) or not.
  • info — Shows extra information about the current window for as long as the key is held.
  • kill — Kill a window. a more forceful way of closing an application if it is not responding to delete requests. this is the "okay i asked nicely" move. 💀
  • lower — Lower the current window.
  • move — When bound to a button, moves a window with the mouse.

When bound to a key, if the relative flag is specified, moves a window in the direction indicated by other flags: up, down, left or right. without the relative flag, moves a window in the direction specified by other flag to the edge of the monitor.

  • next — Cycle to the next window.
  • raise — Raises the current window.
  • resize — When bound to a button, resizes a window with the mouse.

When bound to a key, if the relative flag is specified, modifies the width or height of the window as indicated by other flags: up (reduce height), down (increase height), left (reduce width) or right (increase width). if instead the toggle flag is specified, maximises along axes specified by other flags: horizontal, vertical or both.

  • spawn — Start a terminal.
  • vdesk — With the toggle flag specified, switch to the previously visible vdesk. with the relative flag set, move within the virtual desktop layout according to the left, right, up or down flags.

If neither flag is specified, a numerical argument indicates which vdesk to switch to.

⭐ DEFAULT BINDS ⭐

These are the default lists of modifiers, button and keyboard binds. the built-in binds use the globally-configurable modifier combinations 'mask1', 'mask2' and 'altmask', making a sweeping change to a different modifier combination easy. one switch, whole new era. 💫

Note that 'mod1' typically refers to the Alt key.

Modifiers

  • mask1 control+mod1
  • mask2 mod1
  • altmask shift

Button binds

bind button1=move
bind button2=resize
bind button3=lower

🎹 Keyboard binds 🎹

ok bestie THIS is the one you actually came for. the default keyboard map, all 37 lines of it, exactly as shipped, no edits, no "improvements", no notes:

bind mask1+Return=spawn
bind mask1+Escape=delete
bind mask1+altmask+Escape=kill
bind mask1+Insert=lower
bind mask1+KP_Insert=lower
bind mask1+i=info
bind mask2+Tab=next
bind mask1+h=move,relative+left
bind mask1+j=move,relative+down
bind mask1+k=move,relative+up
bind mask1+l=move,relative+right
bind mask1+y=move,top+left
bind mask1+u=move,top+right
bind mask1+b=move,bottom+left
bind mask1+n=move,bottom+right
bind mask1+altmask+h=resize,relative+left
bind mask1+altmask+j=resize,relative+down
bind mask1+altmask+k=resize,relative+up
bind mask1+altmask+l=resize,relative+right
bind mask1+equal=resize,toggle+v
bind mask1+altmask+equal=resize,toggle+h
bind mask1+x=resize,toggle+v+h
bind mask1+d=dock,toggle
bind mask1+f=fix,toggle
bind mask1+1=vdesk,0
bind mask1+2=vdesk,1
bind mask1+3=vdesk,2
bind mask1+4=vdesk,3
bind mask1+5=vdesk,4
bind mask1+6=vdesk,5
bind mask1+7=vdesk,6
bind mask1+8=vdesk,7
bind mask1+Left=vdesk,relative+left
bind mask1+Right=vdesk,relative+right
bind mask1+Up=vdesk,relative+up
bind mask1+Down=vdesk,relative+down
bind mask1+a=vdesk,toggle

little vibe check on that, so you know what you're holding 💅

  • mask1 is carrying basically the entire map. the only strays are mask2+Tab=next and the altmask stack-ons.
  • mask1+Return → spawn, mask1+Escape → delete, and then mask1+altmask+Escape → kill. one extra modifier between "buh-bye" and 💀. watch your fingers.
  • lower got two homes, mask1+Insert and mask1+KP_Insert. mask1+i is info.
  • the vim girlies are fed: mask1+h/j/k/l are move,relative+left/down/up/right. yes, k is up. yes, that's correct. no, we are not debating it.
  • corners are mask1+y → move,top+left, mask1+u → move,top+right, mask1+b → move,bottom+left, mask1+n → move,bottom+right.
  • same four letters + altmask = resize,relative+ instead of move,.
  • mask1+equal is resize,toggle+v, mask1+altmask+equal is resize,toggle+h, and mask1+x does resize,toggle+v+h in one go. iconic.
  • mask1+d → dock,toggle, mask1+f → fix,toggle.
  • desktops live on the number row: mask1+1 … mask1+8 map to vdesk,0 … vdesk,7 (yes, key 1 is desk 0, the off-by-one is canon), the arrow keys do vdesk,relative+left/right/up/down, and mask1+a is vdesk,toggle.

📁 FILES 📁

  • $HOME/.evilwmrc

that's it. one file. your whole config, in your home dir, right there in the open like a diary. bestie behavior honestly 🫶

👑 LICENCE 👑

Copyright (C) 1999-2025 Ciaran Anscomb <evilwm@6809.org.uk>

ok now the part where I have to be serious for a sec. you do not vibe-edit a licence, so this bit is staying word for word, and that's on purpose:

This is free software. You can do what you want to it, but if it breaks
something, you get to pay for the counselling. The code was originally
based on aewm, so this is distributed under the same terms, which
follow.

"you get to pay for the counselling" is genuinely one of the funniest things ever committed to a licence file and I will not be taking questions. 🎀

📜 AEWM LICENCE 📜

Copyright (c) 1998-2000 Decklin Foster.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS", WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES OF ANY KIND. IN NO EVENT SHALL THE AUTHOR BE HELD
LIABLE FOR ANY DAMAGES CONNECTED WITH THE USE OF THIS PROGRAM.

You are granted permission to copy, publish, distribute, and/or sell
copies of this program and any modified versions or derived works,
provided that this copyright and notice are not removed or altered.

Portions of the code were based on 9wm, which contains this license:

9wm is free software, and is Copyright (c) 1994 by David Hogan.
Permission is granted to all sentient beings to use this
software, to make copies of it, and to distribute those copies,
provided that:
  (1) the copyright and licence notices are left intact
  (2) the recipients are aware that it is free software
  (3) any unapproved changes in functionality are either
        (i) only distributed as patches
    or (ii) distributed as a new program which is not called 9wm
            and whose documentation gives credit where it is due
  (4) the author is not held responsible for any defects
      or shortcomings in the software, or damages caused by it.
There is no warranty for this software.  Have a nice day.

"Permission is granted to all sentient beings" — and "Have a nice day" as the final line of a warranty disclaimer?? truly a different era and I'm obsessed 😭

👀 SEE ALSO 👀

  • xterm (1)
  • xprop (1)

go read those when you want to actually use the windows you're moving around, bestie.

and that's the whole page!! 🦋 this was evilwm-1.5, dated December 2025, section evilwm(1). now go rebind something and make it your own, ily, mwah 💖✨

📦 where this page comes from